How does Ken compare to document generators like Sphinx or AsciiDocs? #4
Description
First, I haven't explored ken past reading the github.io page, so I am not sure of the scope of it.
I have mostly avoided using reStructuredText for projects, preferring the simplicity of markup, but it is the standard for the Python community. I also looked at ascii docs some time ago when comparing various types of markup languages.
As for markup languages
- SGML
- XML
- HTML
- XML
- wiki markup
- creole
- mediawiki
- commonmark
- github markup
- markdown
- asciidoc
- reStructuredText
- yaml
It would be nice to understand where they fall short, and how Ken improves on them.
(I really don't like markdown. The cutesy name implies that it is not just another kind of markup language. And, even though it supposedly had a definition, none of the implementations seem to follow it exactly.)
My use of plain text with embedded markup goes back to the beginning days of email. Email was nothing but text back then. In fact almost everything was just text files. We added some simple and obvious markup to the text to indicate semantics that added to the plain text. (Emoticons were an outgrowth of that.)
Some examples.
Starting a list item with a '-' was so obvious because everyone did that on paper already.
Using '*' around the item to indicate emphasis, or underlining headings was also obvious.
Then came HTML and it added links and a much more complicated and necessarily rigid syntax. But, truthfully in the beginning it wasn't much more that just what had been done in text email and documents with links added. Of course we know how HTML grew and conflated semantics and presentation and became a mess.
When wiki markup appeared, I felt like it was going back to simple text with semantic tagging as needed, but always trying to be readable as plain text. Of course it had to have support for links, but they were not obnoxious. Some markup has always been hard to be both readable and type-able as text. Tables are a good example.
It is too bad that there wasn't one true standard wiki markup language. Instead as the wiki idea caught on everyone had to believe that they could do it better and every wiki had their own language.
I would imagine that Wikipedia is the most used wiki in the world and they have more power and complexity in their language than most, but their are still things missing. I often wish that Wikipedia had sticky table headers so that I could scroll a long table and still see the headers. But that is just presentation. Of course sorting tables is also presentation. (Maybe presentation should just always be added and not part of the markup. But then, you cannot sort a table that has a totals row. Actually you can if the semantic meaning of the totals row is represented.)
This turned into a surprisingly long comment. My original thought was just that I did a huge comparison of wiki markup languages back in about 2003 and decided that I liked creole the best because it had the most obvious semantic meaning (bold and /italics/ and underlined).
I can't stand markdown because it had to pick non-obvious semantic markings such as bold and italics and italics. However, as you can tell I am mixing presentation with semantics as I am used to bold and italics as opposed to emphasis and strong emphasis.
The change from "original text" with underlined headings to "# heading #" does not cause a readability problem as it is almost as obvious as underlining and it allows
- easier parsing being on one line
- extends to any number of heading levels vs title with '=' under and heading with '-' under.
Unsurprisingly, wikis almost immediately added buttons and GUI presentation to allow users to see what they were typing because most of the world isn't at all technical.
And to confuse things even more, GitHub lets you choose a different markup language when you create a wiki page, but the page then must be edited with that language. To bad they didn't just use a language independent representation and allow users to set their preferred language for editing. Of course that could have caused problems because a github wiki is just a git repo and the owner can edit the files directly.
@dhh1128 I bet I gave you some things to think about with this mess. :-)