TITLE: Doconce Quick Reference
AUTHOR: Hans Petter Langtangen at Simula Research Laboratory and University of Oslo
DATE: today

# Very preliminary

_WARNING: This quick reference is very incomplete!_


===== Supported Formats =====

Doconce currently translates files to the following formats:

 * LaTeX (format `latex`)
 * HTML (format `html`)
 * reStructuredText (format `rst`)
 * StructuredText (format `st`)
 * plain (untagged) ASCII (format `plain`)
 * Sphinx (format `sphinx`)
 * Googlecode wiki (format `gwiki`)
 * MediaWiki, a la Wikipedia and Wikibooks (format `mwiki`)
 * Creoloe wiki (format `cwiki`)
 * Epydoc (format `epydoc`)
 * Pandoc (format `pandoc`, very experimental)

The best supported formats are `latex`, `sphinx`, `html`, and `plain`.

===== Title, Authors, and Date =====

A typical example of giving a title, a set of authors, and a date
reads
!bc
TITLE: On an Ultimate Markup Language
AUTHOR: H. P. Langtangen at Center for Biomedical Computing, Simula Research Laboratory and Dept. of Informatics, Univ. of Oslo
AUTHOR: Kaare Dump Email: dump@cyb.space.com at Segfault, Cyberspace Inc.
AUTHOR: A. Dummy Author
DATE: today
!ec
The title must appear on a single line.
The author syntax is
!bc
name Email: somename@adr.net at institution1 and institution2
!ec
where the email is optional, the "at" keyword is required if one or
more institutions are to be specified, and the "and" keyword
separates the institutions. Each author specification must appear
on a single line.
When more than one author belong to the
same institution, make sure that the institution is specified in an identical
way for each author.

The date can be set as any text different from `today` if not the
current date is wanted, e.g., `Feb 22, 2016`.


===== Section Types =====
label{quick:sections}

|----------------c--------|------------------c--------------------|
|      Section type       |        Syntax                         |
|----------------l--------|------------------l--------------------|
| chapter                 | `========= Heading ========` (9 `=`)  |
| section                 | `======= Heading =======`    (7 `=`)  |
| subsection              | `===== Heading =====`        (5 `=`)  |
| subsubsection           | `=== Heading ===`            (3 `=`)  |
| paragraph               | `__Heading.__`               (2 `_`)  |
| abstract                | `__Abstract.__` Running text...       |
|-----------------------------------------------------------------|

Note that abstracts are recognized by starting with `__Abstract.__` at
the beginning of a line and ending with three or more `=` signs of the
next heading.

===== Inline Formatting =====

Words surrounded by `*` are emphasized: `*emphasized words*` becomes
*emphasized words*. Similarly, an underscore surrounds words that
appear in boldface: `_boldface_` become _boldface_.

===== Lists =====

There are three types of lists: *bullet lists*, where each item starts
with `*`, *enumeration lists*, where each item starts with `o` and gets
consqutive numbers,
and *description* lists, where each item starts with `-` followed
by a keyword and a colon.
!bc
Here is a bullet list:

 * item1
 * item2
  * subitem1 of item2
  * subitem2 of item2
 * item3

Note that sublists are consistently indented by one or more blanks..
Here is an enumeration list:

 o item1
 o item2
   may appear on
   multiple lines
  o subitem1 of item2
  o subitem2 of item2
 o item3

And finally a description list:

 - keyword1: followed by
   some text
   over multiple
   lines
 - keyword2:
   followed by text on the next line
 - keyword3: and its description may fit on one line
!ec
The code above follows.

Here is a bullet list:

 * item1
 * item2
  * subitem1 of item2
  * subitem2 of item2
 * item3

Note that sublists are indented.
Here is an enumeration list:

 o item1
 o item2
   may appear on
   multiple lines
  o subitem1 of item2
  o subitem2 of item2
 o item3

And finally a description list:

 - keyword1: followed by
   some text
   over multiple
   lines
 - keyword2:
   followed by text on the next line
 - keyword3: and its description may fit on one line


===== Comments =====

Lines starting with `#` are treated as comments in the document
and translated to the proper syntax for comments in
the output document. Such comment lines
should not appear before LaTeX math blocks, verbatim code blocks,
or lists if the formats `rst` and `sphinx` are desired.

