# 2010-06-30 LaTeX vs. Docbook

I installed both a Docbook and a !LaTeX tool chain on my laptop recently. I’ve used !LaTeX for my thesis – nearly fifteen years ago. I remember forgetting more and more about it in the years that followed until I finally decided that it was just easier to write stuff on a wiki, work on the CSS stylesheet, and print to PDF if required. I got curious again and decided to make an experiment:

1. Using my own wiki – which I like because I use it every day and know how to change it
2. Open Office – which I don’t like because it’s user interface is very similar to Microsoft Word
3. Docbook – which I don’t like because I need to write XML which is verbose and ugly
4. !LaTeX – which I don’t like because it’s arcane and by the time I need it again I have forgotten 90% of everything

Here’s how it went: I quickly wrote up some stuff using my wiki. Getting it ready for the web took a few minutes, maybe half an hour of fiddling with CSS; I’m assuming I can just keep this CSS for the next time I need to convert one of my wiki pages to PDF. On the other hand, there are many things it doesn’t do: hyphenation, orphan protection when paginating, quick and easy floating boxes and images (it always needs a lot of CSS fiddling).

Using Open Office, things went just as quickly. I’m not sure I’ll be able to reproduce the exact output when I look at making my next PDF file, but it was more or less intuitive. Installing and using the Behrens-Schrift font by Dieter Steffman was trivial. The file doesn’t use quite the same font and it’s landscape instead of portrait, but my conclusions are – I hope – independent of these small differences.

Docbook was a pain to setup, but at least there were some books available online. It turns out that the one book that explains all the tags is a dry technical reference that is practically unusable when you’re starting out. When I looked at the output, I realized how tricky it was to fiddle with it. The large table at the beginning needs some more space between the cells, the four smaller tables need to be more compact. I found XSLT fragments that allowed me to set the padding for all tables, but didn’t figure out how to do this for one table only. If you look at the source file (which I edited with nXML Mode and Emacs), you’ll note that looking at the table markup is a pain. I wasn’t sure how to have two columns or floating tables for the four compact tables, so I nested tables. The markup got a lot worse. The output looks good, so that’s a plus.

LaTeX was easy to setup because my GNU/Linux distro already comes with excellent packages. LaTeX documentation for beginners, however, is hard to find. Where do I learn about the basics? I see that the texlive-doc-en package has a “gentle” document somewhere. Maybe someday! I fell back to my “!LaTeX Einführung Band 1” by Helmut Kopka – the second printing, 1996 – it has a price in Deutsche Mark instead of Euros, that’s how old it is. I was surprised to see how ugly the table turned out, and I have no idea on how to improve that. The source doesn’t look too hot either. Very cryptic. (I edited it using AUCTeX and Emacs.)

Conclusion?

I will be using Open Office! ⚠

It hurts my markup sensibilities, but if I want to get stuff done, I can’t waste it on Docbook and !LaTeX.

Update: I returned to rst2pdf again and tried it. It took me quite a while to get the font importing right. But I think it finally worked! The command used: rst2pdf chargen.rst -s style.json --font-path ~/.fonts (the font-path is where I installed the fonts I got from elsewhere).

Suddenly I’m no longer sure. ReST seems quite a viable solution. And I've started playing around with the style sheet... Not bad The only question I could not answer was how to center the first column of my tables.

Update: I’ve returned to LaTeX in 2013.

Have you tried txt2tags? It’s easily my favourite light text formatting system and converts cleanly to pretty much everything including LaTeX, html and MediaWiki. This makes it an ideal “write once, publish anywhere” format.

To create a .pdf, use

txt2tags -t lout file.t2t lout -Z file.lout > file.pdf

Easy!

greywulf 2010-06-30 17:50 UTC

Surprising verdict. I thought for sure you’d go Wiki. At least you were impartial: Seems you’ve consistently held a strong bias against OO.org and it still won the shootout.

AaronHawley 2010-06-30 19:50 UTC

