https://drewdevault.com/2018/05/13/scdoc.html – possibly this would fit better with the goals of Kakoune?
I’ve always thought why manpages are not simple plaintext? the _underline_, /cursive/, *bold* notations exist for years going way before Unix birth date. If you need to generate beautifully rendered pages or PDFs that’s not feasible, but for simple terminal manual pages I don’t know if you need more than that. I also think that a good manual should have the information necessary to understand the tool, not beautiful look. Otherwise we would use LaTeX
.
The HTML document model is pretty generic, so Markdown can get away with being a pretty generic pidgin. People who have written HTML long-hand (or not-very-simplified HTML variants like phpBB’s BBCode) fall in love with Markdown because 90% of the time it just does the right thing.
The problem comes when people try to extend the Markdown model to more complex document models, like DocBookXML, or mdoc, or whatever. Then there’s a few basic approaches you can take:
- Keep the markup simple, at the cost of making poor documents in the target format (scdoc, whatever syntax HN comments use)
- Keep the markup simple for simple things, but more complex things require much more complex markup (AsciiDoc, maybe BBCode)
- Keep the markup regular and consistent, at the cost of simple things feeling over-complicated (ReStructuredText)
I’m probably always going to use Markdown for any kind of HTML prose, but for technical writing I’d probably go for ReStructuredText, and for manpages honestly mdoc is not nearly as complex as people make out, and it’s really easy to test.
Unix was originally sold as a document typesetting system, and came with binders full of printed-out documentation, generated by that typesetting system (troff). The fact that the source code for those documents was also installed, and could be read without printing it out, was more of a happy bonus, it’s definitely not how the documentation was intended to be read.
1 Like