
======= From Doconce to Other Formats =======
label{doconce2formats}

Transformation of a Doconce document to various other
formats applies the script `doconce format`:
!bc sys
Unix/DOS> doconce format format mydoc.do.txt
!ec
The `preprocess` program is always used to preprocess the file first,
and options to `preprocess` can be added after the filename. For example,
!bc sys
Unix/DOS> doconce format LaTeX mydoc.do.txt -Dextra_sections
!ec
The variable `FORMAT` is always defined as the current format when
running `preprocess`. That is, in the last example, `FORMAT` is
defined as `LaTeX`. Inside the Doconce document one can then perform
format specific actions through tests like `#if FORMAT == "LaTeX"`.

Inline comments in the text are removed from the output by
!bc sys
Unix/DOS> doconce format LaTeX mydoc.do.txt remove_inline_comments
!ec
One can also remove such comments from the original Doconce file
by running a helper script in the `bin` folder of the Doconce
source code:
!bc
Unix/DOS> doconce remove_inline_comments mydoc.do.txt
!ec
This action is convenient when a Doconce document reaches its final form.


===== HTML =====

Making an HTML version of a Doconce file `mydoc.do.txt`
is performed by
!bc sys
Unix/DOS> doconce format HTML mydoc.do.txt
!ec
The resulting file `mydoc.html` can be loaded into any web browser for viewing.

===== LaTeX =====

Making a LaTeX file `mydoc.tex` from `mydoc.do.txt` is done in two steps:
# Note: putting code blocks inside a list is not successful in many
# formats - the text may be messed up. A better choice is a paragraph
# environment, as used here.

__Step 1.__ Filter the doconce text to a pre-LaTeX form `mydoc.p.tex` for
     `ptex2tex`:
!bc sys
Unix/DOS> doconce format LaTeX mydoc.do.txt
!ec
LaTeX-specific commands ("newcommands") in math formulas and similar
can be placed in files `newcommands.tex`, `newcommands_keep.tex`, or
`newcommands_replace.tex` (see Section ref{newcommands}). 
If these files are present, they are included in the LaTeX document 
so that your commands are defined.

__Step 2.__ Run `ptex2tex` (if you have it) to make a standard LaTeX file,
!bc sys
Unix/DOS> ptex2tex mydoc
!ec
or just perform a plain copy,
!bc sys
Unix/DOS> cp mydoc.p.tex mydoc.tex
!ec
Doconce generates a `.p.tex` file with some preprocessor macros.
For example, to enable font Helvetica instead of the standard
Computer Modern font,
!bc sys
Unix/DOS> ptex2tex -DHELVETICA mydoc
!ec
The title, authors, and date are by default typeset in a non-standard
way to enable a nicer treatment of multiple authors having
institutions in common. The standard LaTeX "maketitle" heading
is also available through
!bc sys
Unix/DOS> ptex2tex -DTRAD_LATEX_HEADING mydoc
!ec

The `ptex2tex` tool makes it possible to easily switch between many
different fancy formattings of computer or verbatim code in LaTeX
documents. After any `!bc sys` command in the Doconce source you can
insert verbatim block styles as defined in your `.ptex2tex.cfg`
file, e.g., `!bc sys cod` for a code snippet, where `cod` is set to
a certain environment in `.ptex2tex.cfg` (e.g., `CodeIntended`).
There are over 30 styles to choose from.

__Step 3.__ Compile `mydoc.tex`
and create the PDF file:
!bc sys
Unix/DOS> latex mydoc
Unix/DOS> latex mydoc
Unix/DOS> makeindex mydoc   # if index
Unix/DOS> bibitem mydoc     # if bibliography
Unix/DOS> latex mydoc
Unix/DOS> dvipdf mydoc
!ec
If one wishes to use the `Minted_Python`, `Minted_Cpp`, etc., environments
in `ptex2tex` for typesetting code, the `minted` LaTeX package is needed.
This package is included by running `doconce format` with the
`-DMINTED` option:
!bc sys
Unix/DOS> ptex2tex -DMINTED mydoc
!ec
In this case, `latex` must be run with the
`-shell-escape` option:
!bc sys
Unix/DOS> latex -shell-escape mydoc
Unix/DOS> latex -shell-escape mydoc
Unix/DOS> makeindex mydoc   # if index
Unix/DOS> bibitem mydoc     # if bibliography
Unix/DOS> latex -shell-escape mydoc
Unix/DOS> dvipdf mydoc
!ec
The `-shell-escape` option is required because the `minted.sty` style
file runs the `pygments` program to format code, and this program
cannot be run from `latex` without the `-shell-escape` option.


===== Plain ASCII Text =====

We can go from Doconce "back to" plain untagged text suitable for viewing
in terminal windows, inclusion in email text, or for insertion in
computer source code:
!bc sys
Unix/DOS> doconce format plain mydoc.do.txt  # results in mydoc.txt
!ec

