Hacker News Reader

Comment by zdw | Hacker News Reader

I feel like DocBook is in a bad place compared to alternatives - it's to esoteric, too hard to write, and then there's the fact that it's XML.

TeX and friends are first class for paper docs and publication, but given their pre-web origins don't work well in that medium.

Markdown is just too limited and primitive for anything more than a blog post or basic README file - no captions on figures, hyperlinking to headings/sections isn't formalized, etc.

I tend to think that Sphinx + ReStructuredText makes the right balance in terms of publishing targets, and with all of Python, ReadTheDocs, and the Linux Kernel making the same decision, it seems like the right one. Intersphinx is pretty sweet if you have to link multiple sites together.

MS Word and Wikis can go die in a fire.

View on HN

I have seen some places that use asciidoc as the interface, and then transpile asciidoc to docbook by using custom transformations. This works really well.

It's a huge PITA to write anything but basic markdown for books or long articles (30+ pages) that you need to output in multiple formats (e.g. one source to PDF, epub, and html) to be honest.

What I'd love to see is a general-purpose human readable format for documents. Markdown is handicapped by being (effectively) an HTML pre-processor for a tiny subset of HTML. Poor support for math, no captions, but more importantly very little semantics. You can often write a valid Markdown document that does what you want, but any significant information in the document (like "Author: My Name") just becomes part of the resulting HTML, not something that has any meaning in the Markdown spec.

RST strikes me as rather domain specific with its emphasis on technical writing, and IMO it also suffers from being intended as a preprocessor (the ugly link syntax for example).

I'm probably asking for too much, but what I'm looking for is something semantic enough to write a book in, but with viewing as plain text as the primary intended output. Gemini's gemtext format has very different goals, but it captures what I mean by "text as the primary intended output" very well.

> Markdown is just too limited and primitive

On the other hand, if you think of Markdown as just being a preprocessor, not a format that has to have everything built in, it's really not that bad if your renderer is good. For example: python-markdown has built-in plugins that make everything much nicer: meta, extra, and smarty are the one's I'd recommend. 'yafg' is a plugin that solves the figure support problem. 'markdown_vidify' allows embedding HTML5 videos.

I’ve heard people talking about reStructuredText as having ugly link syntax before, and I’m curious what specifically it is that you’re finding ugly. Are you talking about inline links, `link text <href>`_? In that, certainly I think the underscore was a mistake, though I’d say it’s good apart from that (angle brackets are good for URL delimition matching a long-standing historical convention as well as not using valid URL characters; parentheses as in Markdown are fundamentally particularly bad because parentheses are valid URL characters, so you can’t just drop a valid URL in willy-nilly). Or is it the reference style, with text_ or `link text`_ followed by .. _text: href or .. _link text: href? The reference definition is definitely… syntactically idiosyncratic, even if it’s quite consistent through the language.

Good question! Keep in mind that I'm not a regular rST user, so I'm not the best person to make complaints about it.

I dislike both the inline links and the footnotes. I agree with you about the underscore and that is the main aesthetic critique. I also rather dislike the use of backticks here, though. They have the smell of code especially with the nested <href>. If you have to have inline links I think Markdown's aren't that bad, especially because they lend themselves to easily adding inline images (exclamation point before the opening bracket). But both clearly function as markup, which is what would make them inappropriate for my envisioned format that is intended to be primarily rendered as plain text.

Additional complaints about rST syntax are the mixture of semantic document elements with code. For example rST has a glossary directive (great!) but unfortunately it is (and reads as) a piece of code (just like literalinclude or highlight).

In some ways what I'm looking for is even more constrained than Markdown. For example,

    # GLOSSARY:

is valid markdown, but I'd like a standardized format that imputes semantic meaning to constructs like this and has rules for how the glossary section of the document must be formatted. The result would (hopefully) read without any hint that it is markup, but on the other hand make it possible to convert the document to PDF, HTML, EPUB, etc.