As for txt2tags and similar formats: I suspect that they won’t do for the kind of documents I’d like to typeset – it’s a wiki-markup but not quite. Lightweight markup languages like Markdown, Textile, or Creole still have no hyphenation and final layout happens in a target environment like HTML/CSS or !LaTeX – while that solves the hyphenation issue it just returns me to the issues I have with !LaTeX itself: If I want to fiddle with it, create new document classes, new styles, understand images, positioning, pagination, table formatting, then I have to understand the arcane intricacies of !TeX. Given that choice, I think I’d rather use my own wiki for these situations.

AlexSchroeder 2010-06-30 22:40 UTC

The canonical beginner text to LaTeX is the (Not So) Short Introduction to LaTeX. Though I have found TUGIndia’s LaTeX primer very useful. LaTeX does have a bunch of neat packages that sort of bring it into mainstream typesetting (as opposed to academic publications). TeXlive has made it easier to manage various packages. But to overrule LaTeX’s idea of what is right demands you to get your hands really dirty.

Personally, I just type in org-mode and publish in HTML or PDF (via LaTeX).

Have fun with Openoffice. Damn thing needed Java for macros when I last used it.

AlokSingh 2010-07-01 03:03 UTC

Ever considered using something like LyX? I wrote my diploma thesis with that one the results were really impressive. Its still LaTeX in the end so I dont know if the table would look better but you at least dont have to remember any cryptic tags and whatnot…

– Florian 2010-07-01 07:12 UTC

I’m trying to reformat this !LaTeX document… This could be an interesting alternative. But after searching for quite a while I was unable to pick an arbitrary font for the title, for example. I guess that makes sense given that !LaTeX requires some setup before new fonts become usable to the system.

I decided to give rst2pdf another try. Emacs comes with Table Mode which allows me to edit rst grid tables. It doesn’t look bad at all! So now I wanted to try to font embedding. I have trouble understanding the rst2pdf stylesheet. The following no longer produces errors, but appears to have no effect.

{
"embeddedFonts" : ["Blackwood Castle"],
"parent": "normal",
"fontName": "Blackwood Castle",
"fontSize": 18,
"keepWithNext": true,
"spaceAfter": 6
}
}

The manual provides the following as an example: ["heading1" , { ... }] which results in an “non-string key” error. I noticed I didn’t have fc-match available and reinstalled fontconfig on this Mac OS 10.4 – which now results in a different error. Whenever the stylesheet contains the embeddedFonts directive, I get the error “findfonts.py:317 Error registering font: !VeraBd from /usr/X11R6/lib/X11/fonts/TTF/!VeraBd.ttf” – ugh. And of course my fonts are not in the X11 directory… Maybe I’ll try that again on my laptop running Ubuntu.

AlexSchroeder 2010-07-02 09:00 UTC

I discovered that what I am really doing when trying to select a technology is avoiding writing because tech is fun. :D Pick one.

The time I wasted proves him right!

AlexSchroeder 2010-07-02 11:41 UTC

Updated the main article with rst2pdf results…

AlexSchroeder 2010-07-04 03:24 UTC

This is definitely not the right way to deal with DocBook. The point of DocBook is to deal with it using some IDE that helps you as you go along. I am pretty sure Emacs already has an extension to help deal with DocBook markup.

In some sense, if you have trouble with LaTeX/DocBook, the problem is with you. LaTeX, which I am versed in, is very much about helping the user, the terseness of which is because it is in high demand. It is appalling that you had difficulty finding good documentation for it, since it is one of the best documented stuff out there on the web. Of course, if you use them so rarely as to forget about them, it is understandable that you would fallback upon wiki/OO.o.

Please do repeat your experiment – it is really important to understand the differences between LaTeX/DocBook when proficient.

– burning, 2010-11-20 18:02 UTC

So what IDE is recommended for DocBook?

– PierreGaston 2010-11-22 07:12 UTC

Next time I should look at markdown + pandoc.

AlexSchroeder 2014-06-23 08:29 UTC

Please make sure you contribute only your own work, or work licensed under the GNU Free Documentation License. See Info for text formatting rules. You can edit the comment page if you need to fix typos. You can subscribe to new comments by email without leaving a comment.