blipp / asciidoctor-latex

:triangular_ruler: Add LaTeX features to AsciiDoc & convert AsciiDoc to LaTeX

AsciiDoc-LaTeX Converter for Asciidoctor

Table of Contents

• 1. Purpose
• 2. Installation
  • 2.1. From Rubygems
  • 2.2. From GitHub
• 3. Commands
  • 3.1. Macro files
  • 3.2. Switches
• 4. Document format
• 5. Asciidoc-LaTeX environments
• 6. Click blocks

Note	CHANGELOG.adoc has been added to this repo.

1. Purpose

Asciidoc-LaTeX defines an extended mathematical syntax for the Asciidoc markup language that closely parallels LaTeX. The Asciidoctor-LaTeX converter renders documents written in this extended markup language into both HTML and LaTeX.^[1]

Below, we descibe the main features of Asciidoc-LaTeX. However, since it will not render in GitHub, you are encouraged to view this write-up: Asciidoc-LaTeX. For more information on using Asciidoc-LaTeX, please consult the Asciidoctor-LaTeX manual. For more information on conversion of Asciidoc-LaTeX documents to LaTeX, see the file tech-report.adoc in this repository or consult the online version, which has a table of contents.

Asciidoctor-LaTeX is developed by James Carlson, Jakub Jirutka, and Dan Allen.

2. Installation

2.1. From Rubygems

The development release, currenty 1.5.0.3.dev, is at RubyGems.org Beta alert!

2.2. From GitHub

If you would like to install a development version from the repository, use:

$ git clone https://github.com/asciidoctor/asciidoctor-latex.git
$ cd asciidoctor-latex
$ gem build asciidoctor-latex.gemspec
$ gem install *.gem

3. Commands

Asciidoc math files can be rendered

Render as HTML

Use $ asciidoctor-latex -b html foo.adoc to produce foo.html. With this command the Asciidoc-LaTeX syntax and extensions will be rendered.

Render as LaTeX

Use $ asciidoctor-latex foo.adoc to produce foo.tex.

3.1. Macro files

The contents of a file named macros.tex will read and used by asciidoctor-latex if it is in the same directory as the file being rendered. This is the case regardless of the output format — HTML or tex.

3.2. Switches

asciidoctor-latex -a header=no foo.adoc

Use a minimal header for the generated tex file.

Asciidoctor-LaTeX’s default form at is :latexmath. To use :stem, put the text :stem: in your file. To turn the switch on and set it to latexmath, say instead of stem:latexmth.

4. Document format

Asciidoctor supports two closely-related math formats, Asciidoc-LaTeX and AsciiMath. In Asciidoc-LaTeX, one can write $ a^2 + b^2 = c^2 $ and

 \[
    e^{2\pi \sqrt{-1}} = 1,
 \]

for in-line and display mathematial text, respectively. You will need to express dollar-denominated currency using escaped dollar signs, as in the sentence, "He paid \$100 for that theorem." In AsciiMath, one writes stem:[ a^2 + b^2 = c^2 ] and

  [stem]
  ++++
    e^{2\pi \sqrt{-1}} = 1.
  ++++

5. Asciidoc-LaTeX environments

Asciidoc-LaTeX supports an env construct that maps to LaTeX environments. Thus

[env.theorem]
--
There exist infinitely many prime numbers.
--

renders as an automatically numbered theorem. Environments can contain in-line and display mathematics, e.g.,

[env.theorem]
--
A two-by-two matrix is invertible if
its determinant is nonzero, i.e., if
\[
  \left|\begin{matrix}
    a & b \\
    c & d
  \end{matrix}\right| \ne 0
\]
This result extends to $n\times n$ matrices.
--

There is complete freedom in parameter NAME of [env.NAME], Thus,one can write

[env.definition]
--
An integer $n$ is *prime* if (a) it is not
$\pm 1$ and (b) it has no divisors other
than $\pm 1$ and $\pm n$.
--

or

[env.joke]
--
A mathematician, a philosopher, and
a lawyer met at the local bar
for a drink.  The lawyer said ...
--

One can make cross references by labeling the environment as in

[env.joke#mathjoke1]
--
A mathematician, a philosopher, and
a lawyer met at the local bar
for a drink.  The lawyer said ...
--

then referencing it later as [mathjoke1].

Certain environments receive special treatment. For numbered equations, use [env.equation] like this

[env.equation]
--
a^{p-1} \equiv 1\ \text{mod}\ p
--

For sets of equations, use [env,equationalign]:

[env.equationalign]
--
A & = 4\pi r^2 \\
V & = \frac{4}{3} \pi r^3
--

6. Click blocks

Click blocks are similar to [env] blocks exceptiipoo that the body of the block is not displayed until the user clicks on the heading. The heading of a click block is displayed in blue. Once a click block is "opened", it can be closed by clicking again on the heading.

[click.comment]
--
It is sometimes useful to "hide" a comment
in a click block so as not to unduly
disturb the flow of the prose. Click
blocks are also useful for problem sets,
since one can make hints, solutions, etc.
clickable.

The default for click blocks is not to number them. See the file click.adoc in the exampless directory for more information.

---

1. Many, but not all Asciidoc language features are covered by this release.