A format intended to be read as text probably wouldn't have inline links at all. A cleanly readable syntax for footnotes would probably make more sense, and with the proper semantics, a viewer / converter for the format could convert the link to inline if desired.

Interesting. I’m curious in significant part because I’m in the process of designing a lightweight markup language of my own, in which I am caring a lot about the ergonomics of the source text for reading, writing and tooling (I’d say all existing LMLs fail significantly on at least one of those).

Your remarks against inline links surprise me, because I am rather inclined to approve of inline links, because otherwise the href tends to get too far separated from the place it is, yet it is regularly important to the understanding of the text. Similarly endnotes as widely practised on the web (extremely commonly misnamed footnotes) are horrible for reading, as they’re in a completely different location, requiring jumping back and forth—whereas in the source, there’s a fair chance you wrote the footnote near the source. I’m rather partial to side notes, and have in the past set such a thing up in Sphinx so I could write the |main column content| like that, followed by `.. |main column content| sidenote:: the note text` below. Meanwhile on my website, currently Zola-powered, I write {{ sidenote(src="main column content", note="the note text") }} which invokes a shortcode that transforms it into the required HTML. Anyway, enough of that.

I despise Markdown’s inline link syntax, because it has no rhyme or reason: square brackets around the text, then parentheses around the href and possibly toooltip. Not only are parentheses around the link terrible due to being URL characters (thereby complicating the parser in an attempt to mitigate the damage by allowing matching parentheses, yet still requiring something beyond a simple URL serialiser for unmatched parentheses), the entire […](…) syntax is quite unlike anything used by anything else, and devoid of any rationale (you could just about describe the URL as parenthetical to the prose, but the claim is weak at best and perhaps harmed by the lack of space before it, though that would be a problem of its own)—people that don’t work in Markdown extremely extensively get the order wrong ((text)[href], [href](text) or (href)[text]) fairly regularly. As for Markdown’s inline image syntax, it’s possibly even more atrocious by virtue of being utterly opaque—it’s something that has to be taught and can’t be guessed, and is surprising when encountered even when you see that it is an image.

In my own markup language (code name T), I currently have [link text <href>] as the inline link syntax, quite similar to reStructuredText’s, but using matching outer delimiters. ([link text] <href> or word <href> are almost tempting, but definitely conflict with other parts of my goals.)

With your glossary heading, you may be interested in AsciiDoc (which incidentally for this submission has DocBook semantics); it’s big on the sort of semantics it looks like you may be interested in. (I’m not so fond of quite a bit of its syntax, but its semantics are robust like reStructuredText’s.) https://docs.asciidoctor.org/asciidoc/latest/sections/glossa... is its glossary stuff. Note that it requires more than just a heading with the text “glossary”, which would be problematic to operate on for linguistic reasons (though you could perhaps separate such style commands in a CSS-like way, `section:heading("GLOSSARY:") { role: glossary; }`).

There are dozens of Markdowns flavors:

Github Flavored Markdown Stack Exchange Flavored Markdown Markdown Extra LiaScript MultiMarkdown LeanPub Flavored Markdown Markua Python-Markdown Kramdown

Even that is enough to show that Markdown is bad by design. But when you actually use it for any serious document, you face the bad design and struggle with the "easy" tool :)

> there's the fact that it's XML

DocBook was SGML for most of its lifetime, and only became XML-only with the newest version 5, I believe. So you can use custom Wiki syntax if your concern is XML's verbosity and unfriendliness as an authoring format.

Other than that, I don't have a particular bad experience using DocBook for the one conference paper where I used it. Especially compared to LaTeX' limited options for rendering copies to HTML, I'd say DocBook is far better, like you say.

Also, DocBook is supported by pandoc.

It needs an editor like https://www.xmlmind.com/xmleditor/docbook_editor.html

I thought DocBook was for technical books whereas Sphinx + ReStructuredText was for technical documentation?

Reply on news.ycombinator.com