If you are fed up of fighting with complex office programs to create PDFs you should rethink your text creation pipeline. Why not using the beauty of TeX and the easiness of simple ASCII text to get a better result with lesser efforts?
Why Do I Have to Invest so Much Time?
I you have a look back at the office market for a decade or so you can’t recognize real innovation. We got more features that even lesser people use, and we still need high-end computers to write a letter. Yes, we have a common standard, set by Microsoft Office in the 1990s, that all office implementations follow – besides the innovative Flex implementations of course. But, how about productivity these days?
My experience shows me that I invest a third up to a half of my time in layout. The more people or the more different office applications are involved the more the layout demands my attention. All the templates can’t help to reduce this effort. Best of all: you never get what you expect or imagine what it should look like. Sometimes you think you work with a buggy application. But, it’s the insane user model behind it that ignores user expectations, misses self-descriptiveness, and the like.
I need a Brilliant Typesetting Solution
So, why shall we invest so much time in the presentation of a document when a brilliant and full-blown typesetting system exists for more than two decades? TeX is one of the best and free tools in this domain I’ve used in the past. You tell TeX what you expect, e.g. a heading, everything else is calculated by TeX itself. All rules that the typesetting community has invented in the last centuries are already part of the implementation.
You may wonder what is the drawback, why do we still use other products. TeX is an academic products and to use it is not as easy as using your office application. The first improvement was the macro language LaTeX. I used it already in the 1990s to write my diploma thesis (German). Although a fellow student of mine developed an integrated environment on MS-DOS in his diploma thesis that I could use it was a lot of work to learn all those macros and use them in a standard text editor. The syntax is a bit quirky.
The last decade the Open Source community has further developed the TeX processing pipeline. The first step was to create a LaTeX word processor that looks similar to your office word processor: LyX. Nowadays there are alternatives, like LEd, that offer a lot more. If you work in a pure TeX/LaTeX environment those editors are pretty cool. But, it is still the old user model to write texts.
Writing Text Can be sooo Easy
LaTeX macros are not an alternative to get rid of all the word processor overhead. If you have a look at todays Wiki products you recognize they deliver their own simplified syntax to create web pages. The syntax is pretty easy, fast to learn and – best of all – fast to use. There exist some solutions now that use this idea and combine it with a TeX/LaTeX processor to create PDFs. The most interesting ones are:
When Standards Are Important
Before we have a deeper look at AsciiDoc, that I prefer over the promising txt2tags at the moment, we have to talk about DocBook, the industry standard for document processing and exchange. DocBook is based on XML that is free and open. XML is a standard that is widely supported with a mass of tools in all important programming languages. One important part in those toolsets is the XSLT – the stylesheet transformation – that allows to transfer your DocBook into PDF, EPUB, MS Word, and other important document formats. DocBook is an ideal candidate for a “write once and process anywhere” concept.
So, if we have a look at the pipeline above we have something like this:
simplified ascii format -> TeX/LaTeX -> PDF
But, the even better pipeline would be:
simplified ascii format -> DocBook -> TeX/LaTex -> PDF
This allows you to use your preferred ascii format without loosing the possibility to exploit all the XML advantages (incl. a standardized document exchange). It is also an investment protection if your preferred ascii format is no longer supported.
AsciiDoc delivers all these advantages in one product:
- Brilliant typesetting through TeX/LaTeX
- Future-proof document exchange, archiving and processing through DocBook
- Easy writing through a simplified ascii format
AsciiDoc works best in Linux environments. All current distributions have installers for it.
Writing Environment Preparation
For Windows we can use Cygwin. Cygwin allows us to use its installer for AsciiDoc and also dblatex, that allows us to create a LaTeX-formatted PDF from DocBook.
In the Cygwin setup search for asciidoc. AsciiDoc is written in Python. So, Python is selected automatically:
Next you search for the dblatex package:
If you install a fresh Cygwin a basic TeX/LaTeX installation will be missing. You can search for the tetex package then:
After the installation of Cygwin, AsciiDoc and dblatex, the hardcore Windows user can skip Cygwin and use a simple Windows batch file, e.g.
build.bat, that looks similar to this (we assume you use the standard installation folder for Cygwin and your working files reside in
bash --login -i -c "cd /cygdrive/c/asciidoc;asciidoc -a lang=en -v -b docbook -d book test.txt;dblatex -V -T db2latex test.xml"
You can also use the asciidoc toolchain manager a2x (however the DocBook file is deleted finally):
bash --login -i -c "cd /cygdrive/c/asciidoc;a2x -v -f pdf -L --asciidoc-opts='-a lang=en -v -b docbook -d book' --dblatex-opts='-V -T db2latex' test.txt"
The batch file does all the necessary processing steps for creating a book structure. The
test.txt file is what you write in your text editor.
test.xml is your generated DocBook file. Finally, you can open the file
c:\asciidoc\test.pdf (based on PDF 1.4, Acrobat 5 compatible).
The book style starts with a new page for every chapter. If you want to use an article template a
-d article creates a continuous text flow for your chapters. If you use a language different to English change the
lang=en to the corresponding id, e.g. de for German. Also important for the
test.txt file is using UTF-8 encoding when you save the file. Else you get umlaut problems with the DocBook processing.
If you have a deeper look at AsciiDoc you will recognize that it delivers a lot of features to influence the document generation. If you want to give AsciiDoc a try have a look at the user guide, the cheatsheet and the examples and templates.