LaTeX backend for Asciidoc

Introduction

LaTeX backend is a configuration file for Stuart Rackham’s Asciidoc. It generates high-level LaTeX markup from Asciidoc documents. LaTeX is a document preparation system for TeX which in turn is a popular typesetting system. It is well known for producing excellently typesetted high quality printouts, especially suited for scientific text.

Tutorial

Getting a ready-to-print document from an Asciidoc document using the LaTeX backend involves at least two steps:

Conversion of the Asciidoc document into a LaTeX document (this is done by Asciidoc using the LaTeX backend)
Conversion of the LaTeX document into a PDF document (this is done by the TeX system)

Try to create a PDF document from the Asciidoc document article.txt which resides in the doc directory of Asciidoc:

Make a copy of article.txt in a directory of your choice, let’s call it latex-test.
Make sure that all images referenced in article.txt exist in latex-test. Brute force approach: Copy the whole images directory from Asciidoc directory into latex-test.

Change directory to latex-test and type following commands:

asciidoc --unsafe --backend=latex article.txt
pdflatex article.tex

Now there should be a file article.pdf in the latex-test directory.

Asciidoc has to be started in unsafe mode when using LaTeX backend.
Note that some special LaTeX packages are necessary, see here.

General notes

Quality of LaTeX output

High-level LaTeX is not very straightforward to generate. Therefore there’s no guarantee that the generated output is valid and compiles successfully. At all, this backend should be considered as rather experimental. You should have been already in touch with LaTeX in order to use the backend effectively because LaTeX compilation errors can be really nasty.

Nevertheless good results can be achieved by using LaTeX backend. Try for example to compile Stuart Rackham’s Asciidoc documentation, a rather large document. It should compile without problems. However, the code filter might have to be reconfigured for the code filter example to work.

Configuration file customization

Like every other Asciidoc backend the LaTeX backend can be customized easily to fit the user’s needs. Actually it is very important to have this option since LaTeX doesn’t have a companion language like CSS which allows to put styling information in a separate file. Read more about the LaTeX backend configuration file here.

Output optimization

The LaTeX output is optimized for creating PDF documents using pdflatex.

Unicode support

Unfortunately TeX/LaTeX does not have native unicode support. The package ucs adds elementary unicode support by introducing UTF-8 input encoding recognition and by defining lookup tables which contain the corresponding LaTeX commands for unicode characters. But these lookup tables are far from being complete. When a unicode character is found which is not defined in the lookup tables an error is raised by the TeX/LaTeX compiler. Note that TeX/LaTeX compilation errors caused by missing unicode character definitions are not fatal, that means the result is probably readable but undefined unicode characters are replaced with [U+...]. You may (de)activate the recognition of escaped unicode characters. See the [latex-recognize-escaped-unicode] backend option.

Backend specific features

Special sections

LaTeX backend supports the following special sections and replaces them with corresponding LaTeX commands or environments:

Abstract (only for document type article)
Dedication (only for document type book)
Index
Bibliography (only when the attribute latex-use-bibliography-environment is set)
Appendix
Contents

Internal cross references

Macros for internal cross references have been extended by the attribute style.

xref:<id>[<caption>, style=<style>]

<<<id>,<caption>,<style>>>

The additional attribute style can have following values:

page: Let’s LaTeX print the page number of the referenced anchor.
ref: Let’s LaTeX print the number of the section, subsection, figure, table or theorem the referenced anchor resides.
autoref: Let’s LaTeX print the number of the section, subsection, figure, table or theorem the referenced anchor resides preceded with a contextual label.
cite: Let’s LaTeX interpret this reference as a reference to a bibliography entry. If the attribute latex-use-bibliography-environment is set, references with cite style as well as their corresponding bibliography anchors are presented as automatically generated numbers.

If the style attribute is not set the reference is printed the common way.

Options

LaTeX document generation is influenced by the following attributes:

latex-table-rowlimit: The maximum number of rows for typesetting tables using the tabular environment. If a table has more rows than latex-table-rowlimit, longtable environment is used instead of tabular environment. longtable environment supports tables spanning over several pages.
latex-use-bibliography-environment: If latex-use-bibliography-environment is defined, thebibliography environment is used for the bibliography section. As a result bibliography entries are automatically numbered. Note that this works only if the bibliography section contains exclusively bibliography list items which start with a bibliography entry ([[[…]]]). Otherwise a TeX/LaTeX compilation error will occur. In order to display bibliography references correctly their style attribute must be set to cite. For more information see Internal cross references.
latex-indent-paragraphs: If latex-indent-paragraphs is defined, the first line of paragraphs will be indented. By default LaTeX backend prevents paragraph indentation and prints paragraphs with preceding vertical space.
latex-recognize-escaped-unicode: If latex-recognize-escaped-unicode is defined, escaped unicode characters (e.g. \$${amp}#960;$$ or \$${amp}#x3C0;$$) will be recognized. This can lead to LaTeX compilation errors since LaTeX unicode support is only rudimentary. For more information see Unicode support.
latex-use-custom-list-items: If latex-use-custom-list-items is defined, lists will be bulleted or enumerated the way you have typed them in the original Asciidoc document. That means, * turns into a circle bullet, - turns into a dash, . turns into a number and .. turns into a letter. Otherwise LaTeX will use different bullets and enumeration characters depending on the level of nesting.
latex-use-colored-tables: If latex-use-colored-tables is defined, tables will be printed colored.
latex-use-running-title-headings: If latex-use-running-title-headings is defined, pagestyle will be set to headings which results in running titles in the head.
latex-use-colored-sidebar-blocks: If latex-use-colored-sidebar-blocks is defined, sidebar block content will be put in a color box instead of being indented by a vertical bar.
icons: Link admonition paragraph and admonition block icon images and badge images. By default icons is undefined and text is used in place of icon images.
encoding: Set the input and output document character set encoding. Currently ISO-8859-1 and UTF-8 are supported.

Requirements

General

The following software is necessary for using the LaTeX backend:

An up-to-date version of Asciidoc
An up-to-date TeX distribution, e.g.:
- MiKTeX for Windows
- teTeX for Linux
- https://www.tug.org/mactex/ for macOS

TeX/LaTeX Package requirements

LaTeX backend makes use of some LaTeX specialities which don’t belong to a minimal TeX/LaTeX distribution. However, I took special care not to employ exotic packages. Hence the following packages should be available in most package repositories. The table is not complete yet because I don’t know the package names for all TeX distributions.

Speciality	MiKTeX package name	Description
KOMA-Script	koma-script	LaTeX backend uses the document classes scrartcl and scrbook as well as some other specialities defined in the KOMA-Script package, e.g. the commands `\addmargin{}` and `\minisec{}`.
xcolor.sty	xcolor	Used to produce colored boxes and tables.
colortbl.sty	colortbl	Used to produce colored tables.
type1ec.sty	cm-super	Enables high quality fonts for PDF output.
hyperref.sty	hyperref	Extensive support for hypertext in PDF documents.
enumerate.sty	tools	When latex-use-custom-list-items is defined this package is used for determining the enumeration character.
graphicx.sty	graphics	Used for including images.
longtable.sty	tools	Enables page spanning tables.
ucs.sty	unicode	Enables support for unicode characters.
textcomp	ltxbase	Used for printing various symbols like arrows. Should be already installed.
alltt	ltxbase	Used in literal-like blocks for retaining line and whitespace formatting. Should be already installed.
listings.sty	listings	Used for listing blocks.

About the LaTeX backend configuration file

An important note for people who want to adapt the LaTeX backend configuration file to their own needs:

LaTeX markup has a lot of special characters, most importantly ``, {, }. In order to make things less complicated, I changed the default substitution order (see entry subsnormal in the [miscellaneous] section). In contrast to the backends docbook and xhtml11, the specialcharacters substitution is applied very late. As a result all special characters produced by quotes, specialwords, replacements, attributes and macros become escaped at the end. If you don’t want special characters in the corresponding sections to get escaped, you’ve to use following symbols instead of the special characters.

\$$!..backslash..!$$ instead of ``
\$$!..braceleft..!$$ instead of {
\$$!..braceright..!$$ instead of }

For more special characters take a look in the [replacements2] sections. [replacements2] section is responsible for replacing the symbols with their corresponding special characters.

Ideas

Code listing block

For creating highlighted code listings I suggest the use of Highlight or GNU Source Highlight. Both are suited for use as Asciidoc filters.

Known Bugs

Sometimes LaTeX backend handles things differently from the default backends
A lot of little bugs

Todo List

Remove bugs
Support for grid attribute in tables
Better looking tables
Option for squeezing output (smaller lists)
Support for different languages (That would be a nice feature for Asciidoc in general)
Option for switching titlepage on and off