===== reStructuredText =====

Going from Doconce to reStructuredText gives a lot of possibilities to
go to other formats. First we filter the Doconce text to a
reStructuredText file `mydoc.rst`:
!bc sys
Unix/DOS> doconce format rst mydoc.do.txt
!ec
We may now produce various other formats:
!bc sys
Unix/DOS> rst2html.py  mydoc.rst > mydoc.html # HTML
Unix/DOS> rst2latex.py mydoc.rst > mydoc.tex  # LaTeX
Unix/DOS> rst2xml.py   mydoc.rst > mydoc.xml  # XML
Unix/DOS> rst2odt.py   mydoc.rst > mydoc.odt  # OpenOffice
!ec
The OpenOffice file `mydoc.odt` can be loaded into OpenOffice and
saved in, among other things, the RTF format or the Microsoft Word format.
That is, one can easily go from Doconce to Microsoft Word.

===== Sphinx =====

Sphinx documents can be created from a Doconce source in a few steps.

__Step 1.__ Translate Doconce into the Sphinx dialect of
the reStructuredText format:
!bc sys
Unix/DOS> doconce format sphinx mydoc.do.txt
!ec

__Step 2.__ Create a Sphinx root directory with a `conf.py` file, 
either manually or by using the interactive `sphinx-quickstart`
program. Here is a scripted version of the steps with the latter:
!bc sys
mkdir sphinx-rootdir
sphinx-quickstart <<EOF
sphinx-rootdir
n
_
Name of My Sphinx Document
Author
version
version
.rst
index
n
y
n
n
n
n
y
n
n
y
y
y
EOF
!ec
These statements as well as points 3-5 can be automated by the command
!bc sys
Unix/DOS> doconce sphinx_dir mydoc.do.txt
!ec
More precisely, in addition to making the `sphinx-rootdir`,
this command generates a script `tmp_make_sphinx.sh` which
can be run to carry out steps 3-5, and later to remake the
sphinx document.

__Step 3.__ Move the `tutorial.rst` file to the Sphinx root directory:
!bc sys
Unix/DOS> mv mydoc.rst sphinx-rootdir
!ec
If you have figures in your document, the relative paths to those will
be invalid when you work with `mydoc.rst` in the `sphinx-rootdir`
directory. Either edit `mydoc.rst` so that figure file paths are correct,
or simply copy your figure directory to `sphinx-rootdir` (if all figures
are located in a subdirectory).

__Step 4.__ Edit the generated `index.rst` file so that `mydoc.rst`
is included, i.e., add `mydoc` to the `toctree` section so that it becomes
!bc
.. toctree::
   :maxdepth: 2

   mydoc
!ec
(The spaces before `mydoc` are important!)

__Step 5.__ Generate, for instance, an HTML version of the Sphinx source:
!bc sys
make clean   # remove old versions
make html
!ec
Many other formats are also possible.

__Step 6.__ View the result:
!bc sys
Unix/DOS> firefox _build/html/index.html
!ec

Note that verbatim code blocks can be typeset in a variety of ways
depending the argument that follows `!bc`: `cod` gives Python
(`code-block:: python` in Sphinx syntax) and `cppcod` gives C++, but
all such arguments can be customized both for Sphinx and LaTeX output.

# Desired extension: sphinx can utilize a "pycod" or "c++cod"
# instruction as currently done in latex for ptex2tex and write 
# out the right code block name accordingly.


===== Google Code Wiki =====

There are several different wiki dialects, but Doconce only support the
one used by http://code.google.com/p/support/wiki/WikiSyntax<Google Code>.
The transformation to this format, called `gwiki` to explicitly mark
it as the Google Code dialect, is done by
!bc sys
Unix/DOS> doconce format gwiki mydoc.do.txt
!ec
You can then open a new wiki page for your Google Code project, copy
the `mydoc.gwiki` output file from `doconce format` and paste the
file contents into the wiki page. Press _Preview_ or _Save Page_ to
see the formatted result.

When the Doconce file contains figures, each figure filename must be
replaced by a URL where the figure is available. There are instructions
in the file for doing this. Usually, one performs this substitution
automatically (see next section).


===== Tweaking the Doconce Output =====

Occasionally, one would like to tweak the output in a certain format
from Doconce. One example is figure filenames when transforming
Doconce to reStructuredText. Since Doconce does not know if the
`.rst` file is going to be filtered to LaTeX or HTML, it cannot know
if `.eps` or `.png` is the most appropriate image filename.
The solution is to use a text substitution command or code with, e.g., sed,
perl, python, or scitools subst, to automatically edit the output file
from Doconce. It is then wise to run Doconce and the editing commands
from a script to automate all steps in going from Doconce to the final
format(s). The `make.sh` files in `docs/manual` and `docs/tutorial` 
constitute comprehensive examples on how such scripts can be made.
