3 ms·

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

by zdw 5y ago

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.

bryanrasmussen 5y ago
I thought DocBook was for technical books whereas Sphinx + ReStructuredText was for technical documentation?
tannhaeuser 5y ago
> 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.
BossingAround 5y ago
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.
bscphil 5y ago
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.
- chrismorgan 5y ago
  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.
  - bscphil 5y ago
    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.
qwertyzxcvmnbv 5y ago
It needs an editor like https://www.xmlmind.com/xmleditor/docbook_editor.html https://www.xmlmind.com/xmleditor/docbook_editor.html

by zdw 5y ago

bryanrasmussen 5y ago

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

tannhaeuser 5y ago

> 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.

BossingAround 5y ago

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.

bscphil 5y ago

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.

chrismorgan 5y ago
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.
- bscphil 5y ago
  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.

qwertyzxcvmnbv 5y ago

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