How to Create Handsome PDF Documents Without Frustration

AsciiDoc - DocBook - LaTex/PDF

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

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:

Cygwin asciiDoc installation

Next you search for the dblatex package:

Cygwin dblatex installation

If you install a fresh Cygwin a basic TeX/LaTeX installation will be missing. You can search for the tetex package then:

Cygwin teTeX installation

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 c:\asciidoc):
@echo off
C:
chdir C:\cygwin\bin
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"
pause

You can also use the asciidoc toolchain manager a2x (however the DocBook file is deleted finally):

@echo off
C:
chdir C:\cygwin\bin
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"
pause

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.

Amazon Ads

11 Comments

  1. Matthew Pettis

    I know this is an older post, but this post is linked to from the asciidoc documentation. Anyway, I am on Windows and attempting this after installing asciidoc, dblatex, and tetex on cygwin. when using your second .bat file, I get the error:

    ———————
    Image 'dblatex' not found
    Build V6-V7-Production-stress-tests.pdf
    built-in module pdftex registered
    no support found for ifxetex
    no support found for fontspec
    no support found for xltxtra
    no support found for fontenc
    no support found for inputenc
    no support found for fancybox
    built-in module makeidx registered
    no support found for asciidoc-dblatex
    building additional files…
    checking if compiling is necessary…
    the output file doesn't exist
    pdflatex -interaction=batchmode V6-V7-Production-stress-tests.tex
    This is pdfeTeXk, Version 3.141592-1.21a-2.2 (Web2C 7.5.4)
    file:line:error style messages enabled.
    %&-line parsing enabled.
    entering extended mode
    pdflatex failed
    V6-V7-Production-stress-tests.tex: File `fancybox.sty' not found.
    Unexpected error occured
    a2x: deleting /cygdrive/e/RMG/JMS-Test-Versions/doc/V6-V7-Production-stress-tests.xml
    ————————————-

    any idea why i get this? dblatex is installed and i can call it from the command line on its own…

    thanks,
    matt

  2. rainwebs

    Matthew,

    do you have done full-blown installations of all mentioned packages? Did you test it with the first batch file code?

    Maybe you also have coding errors in the text source file. You may try to use each tool step by step using the different (generated) source files. My experience shows me that it is a bit tricky to recognize such (syntax) errors when you use the complete processing chain in one step.

  3. Bernard

    I have been using asciidoc for years to generate and maintain java programming courses.
    It is very useful ….
    some snags though:
    – the syntax evolves sometimes in incompatible ways so you’ll have to modify your documents ! (I have hundreds of documents!)
    – the program tries to connect to sourceforge and oasis to get document through the web if it is impossible (happens to be my case) you are obliged to build a local copy of thes documents (a cumbersome task)
    – I need to tidy and “sed”/modify the xml to adapt to french language (e.g change “example” to “exemple” and so on)
    – I needed to modify the source code to accept java examples (easy there)

    but overall a very useful application
    (use it through cygwin on windows 7)

    Bernard

  4. rainwebs

    Bernard,

    thanks for your experiences. Tools developed primarily in the U.S. always show some defects when we use European Umlauts ;-).

    I’m currently looking for a better processing chain (e.g. using DITA). But, it seems that the chain I describe in this post is still state-of-the-art :-(.

  5. sjas

    @echo off
    set cygwin_home=C:\cygwin\bin
    SETLOCAL
    cygpath -u %CD% > temp.txt
    set /p local_filepath= < temp.txt
    del temp.txt
    ENDLOCAL & set proper_filepath=%local_filepath%
    @echo on
    %cygwin_home%\bash –login -i -c "cd %proper_filepath%; a2x -v -f pdf -L –asciidoc-opts='-a lang=de -v -b docbook -d article' –dblatex-opts='-V -T db2latex -P "latex.output.revhistory=0"' %1"

  6. sjas

    The code above is described in further detail on github: https://github.com/sjas/a2x-asc-to-pdf (rainwebs: meanwhile a dead link, so try the home https://github.com/sjas/ for other asciidoc solutions, e.g. based on Ruby)

    Basically its one of the batch examples pimped so it takes the the filename as parameter and works out of the box when being placed in the same folder.

    I grew really tired of not having a proper automation for compiling PDF’s, maybe this helps anyone else, too.

  7. bill

    I know this article is now very dated, but as Matthew Pettis states above, I was directed her from the AsciiDoc site.

    I just want to alert you you that the option to install tetex does not seem to be available in Cygwin64. I have been able to generate the PDF file, but I am getting some output about “no support” for a number of things. See below. I am not sure if I need to be concerned about this as this entire toolset — AsciiDoc, DocBook, etc. — is relatively new to me. I am concerned that this might cause issues further down the road.

    no support found for ifxetex
    no support found for fontspec
    no support found for xltxtra
    no support found for fontenc
    no support found for inputenc
    no support found for fancybox

    I am not sure that the missing tetex and the above messages are related in anyway. Nor do I know what to do — yet — to resolve the above conditions.

    Bill

    • rainwebs

      Hi Bill,

      sorry that I can’t test it myself with a cygwin 64 at the moment.

      You may search for another latex package to install. Looks like they skipped latex support in cygwin 64. Did they really skipped latex?! I used teTex those days because it was available. Here’s a not so easy solution, but maybe it can help: http://tex.stackexchange.com/questions/44485/install-packages-on-cygwin

      The error messages are maybe the result of not using UTF-8? I found a hint here: https://groups.google.com/forum/#!topic/asciidoc/gig-TyT7zLc

      • Bill Burton

        Hello,

        I just found your helpful article. It seems the maintainer of tetex has chosen not to support the package anymore (since 2006)[1] so it’s no wonder cygwin 32/64 no longer includes it. The apparent successor, TeX Live[2] is available on cygwin.

        Is it possible to use TeX Live to get AsciiDoc working?

        Thanks,
        -Bill B.
        [1] http://www.tug.org/tetex/
        [2] http://www.tug.org/texlive/

        • rainwebs

          Hi Bill,

          sorry, I’m not able to test this myself at the moment. Normally, a standard TeX installation should help, like the mentioned one in the post did it those days. So give it a try.

        • Spearit

          Hi Bill,
          Were you able to get asciidoc up and running with cygwin64 and TeX Live? I’m looking for a solution to run asciidoc on a Windows box.

Comments are closed.