|
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.9.dev, is at RubyGems.org Beta alert!
|
Note
|
Version 1.5.0.7 is "stable". Version 1.5.0.9 introduces new syntax with switches for three 'dialects' See below. |
Invoke asciidoctor-latex for LaTeX output by
# # asciidoctor-latex -a dialect=asciidoc foo.adoc # asciidoctor-latex -a dialect=manuscript foo.adoc # asciidoctor-latex -a dialect=latex foo.adoc # # Be sure to use XeLaTex for tex’ing # For html output, use # # asciidoctor-latex -a dialect=asciidoc foo.adoc -b html # asciidoctor-latex -a dialect=manuscript foo.adoc -b html # asciidoctor-latex -a dialect=latex foo.adoc -b html # # The above are source file options for dialects of asciidoc: # # asciidoc # asciidoc-manuscript # asciidoc-latex # #
1.1. 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 *.gem2. Commands
Asciidoc math files can be rendered
- Render as HTML
-
Use
$ asciidoctor-latex -b html foo.adocto producefoo.html. With this command the Asciidoc-LaTeX syntax and extensions will be rendered. - Render as LaTeX
-
Use
$ asciidoctor-latex foo.adocto producefoo.tex.
2.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.
2.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.
3. 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.
++++4. 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
--5. 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.