Choice of Document Formats

This document is Copyright by Shlomi Fish, 2006, and is available under the terms of the Creative Commons Attribution License (CC-by) 3.0 Unported (or at your option any later version of that licence).

For securing additional rights, please contact Shlomi Fish and see the explicit requirements that are being spelt from abiding by that licence.

There are too many Markdown dialects (e.g: GitHub's, reddit's, Stack Exchange's) each one with its own army and navy (= fragmentation and incompatibilities). Moreover, they can only be converted to XHTML.

All that put aside, I should note that if you are thinking about using TeX or LaTeX, please re-consider. Tex/LaTeX are very convenient for generating PostScript or PDF but:

1. The only thing that can understand TeX is tex. I believe it was said much earlier than when Tom Christiansen ported that idiom to the Perl world. It is in fact much more true for TeX than it is for Perl.

2. Conversion of LaTeX to DocBook or HTML often doesn’t work quite well. Often, the tools are outdated and generate old or invalid HTML, and often they break on more than complex LaTeX. TeX and LaTeX are Turing-complete, and the syntax is incredibly problematic.

3. LaTeX has poor support for hypertext, and other PDF niceties.

4. PDF and PostScript, which are the default-and-least-error-prone TeX output formats, have relatively poor accessibility and internationalisation. For example, from my understanding Bi-directional text (mixed Arabic-English text, etc.) is rendered visually.

5. It is easier to convert semantic XHTML or DocBook/XML to LaTeX than the other way around.

LaTeX is much less verbose than DocBook/XML, but I think you can find a better format. It is is still usable for writing texts with lots of mathematical formulae, but still a very problematic format. When working with LaTeX I often get obscure TeX errors that I can’t tell immediately what exactly went wrong. In DocBook/XML it just reports that one tag is missing, or that the order of tags are incorrect, which takes me much less time to solve.

One option to convert simple LaTeX to DocBook 5/XML or XHTML is TeX4ht which works reasonably well, and there is also MathJax.

One may be tempted to use word processors such as Microsoft Word or LibreOffice Writer, and they provide the XML-based standards of ODF and .docx. However, part of the problem with them is that their conversion to output formats tends to be non-semantic if not completely non-valid, and at least in the case of MS Word, have a huge problem with maintaining compatibility of documents created with newer or older versions. As I noted in a Reddit comment, word processors are the kind of programs that are created by smart people for people who are less smart than them, because smart programmers can use text editors and markup languages. I have written a mini-essay about “Selling for people stupider than you”.

Note that in the past, I preferred using WordPerfect, as a word processor, over Microsoft Word (and later LibreOffice Writer) due to its "reveal codes" feature (but WordPerfect was not ported to Microsoft Windows in time for it to be usable). That put aside, I found Excel, Visio, and to a lesser extent PowerPoint, to be useful and usable applications. Nevertheless, I avoid using their desktop versions due to lack of portability, a non-FOSS licence, and the availability of some decent FOSS alternatives.

Going full circle now - POD is a good option if it does what you need. The Camel Book and some other perl books were written in POD. I wrote some documentation for Perl and non-Perl projects in POD. I also write some of my man pages in POD because nroff's syntax scares me.

But if you feel that you want something better, you have many options.

One final note is that DocBook/XML was problematic for using in bi-directional texts because of implementation or standard problems, last time I checked. Otherwise, its Unicode support should be very good.