= AsciiDoc-LaTeX Converter for Asciidoctor
James Carlson
2015-04-19
:numbered:
:pagenums:
:toc2:
:stem:

NOTE: CHANGELOG.adoc has been added to this repo.

== Purpose

:adl: Asciidoc-LaTeX
:adlp: Asciidoctor-LaTeX
:ad: Asciidoc
:adp: http://asciidoctor.org[Asciidoctor]
:adoc: http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoc]
:adlm: http://www.noteshare.io/section/asciidoctor-latex-manual-intro[Asciidoctor-LaTeX Manual]
////
:tex: https://www.sharelatex.com/[LaTeX]
////
:tex: LaTeX
:article: http://noteshare.io/book/transcendental-numbers-and-periods[article]
:ns: http://www.noteshare.io[Noteshare.io]


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.footnote:[Many, but not all Asciidoc language
features are covered by this release.]

Below, we descibe the main
features of {adl}.  However, since
it will not render in GitHub, you
are encouraged to view this write-up:
https://vschool.s3.amazonaws.com/manuscripts/372.html[Asciidoc-LaTeX].
For more information on using {adl}, please consult the
http://www.noteshare.io/book/asciidoctor-latex-manual[Asciidoctor-LaTeX manual].
For more information on conversion of {adl}
documents to {tex}, see the file `tech-report.adoc` in
this repository or consult the
https://vschool.s3.amazonaws.com/manuscripts/389.html[online version],
which has a table of contents.

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


== Installation

=== From Rubygems

The development release, currenty 1.5.0.3.dev, is at
https://rubygems.org/gems/asciidoctor-latex[RubyGems.org]
Beta alert!

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


== 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`.


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


=== Switches

asciidoctor-latex -a header=no foo.adoc::
Use a minimal header for the generated tex file.


{adlp}'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`.

== Document format

Asciidoctor supports two closely-related
math formats, [blue]#Asciidoc-LaTeX#
and [blue]#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.
  ++++
----


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




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