published
updated
I think I will call it "IncDown" (Incremental Notes Markup) mostly because these are habits I've already developed and take inspiration from a few different places. I'm not looking to write a book, but mostly to integrate other services into a plaintext format, and write my own notes. I write notes about many things, in many ways, but these are enough tools for me to generate my website, and perhaps other services using just plain text files. Markdown was too limiting, ReST had an unfamiliar syntax, and AsciiDoc was too complicated.
In the previous log I try to ensure strict parsing criteria while still keeping the format simple. I've built this around my already existing workflow, so I'm hoping not to change that. This file is itself written in IncDown.
What makes IncDown different is it's notion of "sections". Sections through line breaks allow for psuedo-immutable note taking. I say pseudo because there's nothing stopping you from updating old notes, but this is a simple method allows me to keep timestamped notes.
A single note may optionally be made up of "sections". Each defined using a line break. Each section inherits from the top of the stack section (the most recently created section), and further sections will override any data present in the "top of the stack" section.
I received a lot of recommendations when asking about building a parser for my language, and I also have some ideas on which technology to build on given my goals. I also looked into how markdown parsers are written to get some idea of what I'm getting into.
Some things I'd like to unlock through parsing:
- LSP (in a similar vein to zk)
- NVim highlighting
- Telekasten fork that understands this format
- Pandoc conversion
- Static Site Generation
- Task warrior integration?
- Shaarli / Grasp / Wallabag / Kobo integration
- rofi / fzf interfaces
Some of the suggestions include:
- ANTLR
- Combinatory parsers
- Write one from scratch
- PEGs (???)
- Tree Sitter
- Pandoc's Lua parser
I'm still tossing up between what to do about todos and taskwarrior. I could go the taskwiki route of using taskwarriors filtering in headers. I already have integration with notes about tasks. I'm not really sure taskwiki style integration is something useful to me, since it isn't something I've used in a long while. Creating a split and running taskwarrior-tui in it with slightly enhanced UI, and then perhaps a little integration (creating notes out of tasks, and then linking against those, basically running task-note on them) would be far more useful I think. Still would be nice to have highlighting support for todos, despite not really using them anymore in plain text notes. I say that, but then again, my most frequent note at this time is basically a todo list. So, hmm, something to think about some more 🤔
The other thing I've been thinking about is clickable headings. I like the idea of them, but I don't use them yet. For this reason I don't think I'll implement them. I wonder about them because my notes have been getting longer now that they're logs. Seeing backlinks from specific sections seems useful and fairly straightforward. I suppose clickable sections would not be too difficult. It also avoids the naming problem which can be caused with headers. Sections are automatically numbered, visible only to the parser.
It seems like through this project I can realize some of my older ideas around yaad.
%title Notes on Notes (My plaintext format)
arbitrary Metadata defined at the start of the file, or after a line break order doesn't matter %attribute value links, slugs, etc Standard metadata includes:
- title
- date
- update
- link
- tags
Metadata is additive within sections, defining multiple links or updates turns meta data into an array
Paragraphs
Separated by 1 new line character (does this make parsing harder?)
Headings
surround headings with the = character. must be at the start of a new paragraph. 4 levels, more =, bigger heading
should heading be clickable? how do we define that?
Line breaks
At least 5 consecutive - characters followed by a new line
must be at the start of a new paragraph?
linebreaks define a section, each note can have multiple sections, and each section can have it's own metadata. section metadata overrides note metadata, otherwise sections inherit from notes
Lists
use # for numbered lists and - for unordered lists
tab for nesting lists
i'd like it to be followed directly under the heading, but that might be tricky to parse
Bold
surround words with *
Italics
surround words with
Monospace
surround words with `
Strikethrough
surround words with ~
Quotes
starting a paragraph with > makes it a quote
starting every new line with a > also makes the entire block a quote (it's still just one paragraph)
they may be optionally indented for plain text visual distinction (no change to parsing)
Annotations / Highlights?
Images
Thinking of adopting markdown format
Footnotes
Thinking of adopting ReST notation [#] for auto numbered footnotes, [1] for specific numbered footnotes
footnote values can be defined through `%footnote [1] Some footnote stuff`
the short hand ! footnotes ! to end of the section or note is also permitted
if not formatted as a list each new line will denote a new footnote
Can numbered footnotes reference footnote metadata across sections?
A reference to an automatically numbered footnote in a section that does not have any footnote metadata will...?
- parse error?
- link to the first automatically numbered footnote metadata from any section?
Incremental note-taking Generally immutable, update-logs Since metadata is associated per section, each section can have it's own %update, %footnote or %tag metadata to work on Tags Surround words with : Tags an ease of use around the %tag metadata Internal & External links internal links use double [ ] notation allowing also named links using the | character external links use markdown notation text Dead Links?? i'd like it if at least internal links were verified to exist in some way, but i'm not sure if that should be the parsers job Code blocks code blocks must be fenced by the triple { character they may optionally take a language for highlighting immediately after opening the triple fence
mermaid?