When using the Mako preprocessor one can also place comments in
the Doconce source file that will be removed by Mako before
Doconce starts processing the file. Mako comments are recognized
by lines starting with two hashes `##` or by blocks of text
inside the comment directives `%<doc>` (beginning) and `<%doc/>` (end).

Inline comments, in the text, that are meant as messages or notes to readers
(authors in particular)
are often useful and enabled by the syntax
!bc
[name: running text]
!ec
where `name` is the name or ID of an author or reader making the comment,
and `running text` is the comment. There must be a space after the colon.
Running
!bc sys
doconce format html mydoc.do.txt --skip_inline_comments
!ec
removes all such inline comments from the output. This feature makes it easy
to turn on and off notes to readers and is frequently used while writing
a document.

All inline comments to readers can also be physically
removed from the Doconce source if desired:
!bc sys
doconce remove_inline_comments mydoc.do.txt
!ec
This action is appropriate when all issues with such comments are resolved.

===== Verbatim/Computer Code =====

Inline verbatim code is typeset within back-ticks, as in
!bc
Some sentence with `words in verbatim style`.
!ec
resulting in Some sentence with `words in verbatim style`.

Multi-line blocks of verbatim text, typically computer code, is typeset
in between `!bc xxx` and `!ec` directives (which must appear on the
beginning of the line). A specification `xxx` indicates what verbatim
formatting style that is to be used. Typical values for `xxx` are
nothing, `cod` for a code snippet, `pro` for a complete program,
`sys` for a terminal session, `dat` for a data file (or output from a
program),
`Xpro` or `Xcod` for a program or code snipped, respectively,
in programming `X`, where `X` may be `py` for Python,
`cy` for Cython, `sh` for Bash or other Unix shells,
`f` for Fortran, `c` for C, `cpp` for C++, `m` for MATLAB,
`pl` for Perl. For output in `latex` one can let `xxx` reflect any
defined verbatim environment in the `ptex2tex` configuration file
(`.ptex2tex.cfg`). For `sphinx` output one can insert a comment
!bc
# sphinx code-blocks: pycod=python cod=fortran cppcod=c++ sys=console
!ec
that maps environments (`xxx`) onto valid language types for
Pygments (which is what `sphinx` applies to typeset computer code).

The `xxx` specifier has only effect for `latex` and
`sphinx` output. All other formats use a fixed monospace font for all
kinds of verbatim output.

# When showing copy from file in !bc envir, intent a character - otherwise
# ptex2tex is confused and starts copying...
Computer code can also be copied from a file:
!bc
 @@@CODE doconce_program.sh
 @@@CODE doconce_program.sh  fromto: doconce clean@^doconce split_rst
 @@@CODE doconce_program.sh  from-to: doconce clean@^doconce split_rst
!ec
The `@@@CODE` identifier must appear at the very beginning of the line.
The first specification copies the complete file `doconce_program.sh`.
The second specification copies from the first line matching the *regular
expression* `doconce clean` up to, but not including the line
matching the *regular expression* `^doconce split_rst`.
The third specification behaves as the second, but the line matching
the first regular expression is not copied (aimed at copying
text between begin-end comment pair in the file).

The copied line from file are in this example put inside `!bc shpro`
and `!ec` directives, if a complete file is copied, while the
directives become `!bc shcod` and `!ec` when a code snippet is copied
from file. In general, for a filename extension `.X`, the environment
becomes `!bc Xpro` or `!bc Xcod` for a complete program or snippet,
respectively. The enivorments (`Xcod` and `Xpro`) are only active
for `latex` and `sphinx` outout.

Important warnings:

 * A code block must come after some plain sentence (at least for successful
   output in reStructredText), not directly after a section/paragraph heading,
   table, comment, figure, or movie.
 * Verbatim code blocks inside lists can be ugly typeset in some
   output formats. A more robust approach is to replace the list by
   paragraphs with headings.

===== LaTeX Mathematics =====

Doconce supports inline mathematics and blocks of mathematics, using
standard LaTeX syntax. The output formats `sphinx`, `latex`, and `pdflatex`
work with this syntax while all other formats will just display the
raw LaTeX code.

