📐 Add LaTeX features to AsciiDoc & convert AsciiDoc to LaTeX
Branch: master
Clone or download
jxxcarlson Merge pull request #68 from tribut/align
Use align/aligned instead of equation/split
Latest commit 652176e Sep 14, 2017
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin Add stem:latexmath to default options in bin/asciidoctor-latex Dec 16, 2014
data Add support for index in tex output Jul 27, 2017
dist Compile to JavaScript Oct 23, 2016
doc Add doc files Jun 7, 2016
examples Use texmacros not tex_macros May 15, 2015
lib Merge pull request #68 from tribut/align Sep 14, 2017
npm Compile to JavaScript Oct 23, 2016
spec Add to repo: add_ons/compile_index.rb and make_index.rb (restructure) Sep 13, 2015
test Use align/aligned instead of equation/split Aug 2, 2017
try-out Merge pull request #17 from otavio/quote-try-out Jun 27, 2016
.editorconfig Add .editorconfig Dec 12, 2014
.gitignore Merge branch 'master' of github.com:asciidoctor/asciidoctor-latex Jul 29, 2017
.travis.yml configure CI job to run doctest (PR #61) Jul 26, 2017
.yardopts - Update documentation Apr 19, 2015
CHANGELOG.adoc Ready for 1.5.0.16.dev Jun 29, 2016
Gemfile fix compatibility with Asciidoctor upstream Jul 26, 2017
LICENSE.adoc Migrate LaTeX converter to asciidoctor-latex repository Nov 5, 2014
README.adoc Merge pull request #49 from mattpalermo/master Jul 29, 2017
Rakefile Changes to Rakefile and test/ to accomodate dialects Jun 22, 2016
asciidoctor-latex.gemspec Change s.add_runtime_dependency 'asciidoctor', '~> 1.5.2' to Jul 9, 2015
cross.rake Cross-compile to JavaScript Apr 12, 2015
package.json Compile to JavaScript Oct 23, 2016
tech-report.adoc use correct style for source blocks in tech report Jul 26, 2017

README.adoc

Asciidoctor LaTeX

1. Introduction

Asciidoctor LaTeX defines an extended syntax for the AsciiDoc markup language (AsciiDoc-LaTeX) that closely parallels LaTeX for inline and display mathematical formulas and for environments. Documents written in this extended markup language can be converted into HTML or LaTeX:

Render as HTML

Use asciidoctor-latex -b html foo.adoc to produce foo.html.

Render as LaTeX

Use asciidoctor-latex foo.adoc to produce foo.tex, then use xelatex foo.tex to create foo.pdf.

Below, we describe the main features of AsciiDoc-LaTeX. However, since this document will not render fully in GitHub, you are encouraged to compile it yourself using asciidoctor-latex -b html README.adoc or to consult the README at S3. There is also an online version hosted at shoobox.io, a site for editing and distributing AsciiDoc and AsciiDoc-LaTeX documents.

Asciidoctor LaTeX is developed by James Carlson, Jakub Jirutka, and Dan Allen. Display of mathematical text relies on MathJax.

2. Features

AsciiDoc-LaTeX renders inline and displayed mathematical, and it supports a construct akin to LaTeX environments for theorems, equations, etc. These and other features are described briefly below and more fully in AsciiDoc-LaTeX environments.

2.1. Inline and displayed formulas

Example

Imagine that foo.adoc contains the text below. The inline and displayed formulas will be correctly rendered as html or tex.

The formula $a^2 + b^2 = c^2$ relates the sides
and hypotenuse of a right triangle.  The formula
\[
\int_0^1 x^n dx = \frac{1}{n+1}
\]
is something we all learn in Calculus

2.2. Environments

Example
  [env.theorem]
  --
 The Diophantine equation
 \[
    x^n + y^n = z^n
 \]
 for $n > 2$ has only trivial solutions
--

2.3. Click blocks

A click block displays its title but not its body. If you click on the title, the body is displayed. Click on the title again to hide the body.

The title of a click block is displayed in blue.

Example
  [env.question]
  --
  What is the speed of light?
  --

  [click.answer]
  --
  300,000 km/sec
  --

3. Installation

3.1. From Rubygems

Run gem install asciidoctor-latex --pre to install from RubyGems.org. See the change log for a list of updates.

3.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

4. Contributing

If you wish to contribute to the asciidoctor-latex project, you should set up your environments to use Jakub Jirutka’s asciidoctor-doctest. At the moment you will need to use the version which handles dialects using

gem 'asciidoctor-doctest', github: 'jxxcarlson/asciidoctor-doctest', ref: 'latex'

in your Gemfile. Run all tests with rake doctest, or run individual tests with rake doctest:html or rake doctest:tex.

At the moment the tests are for the latex dialect.

5. Dialects

Asciidoctor LaTeX processes three dialects of the core AsciiDoc language:

  • asciidoc (the core language)

  • manuscript

  • latex

Asciidoc-latex is the default dialect. Dialects can be set with the :dialect on the command line as in this example:

   asciidoctor-latex -a dialect=manuscript foo.adoc

To set the dialect with the Ruby API, use for example :

   Asciidoctor.convert str, { 'dialect' => 'latex' }

6. Macros

Macros can be included in the body of an AsciiDoc-LaTeX file using the texmacro environment, as in the example below.

[env.texmacro]
--
\def\AA{\mathbb{A}}
\def\BB{\mathbb{B}}

\newcommand{\set}[1]{ \{\,#1\,  \} }
\newcommand{\sett}[2]{ \{\,#1\, \mid\, #2\, \} }
--

To include a LaTeX macro file MACRO_FILE, insert the code include_latex_macros::MACRO_FILE[]. Here MACRO_FILE can be a file name or a an absolute or relative path. Included macros work for both the html and tex backends.

Note
Automatic inclusion of the file macros.tex has been discontinued.

7. Switches

Tex header

To generate a tex file with a minimal header, do:

$ asciidoctor-latex -a header=no foo.adoc
Print style

An alternate css file, data/print.css is provided for printing. It features wider margins and a smaller type size. Copy it to the root of your document folder and use the command asciidoctor-latex -a stylesheet=print.css or more generally asciidoctor-latex -a stylesheet=path_to/print.css.

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.

8. 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.
  ++++

9. AsciiDoc-LaTeX environments

AsciiDoctor 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
--

An equation number will be displayed only when a label for cross-referencing is provided, e.g.,

[env.equation#little-fermat]
--
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
--