https://github.com/marcelgarus/semdoc

A document file format that allows writers to focus on the content solely and empowers readers to adapt the appearance to their devices and needs.
https://github.com/marcelgarus/semdoc

document file-format semdoc

Last synced: 8 days ago
JSON representation

A document file format that allows writers to focus on the content solely and empowers readers to adapt the appearance to their devices and needs.

• Host: GitHub
• URL: https://github.com/marcelgarus/semdoc
• Owner: MarcelGarus
• Created: 2020-04-04T11:32:56.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2023-04-20T18:29:26.000Z (over 1 year ago)
• Last Synced: 2024-09-17T23:58:15.808Z (about 2 months ago)
• Topics: document, file-format, semdoc
• Language: Rust
• Homepage: https://semdoc.dev
• Size: 238 KB
• Stars: 10
• Watchers: 4
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        


## SemDoc – Semantic Document

SemDoc is a document file format that allows writers to focus on the content solely and empowers readers to adapt the appearance to their devices and needs.

### Why yet another file format?

There are many great tools for writing documents: Google Docs, Word, Notion, Markdown, Latex, and many more.

But for *distributing* documents, we're pretty much stuck with PDF.

SemDoc aims to change that.

**What's wrong with PDF?**

PDF is excellent for print-quality content:

If you want to print something or publish a design brochure, it's a great fit.

But I'm not too fond of PDF for general content consumption:

* **It organizes everything into pages.**

  It's not like scrolling is a particularly new invention.

* **The layout is entirely static.**

  I refuse to believe that putting my phone into landscape mode just to read a PDF without continually scrolling back and forth is the best user experience we can come up with in the 21st century.

* **Advanced features are hard to use correctly.**

  Tabbing through input fields or copying text with accents rarely works.

  These symptoms indicate an issue with the format itself.

* **Dark mode?** Anyone?

Fundamentally, PDF gives most of the control to document *creators*, leaving none to readers.

In contrast, SemDoc follows these principles:

* **Be a compile target.**

  It doesn't aim to be readable to humans or be edited by hand; instead, it's an efficient binary format.

  Like PDFs, you compile other formats to it.

* **Be purely semantic.**

  It contains no syntax information, only semantic information.

  Writers declare *what* to display, readers control *how* to show it.

* **Be extensible.**

  Over time, the SemDoc format can be extended.

### Relevance

Some might think, "documents are going to be cloud-first anyway. Consumers don't need file formats anymore; they'll collaborate online."

That's probably true for most cases.

But I'd argue there will always be a use-case for immutable atomic instances of documents to be sent.

Immutability makes them legally binding.

Latency might forbid you from collaborating with people living on Mars.

**The concept of transferring a file is straightforward to understand for us humans because files are like things.**

---

[Here's an explanation of the format.](format.md)

## Roadmap

- [x] Write vision

- [x] Implement base of the format

- [x] Make format debuggable

- [x] Document format

- [x] Implement block-level optimizations

- [x] Support blocks with more than 255 children

- [x] Add more blocks

- [ ] Improve the quality of Markdown to SemDoc converter

- [ ] Use Reference atom

- [ ] Implement document reader in CLI

- [ ] Implement document reader in Flutter

- [ ] Optimize performance

- [ ] Put process in place for proposing new blocks

- [ ] Implement intermediary language for editing SemDocs

## Block ideas

- [ ] pixel images

- [ ] vector images

- [ ] redacted

- [ ] comments

- [ ] signed

- [ ] secondary

- [ ] more info

- [ ] links

- [ ] highlighting

- [ ] quote