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

Comments on 2010-06-30 LaTeX vs. Docbook

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

# 2010-06-27 Docbook Mess

I was looking for an alternative to LaTeX. I recently learned how to setup DocBook. There’s a book explaining what DocBook is and how to use it; the old version of the book is available online. I also followed the instructions in the DocBook XSL book on how to install FOP, so in theory I had the entire tool chain to write an XML file, translate it to FO format using xsltproc and translating that to PDF format using fop.

It looked very ugly. I felt like going back to LaTeX – and that’s pretty ugly, too!

I found that by default, FO processors only know about Times Roman, Helvetica, and Courier by default. So I decided to try and get the article font switched to Garamond before continuing my delve into Docbook. I got followed the instructions on adding a font and wasted some time tracking down jar files that were not needed and tracking down a copy of the Garamond font I could embed. In the end I got it all working! I had an ugly document, but it was A4, two columns, had some bold, and some italic, and my name on it.

But I also felt that maybe – just maybe – LaTeX and OpenOffice were not such a bad ideas after all.

Maybe I should just stick to OpenOffice and focus on getting things done.

## Technical Details

Makefile:

all: test.pdf

%.fo: %.xml Makefile
xsltproc \
--output $@ \ --stringparam fop1.extensions 1 \ --stringparam paper.type A4 \ --stringparam column.count.body 2 \ --stringparam body.font.family Garamond \ /usr/local/share/xml/docbook-xsl/fo/docbook.xsl \$<

%.pdf: %.fo
fop -c garamond.xml -fo $< -pdf$@

# Garamond
# curl http://garamond.org/font/urw/GaramondNo8.Files.txt | xargs wget

fonts: GaramondNo8-Ita.xml GaramondNo8-MedIta.xml GaramondNo8-Med.xml GaramondNo8-Reg.xml

GaramondNo8-%.xml: GaramondNo8-%.ttf
java -cp "/usr/local/share/xml/fop/build/fop.jar:/usr/local/share/xml/fop/lib/commons-io-1.3.1.jar:/usr/local/share/xml/fop/lib/commons-logging-1.0.4.jar:/usr/local/share/xml/fop/lib/xmlgraphics-commons-1.3.1.jar" \
$<$@

/usr/local/share/xml/fop is a symlink to fop-0.95.

The garamond.xml I also had to write:

<fop version="1.0">
<renderers>
<renderer mime="application/pdf">
<fonts>
<font metrics-url="GaramondNo8-Ita.xml" kerning="yes" embed-url="GaramondNo8-Ita.ttf">
<font-triplet name="Garamond" style="italic" weight="normal"/>
</font>
<font metrics-url="GaramondNo8-Med.xml" kerning="yes" embed-url="GaramondNo8-Med.ttf">
<font-triplet name="Garamond" style="normal" weight="bold"/>
</font>
<font metrics-url="GaramondNo8-MedIta.xml" kerning="yes" embed-url="GaramondNo8-MedIta.ttf">
<font-triplet name="Garamond" style="italic" weight="bold"/>
</font>
<font metrics-url="GaramondNo8-Reg.xml" kerning="yes" embed-url="GaramondNo8-Reg.ttf">
<font-triplet name="Garamond" style="normal" weight="normal"/>
</font>
</fonts>
</renderer>
</renderers>
</fop>

I also got fop-hyph.jar from OFFO and I got jai_codec.jar and jai_core.jar from the Java Advanced Imaging Downloads. I copied all three into /usr/local/share/xml/fop/lib.

Uhm… That’s it, I think.

My test file:

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article>
<title>My Article</title>
<author><firstname>Alex</firstname>
<surname>Schroeder</surname></author>
<sect1><title>Testing</title>
<para>This is an ordinary paragraph with some <emphasis role="bold">bold</emphasis>
and <emphasis>italic</emphasis> words.</para>
</sect1>
</article>

Oh, and this required the installation of the DocBook 4.5 XSL files and an entry in my catalog file. I got it from here: http://www.oasis-open.org/docbook/xml/4.5/ and followed my own instructions on how to update the catalog file.

All of this seems mighty complicated compared to just starting OpenOffice and writing a document or two. Sure, I don’t like working with it. But I don’t like working with all these arcane files and formats either. I can already see myself trying to get a title page or a little table just right in a three page document. It’ll never be worth my time. I’d be a gazillion times faster using Emacs and plain text!

Tags:

Check out docutils and rst2pdf. And yes, as soon as images are in the mix, you may want to consider something with a UI.

Harald Wagener 2010-06-27 07:19 UTC

Rst is definitely a good idea for 90% of articles. Also, if you want to publish it online, check out Sphinx.

Or have a look at a Wiki-based solution, for example Confluence+Scroll Wiki Exporter.

– Stefan Kleineikenscheidt 2010-06-28 15:54 UTC

Thanks for all the suggestions. I guess I just need to start producing a few small PDF documents for me to evaluate the various solutions.

AlexSchroeder 2010-06-28 23:45 UTC

# 2010-06-25 Compile Bitlbee UI-fix branch on Mac OS 10.4

Yeah, I know. Why the hell am I still using Mac OS 10.4 instead of upgrading – or moving to a Debian system? I dunno!

So I was trying to compile the ui-fix branch for BitlBee. It includes the killerbee branch, so it uses libpurple and all that.

I wasted a lot of time on this.

The sun was shining, too.

I was unable to find something prepackaged for me. So I started to follow the instructions in DocBook XSL: The Complete Guide.

Installing the DocBook DTD – xmlto doesn’t use the latest one so I got version 4.2 – http://www.oasis-open.org/docbook/xml/4.2/docbook-xml-4.2.zip and unpacked it. I wanted everything in /usr/local/share/xml so that’s what I did – sudo mv docbook-xml-4.2 /usr/local/share/xml

Installing the DocBook stylesheets – so now we need stylesheets to create the manpages. I got the following file: http://sourceforge.net/projects/docbook/files/docbook-xsl-ns/1.75.2/docbook-xsl-ns-1.75.2.tar.bz2/download and used sudo mv docbook-xsl-ns-1.75.2 /usr/local/share/xml

How to write an XML catalog file – next I needed to write the catalog for the minimum stuff I needed. I created a the file /usr/local/share/xml/docbook.cat with the following content:

<?xml version="1.0"?>
<catalog  xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<group  prefer="public"  xml:base="file:///usr/local/share/xml/" >
<public
publicId="-//OASIS//DTD DocBook XML V4.2//EN"
uri="docbook-xml-4.2/docbookx.dtd"/>
<rewriteURI
uriStartString="http://docbook.sourceforge.net/release/xsl/current/"
rewritePrefix="docbook-xsl-ns-1.75.2/" />
</group>
</catalog>

I set the environment variable in my .bashrc: export XML_CATALOG_FILES=/usr/local/share/xml/docbook.cat.

And with that, make xmlto and make bitlbee worked!