Inline expressions are written in the standard
LaTeX way with the mathematics surrounded by dollar signs, as in
$Ax=b$. To help increase readability in other formats than `sphinx`,
`latex`, and `pdflatex`, inline mathematics may have a more human
readable companion expression. The syntax is like
!bc
$\sin(\norm{\bf u})$|$sin(||u||)$
!ec
That is, the LaTeX expression appears to the left of a vertical bar (pipe
symbol) and the more readable expression appears to the right. Both
expressions are surrounded by dollar signs. Plain text formats and HTML
will applied the expression to the right.

Blocks of LaTeX mathematics are written within
`!bt`
and
`!et` ("begin/end TeX") directives, just like computer code.
For example,
!bc
!bt
\begin{align*}
\nabla\cdot u &= 0,\\
\nabla\times u & 0.
\end{align*}
!et
!ec
will appear as
!bt
\begin{align*}
\nabla\cdot u &= 0,\\
\nabla\times u & 0.
\end{align*}
!et

One can use `#if FORMAT in ("latex", "pdflatex", "sphinx", "mwiki")` to let
the preprocessor choose a block of mathematics in LaTeX format
or (`#else`) a modified form more suited for plain text and wiki
formats without support for mathematics.

Any LaTeX syntax is accepted, but if output in the `sphinx` format
is important, one must know that `sphinx` does not support many
LaTeX constructs. For output both in `latex` and `sphinx` formats we
recommend the following:

  * Use only the equation environments `\[`, `\]`,
    `equation`, `equation*`, `align`, and `align*`.
  * Labels in multiple equation environments such as `align` are
    not (yet) handled by `sphinx`, so avoid inserting labels and referring
    to equation labels in `align` environments. Actually, `align*`
    is the preferred environment for multiple equations. Writing with
    also `sphinx` output in mind results in a slightly adjusted type
    of LaTeX writing.
  * LaTeX supports lots of fancy formatting, for example, multiple
    plots in the same figure, footnotes, margin notes, etc.
    Allowing other output formats, such as `sphinx`, makes it necessary
    to only utilze very standard LaTeX and avoid, for instance, more than
    one plot per figure. However, one can use preprocessor if-tests on
    the format (typically `# #ifdef format == "latex"`) to
    include special code for `latex` output and more straightforward
    typesetting for other formats. In this way, one can also allow
    advanced LaTeX features and fine tuning of resulting PDF document.


__LaTeX Newcommands.__
Text missing...


===== Figures and Movies =====

Figures and movies have almost equal syntax:
!bc
FIGURE: [relative/path/to/figurefile, width=500] Here goes the caption which must be on a single line. label{some:fig:label}

MOVIE: [relative/path/to/moviefile, width=500] Here goes the caption which must be on a single line. label{some:fig:label}
!ec
Note the mandatory comma after the figure/movie file.

The figure file can be listed without extension. Doconce will then find
the version of the file with the most appropriate extension for the chosen
output format. If not suitable version is found, Doconce will convert
another format to the desired one.

Movie files can either be a video or a wildcard expression for a
series of frames. In the latter case, a simple device in an HTML page
will display the individual frame files as a movie.

Combining several image files into one can be done by the
`convert` and `montage` programs from the ImageMagick suite:
!bc sys
montage file1.png file2.png ... file4.png -geometry +2+2  result.png
montage file1.png file2.png -tile x1 result.png
montage file1.png file2.png -tile 1x result.png

convert -background white file1.png file2.png +append tmp.png
!ec
Use `+append` for stacking left to right, `-append` for top to bottom.
The positioning of the figures can be controlled by `-gravity`.


===== Tables =====

The table in Section ref{quick:sections} was written with this
syntax:
!bc
|----------------c--------|------------------c--------------------|
|      Section type       |        Syntax                         |
|----------------l--------|------------------l--------------------|
| chapter                 | `========= Heading ========` (9 `=`)  |
| section                 | `======= Heading =======`    (7 `=`)  |
| subsection              | `===== Heading =====`        (5 `=`)  |
| subsubsection           | `=== Heading ===`            (3 `=`)  |
| paragraph               | `__Heading.__`               (2 `_`)  |
|-----------------------------------------------------------------|
!ec

