LaTeX backend for Asciidoc ========================== Benjamin Klum v1.0, June 2006 == Introduction LaTeX backend is a configuration file for Stuart Rackham's https://asciidoc.org/[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: 1. Conversion of the Asciidoc document into a LaTeX document (this is done by Asciidoc using the LaTeX backend) 2. 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. [IMPORTANT] ============================== - Asciidoc has to be started in 'unsafe mode' when using LaTeX backend. - Note that some special LaTeX packages are necessary, see <>. ============================== == 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 <>. === Output optimization The LaTeX output is optimized for creating PDF documents using 'pdflatex'. [[unicodeSupport]] === 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 <> 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 [[internalCrossReferences]] === Internal cross references Macros for internal cross references have been extended by the attribute 'style'. xref:[, style=