You know what, while you're at it, I might as well bring it up. How about XML?
I haven't really tried writing large pieces of text in it but I am already seriously considering. All other alternatives are too complicated and have a learning curve that gets in the way of writing itself. With XML, I'd be able to define my own tags and run them by a parser later on to auto-generate indexable footnotes, and create my own ways of structuring text besides the usual ones (chapters, sections, etcetera). Has anyone tried this approach?
Professional tech writer here: We use GitHub and a tool called OxygenXML to write docs-as-code in an XML DTD called "DITA". It's a hefty IBM invention from the early aughts, but it covers every use case I've thrown at it, from small documentation sets to multi-thousand-page monsters. Supports PDF, HTML, Word, and many other output types.
DITA's so great at everything _except contributions from non-tech writers_ that half of my career has involved migrating tech writing stacks that use it to Markdown/SSGs in git repos.
DITA's benefits require a certain scale that most tech companies never achieve. And the Open Toolkit is a nightmare piece of software.
Agreed, and we use Markdown where we can. But inevitably some product manager comes along and demands tables inside tables or embedded reuse of content... and it's back to DITA.
OxygenXML makes the OT much more manageable. I haven't had to touch an OT XSL transform in a few years now. Worth every penny.
Yeah last time I touched it was during an internship 15 years ago, the few memories I recall were not enjoyment at all (however I was using LaTeX everywhere at the time).
Writing documentation as XML is powerful but not enjoyable at all I guess
I have been thinking about this seriously myself. Not with a specific existing schema like DocBook, but with a custom schema (defined by me) that I then compile to standard schemas, like DocBook or HTML.
This seems extensible to the degree that I want (i.e. semantically rich enough that you can conceivably hang any application from it). But I just can't bring myself to write in XML syntax, especially for maths.
Thanks for the feedback. Yep - we've yet to update the website. It's a waitlist, we're not launched yet. Absolutely fair criticism. It'll be updated in the next few weeks!
Well basic markdown is super useful to do stuff quickly.
Problem is when people started to build systems upon systems upon something that should not be used for more complicated cases.
Maybe not a problem because I don't care but I just see how loads of things that someone created to be "just that" someone takes without understanding and builds on top instead of understanding limitations and scope of the initial idea or system.
It is "oh it is missing a feature" - where it is "no it wasn't built to do that".
I have seen notepad in windows shipping some formatting features, I don't see that as an improvement. Notepad was notepad for purpose.
I think a good balance for a markdown syntax is something you can write nearly naturally on the fly (very low syntax needed for basic use) but can continue to mark up in more detail when you want to turn something into a complex use case (very high syntax ceiling for the complex cases). HTML+CSS almost gets there except the tags are a bit awkward for simple things like just <strong>bolding</strong> a word.
Regarding Notepad, keep in mind they dumped an entire separate app (WordPad) by merging the ability to format into Notepad. This kind of mirrors what I was talking about above: one app with a very low floor but a flexibly high ceiling when you want to go there with it rather than two separate apps you need to pick from up front.
Does org-mode have a spec? From what I've seen, org-mode is defined as whatever Emacs does. Without a spec I can't see how it's a viable format for widespread usage.
1. Spec, written after the fact, not by a core dev.
2. Live help in 'org-info'.
3. Elisp string extraction via 'M-x describe-function' and the like.
Difficulties arise from subtle inconsistencies between the three, and inability of any one to comprehend the kitchen-tool-bin jumble of low- and high-level functionality that has been added over the years.
OTOH, content display is economical of eye and finger effort, and some of the Emacs interaction features startingly powerful.
I wrote my own, use-case specific converter to expand org-format to HTML. Runs on the CL, written in Go.
Personally, I don’t see the point. Searching for markdown libraries is not hard, a good library (the same that will show up first) will show you usage instructions at the top. You can copy-paste those and be done.
Also modern JavaScript uses import, require() is very 2015. If the AI is recommending you use require() I would suggest a better one.
If 2005 text editors autocomplete made it easy to balance and indent html/xml tags and syntax highlighting like today, would JSON, Yaml, Markdown have taken off? In The Art of Unix Programming from 2003, the author states editing xml by hand is torture, hence we must invent unique text formats and parsers for the same.
I have not been able to configure an editor that makes it less painful. I think it's not just the verbosity (although that is painful) - the prefix notation makes some things inherently hard to read. MathML is almost impossible.
Ah yes, writing my notes down in css and html. My favorite!
Seriously though, every time some new hotness comes along, you don’t really have to use it or even waste your time looking at it. Markdown will likely be here after all of its derivatives are long gone.
For me the only addition to markdown I usually enjoy is mathematical typesetting like on GitHub using the inline $$ syntax or the code blocks with the language set to `math`