Note that

 * Each line begins and ends with a vertical bar (pipe symbol).
 * Column data are separated by a vertical bar (pipe symbol).
 * There may be horizontal rules, i.e., lines with dashes for
   indicating the heading and the end of the table, and these may
   contain characters 'c', 'l', or 'r' for how to align headings or
   columns. The first horizontal rule may indicate how to align
   headings (center, left, right), and the horizontal rule after the
   heading line may indicate how to align the data in the columns
   (center, left, right).
 * If the horizontal rules are without alignment information there should
   be no vertical bar (pipe symbol) between the columns. Otherwise, such
   a bar indicates a vertical bar between columns in LaTeX.
 * Many output formats are so primitive that heading and column alignment
   have no effect.

===== Labels, References, Citations, and Index =====

The notion of labels, references, citations, and an index is adopted
from LaTeX with a very similar syntax. As in LaTeX, a label can be
inserted anywhere, using the syntax
!bc
label{name}
!ec
with no backslash
preceding the label keyword! It is common practice to choose `name`
as some hierarchical name, say `a:b:c`, where `a` and `b` indicate
some abbreviations for a section and/or subsection for the topic and
`c` is some name for the particular unit that has a label.

A reference to the label `name` is written as
!bc
ref{name}
!ec
again with no backslash before `ref`.

Single citations are written as
!bc
cite{name}
!ec
where `name` is a logical name
of the reference (again, LaTeX writers must not insert a backslash).
Bibliography citations often have `name` on the form
`Author1_Author2_YYYY`, `Author_YYYY`, or `Author1_etal_YYYY`, where
`YYYY` is the year of the publication.
Multiple citations at once is possible by separating the logical names
by comma:
!bc
cite{name1,name2,name3}
!ec

The bibliography is specified by a line `BIBFILE: name_bib.bib,
name_bib.rst, name_bib.py`, where `name` is the logical name of the
document (the doconce file will then normally have the name
`name.do.txt`), and the various files reflect different formattings of
the bibliography: '.bib' indicates a BibTeX file, '.rst' a reST-style
bibliography, and '.py' a Python list of dictionaries for specifying
the entries in the bibliography. The bibliography (as read from file)
is inserted where the `BIBFILE` keyword appears.

Doconce supports creating an index of keywords. A certain keyword
is registered for the index by a syntax like (no
backslash!)
!bc
index{name}
!ec
It is recommended to place any index of this type outside
running text, i.e., after (sub)section titles and in the space between
paragraphs. Index specifications placed right before paragraphs also
gives the doconce source code an indication of the content in the
forthcoming text. The index is only produced for the `latex`, `rst`, and
`sphinx` formats.

===== Capabilities of the "doconce" Program =====

The `doconce` program can be used for a number of purposes besides
transforming a `.do.txt` file to some format. Here is the
list of capabilities:

@@@CODE doconce_program.sh

===== Exercises =====

Doconce supports *Exercise*, *Problem*, and *Project*. These are typeset
as ordinary sections and referred to by their section labels.
The typical sketch of an exercise, problem, or project sections
looks as follows:
!bc
===== Problem: Derive the Formula for the Area of an Ellipse =====
label{problem:ellipsearea1}
file=ellipse_area.pdf
solution=ellipse_area1_sol.pdf

Derive an expression for the area of an ellipse by integrating
the area under a curve that defines half of the allipse.
Show each step in the mathematical derivation.

__Hint 1.__ Wikipedia has the formula for the curve.

__Hint 2.__ "Wolframalpha": "http://wolframalpha.com" can perhaps
compute the integral.
!ec
An exercise, problem, or project has certain elements:

  * A headline at the level of a subsection or subsubsection,
    containing one of the words "Exercise:", "Problem:", or
    "Project:", followed by a title. (Required.)
  * A standard label for referring to the exercise. (Optional.)
  * A name for the file with the result/answer (`file=filename`). (Optional.)
  * A name for the solution file (`solution=filename`), where the file
    name may be a URL. (Optional.)
  * The running text of the exercise. (Required.)
  * A sequence of hints, indicated as paragraphs. There can be a
    single hint, without any number, or several numbered hints.
    (Optional.)

===== Labels, Index, and Citations =====

===== Preprocessing =====

Doconce documents may utilize a preprocessor, either `preprocess` or
`mako`. The former is a C-style preprocessor that allows if-tests
and including other files (but not macros with arguments).
The `mako` preprocessor is much more advanced - it is actually a full
programming language, very similar to Python.

===== Resources =====

 * Excellent "Sphinx Tutorial" by C. Reller: "http://people.ee.ethz.ch/~creller/web/tricks/reST.html"

