= Asciidoctor LaTeX James Carlson 2016-06-29 :sectnums: :toc2: :env_standard: :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] :sc: http://www.scripta.io[Scripta.io]
== 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 {adl}. 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
http://vschool.s3.amazonaws.com/asciidoctor-latex/README.html[README at S3].
There is also an online version hosted at http://www.shoobox.io/share/230[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 http://docs.mathjax.org/en/latest/start.html[MathJax].
== Features
{adl} 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 <
=== Inline and displayed formulas
foo.adoc contains the text below.
The inline and displayed formulas will be correctly rendered as html or tex.endif::[]
ifndef::env_standard[]
foo.adoc contains the text below.
It will be correctly rendered as html or tex..Rendered Text [blue]#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.# endif::[]
=== Environments
--
endif::[]
ifndef::env_standard[] .Example
--
endif::[]
=== 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.
--
endif::[]
--
--
endif::[]
== Installation
=== From Rubygems
Run gem install asciidoctor-latex --pre to install from https://rubygems.org/gems/asciidoctor-latex[RubyGems.org].
See the https://github.com/asciidoctor/asciidoctor-latex/blob/master/CHANGELOG.adoc[change log] for a list of updates.
=== 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
== Contributing
If you wish to contribute to the https://github.com/asciidoctor/asciidoctor-latex[asciidoctor-latex project], you should set up your environments to use Jakub Jirutka's https://github.com/asciidoctor/asciidoctor-doctest[asciidoctor-doctest]. At the moment you will need to use the https://github.com/jxxcarlson/asciidoctor-doctest[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.
== Dialects
Asciidoctor LaTeX processes three dialects of the core AsciiDoc language:
asciidoc (the core language)manuscriptlatexAsciidoc-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.adocTo set the dialect with the Ruby API, use for example :
Asciidoctor.convert str, { 'dialect' => 'latex' }== Macros
Macros can be included in the body of an AsciiDoc-LaTeX file using the texmacro environment, as in the example below.
\def\AA{\mathbb{A}} \def\BB{\mathbb{B}}
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.
== 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.
{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
\$ a^2 + b^2 = c^2 \$ and+++stem:[ a^2 + b^2 = c^2 ]+++
andifdef::env_standard[] == AsciiDoc-LaTeX environments
env construct that maps to LaTeX environments.
ThusNAME
of [env.NAME], Thus,one can writethen referencing it later as +<
Certain environments receive special treatment.
For numbered equations, use [env.equation]
like this
An equation number will be displayed only when a label for cross-referencing is provided, e.g.,
[env,equationalign]:endif::[]
ifndef::env_standard[] == AsciiDoc-LaTeX environments
Asciidoctor LaTeX supports an env construct that maps to LaTeX environments.
Thus,
renders as an automatically numbered theorem:
NAME
of [env.NAME], Thus,one can writeto obtain
then referencing it later as +<
Certain environments receive special treatment.
For numbered equations, use [env.equation]
like this
Here is the rendered version:
An equation number will be displayed only when a label for cross-referencing is provided, e.g.,
so that now one has
[env,equationalign]:endif::[]