This page is a companion to [featherdown], contains [#technical notes] to self, plus some [ideas for the future|#future] and a good list of [§#references].
§:=featherdown
## Technical Notes
A featherdown page is read in two main steps: determine [§#layout] and replace [§#inline elements].
### Layout
First, all layout elements are isolated.
Technically, each newline is assigned to a type; consecutive types are then compared using some precedence rules to establish the precise boundaries.
||||||||||||||||||||||||||
[§#headings]
[§#tables]
[§#grids]
[§#figures]
[§#quotes]
[§#lists]
[§#paragraphs]
[§#code blocks]
[§#polycolumns]
||||||||||||||||||||||||||
### Inline elements
Within each layout element, all inline references are replaced by the result.
Technically, a sequence of regular expressions is compared against each "line" or "cell", until no more matches are found.
Matches are immediately protected to avoid conflicts, while further matching occurs recursively for any "sub-cells" within each match.
Finally, all protections are directly replaced with the respective results.
### Preprocessing (optional)
Optionally, a pre-processing step occurs before determining layout, whenever in-page [§#definitions] are detected.
Technically, [§#comments] and [§#blanks] are seen as invisible layout elements, but one can imagine them vanish during preprocessing.
### Design considerations
#### Interoperability with HTML
HTML mingles naturally, as the output of featherdown is just more HTML code.
Lines that start with an HTML tag will only be parsed with respect to inline elements, but their layout won't be touched.
#### Interoperability with Javascript
Naturally, javascript code takes precedence over featherdown parsing (as featherdown itself is just another javascript module).
#### Repeated symbols
Tolerating repetition is a natural solution to match //dead key// behaviour in some keyboard layouts.
Plus it is always quicker to retype the same symbol a few times than type two or more different symbols.
#### Meaningful whitespace
This emerges naturally from the requirement that featherdown plaintext be readable as is, much like markdown
### Departures from markdown
#### Intentional
[§#featherdown] intentionally differs from markdown in three major items: [§#tables], [§#links] and [§#images]:
- Images are always autodetected from the file extension, so no special syntax was needed.
- Tables resemble more Pandoc's simple table format. Because adding pipe separators is a hassle, and simple tabs are more, or at least equally visually clear. The tradeoff is nothing complex can be added inside tables.
- Links resemble more Wikipedia's markup, with the pipe as separator within single square brackets. It feels more intuitive and as a bonus uses 2 or 3 characters instead of 4.
#### Minor departures
-Italics using ´´//´´ instead of ´´*´´ (reserved for bold), also because the former symbol visually suggests slanting.
-Subscripts using ´´¨´´ instead of ´´~´´ (reserved for strikethrough)
#### Unintentional
-There is currently no nesting in blockquotes, as it seems to be rarely useful. This may change.
###Future improvements
These are areas to improve on.
####Reversibility
[Featherdown] should be reversible: the generated html output should enable reconstruction of the exact initial featherdown code, character by character.
This will allow WYSIWYG live editing directly in the browser (coming soon).
####Collisions
| :warn: Grids and Setex level 6 are colliding at the moment
In addition, some operators could collide with each other in very specific situations:
- links vs mathematical vectors
- italics vs comments
- hashtags vs atx headings vs inline links
- footnote links vs normal links
#### Standalone script
A simple script, always up-to-date, selfcontained, to add featherdown parsing to any page, optionally subsetted to specific elements rather than the whole body, optionally also with only inline-elements
### Future Features
#### Better footnote autolinking
- Autolink footnote section without special syntax, base on the actual footnotes across the document
- long form autolinks for academic-like citations ´´[#Featherdown 2022]´´
- fix the hash inconsistency ´´[2]´´ vs ´´[#2]´´.
#### Centered horizontal rule symbols
This would require injection of a particular style with the ´´::before´´ CSS pseudo-element
TENTATIVE SEPARATOR VISUAL RESULT COMMENT
´´_´´ underscore ´´_____________★_____________´´ nice
´´-´´ dash ´´-------------★-------------´´ ok too, but would clash with [§#setex] if the symbol were omitted
´´:´´ colon ´´:::::::::::::★:::::::::::::´´ ok-ish
´´*´´ asterisk ´´*************★*************´´ bad, the asterisks are too heavy, drowning the symbol
´´*´´ equal ´´=============★=============´´ nice too -- would clash with wikipedia-style headings if ever implemented
Note that the star symbol itself is not readily available in most keyboards, but emojis are available
##### Friezes
Any line consisting solely of repeated (+10) pairs of characters could be detected as a frieze.
Friezes would automatically be assigned a //css class// equal to the pair of repeated characters, allowing for further customisation.
EXAMPLE PAIR VISUAL RESULT
´´AV´´ ´´AVAVAVAVAVAVAVAVAVAVAVAVAVAVAVAVA´´
´´OX´´ ´´OXOXOXOXOXOXOXOXOXOXOXOXOXOXOXOXO´´
´´O-´´ ´´-O-O-O-O-O-O-O-O-O-O-O-O-O-O-O-O-´´
´´|-´´ ´´-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-|-´´
Each pair is identified in alphabetical order, ´´VA´´ -> ´´AV´´
#### In-table cell justification
Within cells, or at the table headers, using a combination of symbols (visually worse) would be a possible solution to the clash of tabs
ALIGN LEFT CENTRE (default) RIGHT JUSTIFY
TOP ´´<^´´ ´´^^´´ ´´^>´´ ´´<^>´´
MID (default) ´´<<´´ ´´ ´´ ´´>>´´ ´´< >´´
BOTTOM ´´´´ ´´´´
The order or quantity of these symbols wouldn't matter, only their presence.
There is another way, using the relative alignment of headers and a line separator just below them.
Finally, [§#captions] could possibly be coopted for the job.
#### Other Ideas
Buttons, perhaps using arrows to emphasise an action? ´´ Text displayed ==> Action(...) ´´, possibly enclosed in square brackets ´´[ ]´´ to use inline?
- Some way of generating fragment links for items besides headers
- citations, autoformatted
Announce section blocks somewhat resembling links ´´[[[[[[[[[[[[[[[[[[[[link here]]]]]]]]]]]]]]]]]]]]´´
Autodetect Mac/Win and display a manual toggle, for keyboard shortcuts to alternate between e.g. CMD and CTRL.
Do **not** add task lists ´´[ ] [x]´´ and other rarely used features.
Numbered lists, ´´ 1) 2) 3)´´ too.
Nested sub and superscripts; nested items in blockquotes (probably not, its awful)
Collapsible sections with summary/details
Wikipedia-style headings, using equals ´´=´´ like this: ´´======== title =========´´
Perhaps even instead of imposing particular symbols, try to autodetect depth level globally.
Direct html templates in external html files? Perhaps using a literal javascript object or a toml-like list afterwards?
Linking external libraries for math expressions, code syntax highlighting, etc...
###References
#### Syntax
These are some of the references that inspired the [§#featherdown] syntax or were otherwise good ancillary reading.
Daring Fireball's Markdown [Philosophy|https://daringfireball.net/projects/markdown/syntax#philosophy] page.author tries to keep the same "publishable as plaintext, looking good" philosophy
Markdown Guide's [Extended Syntax|https://www.markdownguide.org/extended-syntax/] and [Hacks|https://www.markdownguide.org/hacks/] A complete and well-organised (modern) markdown reference
Pandoc Manual's [Tables|https://pandoc.org/MANUAL.html#tables], [definition lists|https://pandoc.org/MANUAL.html#definition-lists] Great reference for [§#tables], especially "simple tables" (and for definition lists if added in the future). Great reference in general for all else.
Problems with [ReStructuredText|https://docutils.sourceforge.io/docs/dev/rst/problems.html] A really insightful read.
ReStructuredText [Syntax alternatives|https://docutils.sourceforge.io/docs/dev/rst/alternatives.html] Treasure trove of ideas
[ATX text format | http://www.aaronsw.com/2002/atx/intro] The reference for [§#ATX headings]
Setex Headers The reference for [§#Setex headings]
[Wikipedia Markup|https://en.wikipedia.org/wiki/Help:Cheatsheet] The reference that most inspired [§#links]
[Commonmark help|https://commonmark.org/help/] Concise markdows cheatsheet
[Markdown it|https://markdown-it.github.io/] Concise markdowns playground, with nice parallel scrolling
[EMACS Table Mode|https://table.sourceforge.net/] This table format was deliberately avoided, because it is a hassle to type unless a computer program does it for you.
[Typographical symbols|https://en.wikipedia.org/wiki/List_of_typographical_symbols_and_punctuation_marks] The reference for [§#typographic replacements]
Kevin Reid's [Keyboard|https://github.com/kpreid/keyboard-layout/blob/master/Kevin%20Reid's%20doc.txt] A shorter reference for possibly more important [§#typographic replacements]
Unicode's [Full emoji list v.14|https://www.unicode.org/emoji/charts/full-emoji-list.html] The reference for [§#emojis]
[CSS Grid garden|https://cssgridgarden.com/] The reference for [§#grids]
Sean M. Burke's [RTF Cookbook|https://metacpan.org/dist/RTF-Writer/view/lib/RTF/Cookbook.pod] An example not to follow, in particular paragraph alignment should be visually dictated by whitespace rather than a specific textual command
Outsystems [cheatsheet|https://outsystemsui.outsystems.com/OutSystemsUIWebsite/CheatSheet] Good reference of UI items
[Tom's Obvious Minimal Language|https://toml.io/en/] Good use of indentation, maybe the format could be used add frontmatter directly within the page, like in static site generators, avoiding the use of JS objects
[Math Expressions in Github|https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions] Think about whether to add inline math, and math block sections, e.g with the unused ´´º´´ operator
LaTeX's [Full symbol list|https://mirrors.up.pt/pub/CTAN/info/symbols/comprehensive/symbols-a4.pdf] ''
[Bootstrap alerts|https://getbootstrap.com/docs/4.0/components/alerts/] Condensed reference of common alerts and their usual colours, for [§#admonitions]
[RFC search|https://www.rfc-editor.org/search/rfc_search.php] A window into the very readable plaintext formatting of RFC documents, for inspiration
[Markdeep feature demo|https://casual-effects.com/markdeep/features.md.html] Powerful diagrams (and many more features)
[AsciiDoc Quick Reference | https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference] A completely different syntax with similar scope
[THE STANDARD STAGE PLAY FORMAT|https://www.caryplaywrightsforum.org/wp-content/uploads/2012/07/CPF_play_formatting2.pdf] Traditional screenplay format, possibly a worthwhile addition to a special section
Márton Visnovitz's [Comparison of Markdown Flavours|https://gist.github.com/vimtaai/99f8c89e7d3d02a362117284684baa0f] Easy reference to the most consensual features in most Markdown-likes
[Templating in Python|https://wiki.python.org/moin/Templating] Reference to major templating approaches and engines, from a Python perspective
[Micromark Readme|https://github.com/micromark/micromark#examples] Describes how a markdown parser was made (used in [MDX|https://mdxjs.com/blog/v2/])
[MDX v2|https://mdxjs.com/blog/v2/] A format that mixes markdown with JSX, with some interesting new ideas like javascript expressions
#### Live editing
Specific references for upcoming live editing functionality
Wikipedia's [Visual Editor|https://en.wikipedia.beta.wmflabs.org/w/extensions/VisualEditor/lib/ve/demos/ve/desktop-wikimediaui.html] Wikipedia's Visual Editor, deployed in 2015
[Webflow editor|https://webflow.com/] Live HTML editing
[Tiddly Wiki|https://tiddlywiki.com/] A live-editable notebook "for capturing, organising and sharing complex information"
[TinaCMS|https://tina.io/] A Content Management System whose core feature is live editing
[Wordpress Gutenberg editor|https://wordpress.org/gutenberg/] Latecomer visual editor for Wordpress sites
[Microsoft Word|https://wikipedia.org/wiki/Microsoft_Word] Good old live editing tricks, sadly never really useful for HTML
[Linking urls to VSCode|https://code.visualstudio.com/docs/editor/command-line#_opening-vs-code-with-urls] Source warping, the next-best alternative to live editing
[Folding Text|https://www.foldingtext.com/] Some interesting interface choices
[GrandView Outliner|https://welcometosherwood.wordpress.com/2009/10/10/grandview/] Apparently an historically beloved program, ahead of its time. Maybe something could be learned by looking deeper into it?
Quill [compared to other rich text editors|https://quilljs.com/guides/comparison-with-other-rich-text-editors/] Featherdown live editing overlaps partially with rich text editors, so it's useful to know what they do well
Bret Victor's [Tangle|http://worrydream.com/#!/Tangle] More advanced reactivity, possibly to be added to code elements to close the feedback loop
Douglas Engelbart's [Mother of all demos|https://www.youtube.com/watch?v=yJDv-zdhzMY] (1968) The first text editor, among other pioneering ideas
[Windows Shortcuts|https://support.microsoft.com/en-us/windows/keyboard-shortcuts-in-windows-dcc61a57-8ff0-cffe-9796-cb9706c75eec] A good reference for shortcuts
[Ace editor|https://ace.c9.io/build/kitchen-sink.html] A good reference for expected behaviours and ideas
[Zed Editor CRDTs |https://zed.dev/blog/crdts] and [Investment Pitch|https://github.com/rootvc/investment-memos/blob/main/zed.md] Interesting read; plus a comparison of editors from their perspective
[Potluck: Dynamic documents as personal software|https://www.inkandswitch.com/potluck] by [Ink and switch|https://www.inkandswitch.com/] Text documents that are user interfaces (using pattern "searches", on which computation is made, displayed on a separate overlay layer)
[Calculist|https://www.kickstarter.com/projects/524190637/calculist/description] by Dan Allison Inline calculations via ´´[=]´´ and dollar-variables for self-reference/context