= LaTeX Converter Manual
James Carlson
:toc2:
:numbered:
:stem: latexmath

== Introduction

TexConverter translates a file written
in a subset of Asciidoc to LaTeX.  The
subset is described below.  While not
complete, it is adequate for the preparation
of a wide range of mathematical documents,
from one-page handouts to articles to entire books.

As a demonstration of the current state of this
project, the file you are looking at, `manual.adoc`,
can be rendered into HTML by
----
  $ asciidoctor manual.adoc
----
or can be rendered as a LaTeX file via
----
  $ asciidoctor-latex manual.adoc
  # => manual.tex
----
The `.tex` file can in turn be rendred into pdf via
`pdflatex`.


Mathematical text in Asciidoc can be written as
one usually does in LaTeX if one invokes the
latex option.footnote:[This option exists but has not yet been released.  To use
	the option at http://noteshare.io[noteshare.io], include the code `:latex:` in
	your document].  You do this via  `asciidoctor -latex foo.adoc`.
Thus for the Pythagorean
theorem $a^2  + b^2 = c^2$, one writes

----
    $ a^2 + b^2 = c^2 $
----

For the famous formula of Euler,
\[
  e^{2\pi \sqrt{-1}} = 1
\]
one writes

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


== The Asciidoc-LaTeX subset



=== Sections, levels 1 through 5


=== Ordered and unordered lists

In Asciidoc, an unordered list like

* Pay Bills
* Get Groceries
** Milk
** Bread
** Orange Juice
* Change Oil Filter on Car

is written like this

----
    * Pay Bills
    * Get Groceries
    ** Milk
    ** Bread
    ** Orange Juice
    * Change Oil Filter on Car
----

Its translation into LaTeX is

----
   \begin{itemize}
   \item Pay Bills
   \item Get Groceries
   \begin{itemize}
       \item Milk
       \item Bread
       \item Orange Juice
   \end{itemize}
   \item Change Oil Filter on Car
   \end{itemize}
----

The corresponding ordered list,

. Pay Bills
. Get Groceries
.. Milk
.. Bread
.. Orange Juice
. Change Oil Filter on Car

is written as

----
   . Pay Bills
   . Get Groceries
   .. Milk
   .. Bread
   .. Orange Juice
   . Change Oil Filter on Car
----

with the following source in LaTex:

----
	\begin{enumerate}
	\item Pay Bills
	\item Get Groceries
    \begin{enumerate}
	    \item Milk
	    \item Bread
	    \item Orange Juice
	\end{enumerate}
	\item Change Oil Filter on Car
	\end{enumerate}
----

=== Bold, italic, and monospaced text

The text "She said _potatoes_ but he said *potaatoes*", written
in Asciidoc as

----
    She said _potatoes_ but he said *potaatoes*
----
is mapped to

----
    She said \emph{potatoes} but he said \textbf{potaatoes}
----

The text

----
    `monospaced`
----

is mapped to

----
    {\tt monospaced}
----


=== Quotations

The text

----
    [quote, Abraham Lincoln, Soldiers' National Cemetery Dedication]
    ____
    Four score and seven years ago our fathers brought forth
    on this continent a new nation
    ____
----
is mapped to

----
    \begin{quote}
      Four score and seven years ago our fathers brought forth
      on this continent a new nation
    \end{quote}
----

=== Footnotes

Text like this
----
    Ho hum.footnote:[An epression of boredem]
----
is mapped to

----
    Ho hum\footnote{An epression of boredem}
----

=== References and labels

The label

----
    Ho hum[[foo]]
----

is mapped to

----
    Ho hum\label{foo}
----

The cross-reference

----
    Please see <<foo>>
----

is mapped to

----
   Please see \ref{foo}
----



=== Hyperlinks

The hyperlink

----
    http://nytimes.com[All the news that is fit to print]
----

is mapped to

----
   \href{http://nytimes.com}{All the news that is fit to print}
----

=== Line breaks `+`

=== Listing

=== Open blocks

=== Literal

=== Page break

=== Pass

////
  INLINE_TYPES = %w( inline_quoted)
  BLOCK_TYPES = %w(admonition listing literal page_break paragraph stem pass open quote)
////


== Mathematical text

We distinguish between _inner text_ amd _outer text_.  the first
appears between math delimiters, while the second does not.

=== Inner text

As noted in the introduction, mathematical text is enclosed in the
standard delimiters and is written in the normal way.  Environments
supported in display math mode are

* matrix
* equation, including the label macro


=== Outer text

To write a theorem, do this:

----
.Theorem {counter:theorem}
--
For all $a$, $b$, $c$, the relation $a(b+c) = ab + ac$ holds.
--
----

This will render in Asciidoc as

.Theorem {counter:theorem}
--
_For all $a$, $b$, $c$, the relation $a(b+c) = ab + ac$ holds._
--