Documentation for DocumentationCompiler v1.5

[Andres.Pozo]

Hi,

I am trying to compile the documentation for my scripts but none of them compile with the latest version of DocumentationCompiler. It seems to be some problem with the references (\ref) but since the latest version has not documentation I don't know what it's happening.

Fortunately I have a copy of the version 1.3.7 and I can still use it, however it would be better to be able to use the latest version.

Another wish: the directory path in the section "Target system" doesn't remember the value between executions. I would be very helpful if it would remember its last value.

[Juan Conejero]

Hi Andrés,

Yes, we need documentation for the latest version of the PIDoc compiler, and it is urgent. While I find the time to write it, I'll try to solve all your doubts here.

Bibliographic references are symbolic since version 1.5 of PIDoc. For example, you can define a reference with the \reference command, typically at the end of the PIDoc document (just before the \make command):

\reference sedgewick_2011 { Robert Sedgewick, Kevin Wayne (2011), \e { Algorithms }, 4th Ed., Addison-Wesley Professional, pp. 345--347 }

and you can insert links to it with the \ref command as follows:

... based on quick selection algorithms \ref sedgewick_2011 and hard-coded selection networks ...

In this example, 'sedgewick_2011' is the reference identifier. The compiler numbers all references and replaces all links with the appropriate reference numbers automatically.

In previous versions of PIDoc, references were always numeric. The above example could be:

\reference 9 { Robert Sedgewick, Kevin Wayne (2011), \e { Algorithms }, 4th Ed., Addison-Wesley Professional, pp. 345--347 }

... based on quick selection algorithms \ref 9 and hard-coded selection networks ...

Symbolic references have two main advantages: reference identifiers greatly improve legibility of PIDoc source code, and you can change the order of your references as you want because the compiler handles all substitutions transparently.

Equations, figures and tables can also be referenced symbolically, but these require more in-depth descriptions.

[Andres.Pozo]

Thanks Juan. I will update the documentation of my scripts.

[Andres.Pozo]

Hi Juan,

in the last version you have removed the tag \math{}. I suppose this is because of the integration of LaTeX equations.

Could you write a small example with an equation? I know the syntax of LaTeX but I don't know how to use it in PI.

[Juan Conejero]

In PIDoc 1.5 we have two commands for automatic LaTeX equation generation: \equation and \im. I'll describe these commands below.

\equation[<equation-parameters>]_opt <equation-body>

This command generates a LaTeX equation as a new paragraph block. Supported \equation parameters are the following: 

import

Specifies an external equation. If this parameter is used, <equation-body> is interpreted as the path to an existing LaTeX source file (usually carrying the .tex or .latex extension). This parameter is mutually exclusive with the inline parameter (see below).

inline

Specifies an internal equation.  If this parameter is used, <equation-body> is interpreted as the LaTeX source code of the equation to be rendered. This parameter is mutually exclusive with the import parameter (see above). When neither inline nor import are used, equations are assumed to be defined internally (i.e., inline is assumed by default).

numbered:equation-id_opt

Specifies a numbered equation. The PIDoc compiler automatically numbers all numbered equations. When equation-id is specified, it is the unique identifier of this equation, which can be used for equation references with the \eqnref command. equation-id must be a unique valid C identifier. This parameter is mutually exclusive with the unnumbered parameter (see below).

unnumbered

Specifies an unnumbered equation. This parameter is useful when all equations are being numbered by default (through a global compiler option).

scale:scale-factor

Equation scaling factor. scale-factor is a positive real number in the range ]0,10]. The default scaling factor is 1.0, corresponding to the normal equation scale adapted to the default body text style. You can use this parameter to fine tune equation sizes, especially in figure descriptions or boxed text elements.

<block-parameters>_-

The \equation command partially supports the standard block parameter set (see the PIDoc reference documentation for older versions), where the minus sign subscript denotes partial support. Horizontal alignment and block floating parameters are not supported by \equation.

\im[<im-parameters>]_opt <equation-body>

The \im command generates a LaTeX equation as an inline character block. The \im command supports the scale parameter with the same meaning as for the \equation command, plus a subset of block parameters.


Verbatim Blocks

Since PIDoc and LaTeX are quite similar syntax wise, the source code of a LaTeX equation usually conflicts with the document definition except in the simplest cases. To solve this problem (and other similar issues that occur with current and future PIDoc language extensions) we have verbatim blocks since PIDoc 1.5. A verbatim block is formally defined as:

#: <verbatim-text>_opt :#

where <verbatim-text> is any sequence of non-null UTF-8 characters. Verbatim blocks are not parsed by the PIDoc compiler, which allows you to insert virtually anything in a PIDoc source file. Using verbatim blocks, you can define LaTeX equations of any complexity. Here's a relatively simple example:

         \equation[numbered:noise_evaluation_weighting_function] { #:
            $$
            w_i = \frac{1}{(k_i \cdot {\sigma_n}_i)^2} \; ,
            $$
         :# }

and this is a more complex example:

            \equation[numbered:eqn_sigma_clipping_rejection] { #:
               $$
               \begin{array}{l l}
                \mbox{SigmaClippingRejection}(\mathbf{x};s_{low},s_{high}) \; : \\
                     \hspace{1em} \mbox{do} \\
                        \hspace{2em} m \leftarrow \mbox{median}(x_0, \, \dots, \, x_{N-1}) \\
                        \hspace{2em} \sigma \leftarrow \mbox{stddev}(x_0, \, \dots, \, x_{N-1}) \\
                        \hspace{2em} n \leftarrow 0 \\
                        \hspace{2em} \mbox{for} \; i \leftarrow 0 \; \mbox{to} \; N-1 \\
                           \hspace{3em} \mbox{if SigmaClipping}(x_i;m,\sigma,s_{low},s_{high}) \\
                              \hspace{4em} \mbox{reject} \; x_i \\
                              \hspace{4em} n \leftarrow n + 1 \\
                           \hspace{3em} \mbox{end} \\
                        \hspace{2em} \mbox{end} \\
                        \hspace{2em} N \leftarrow N - n \\
                     \hspace{1em} \mbox{while} \; n > 0 \; \mbox{and} \; N > 3 \; ,
               \end{array}
               $$
            :# }

Verbatim blocks can also be used in inline equations with the \im command:

\im {#: s_{low} :#} and \im {#: s_{high} :#} are the clipping point parameters expressed in sigma units.

However, in simpler cases verbatim blocks are not necessary:

where \im x, \im m and \im \\sigma are the pixel value, the median and the standard deviation of the current stack, respectively.

In this example, note that we have escaped the "sigma" word to prevent it from being parsed as a PIDoc command. An alternative would have been:

\im {#: \sigma :#}

but in these cases escaping one or two (and perhaps three) words is a much simpler solution. Also worth noting is that in the fragment:

\im x,

the comma is not part of the LaTeX rendition, since it is parsed as a punctuator (a special class of separator) by the PIDoc compiler.


Automatic LaText Prefixes

The PIDoc compiler automatically inserts a document prefix to render all equations. If <tex-source-code> is the parsed TeX source code of the equation, the actual code sent to the latex compiler is:

\documentclass[landscape,a0]{article}
\usepackage[paperwidth=100cm,paperheight=100cm,margin=0pt]{geometry}
\pagestyle{empty}
\begin{document}
\noindent
<tex-source-code>
\end{document}

In addition, the \im command inserts a double dollar command '$$' before and after the equation source code, so you don't have to use any command to turn on LaTeX's equation mode with \im. You do need those commands with the \equation command, however.


Equation Cache

The PIDoc compiler uses a fast-access cache structure to store temporarily all rendered LaTeX equations during the current compilation. This greatly improves performance and reduces disk space requirements, especially when the same equation is being used multiple times in the same document. For example, thanks to the cache you don't have to worry about using small inline equations many times, such as "\im x" for example: the compiler will only render it at the first occurrence, and will reuse the already rendered item for the rest of instances of "\im x" in your document.


LaTeX Runtime Requirements

Currently, automatic generation of LaTeX equations only works on Linux and Mac OS X. The specific requirements are:

- A working LaTeX distribution. On Linux and FreeBSD this is normally granted without problems, since LaTeX is either part of the underlying operating system distribution, or it can be installed very easily with the native package manager (including the ports system on FreeBSD). On Linux and UNIX, Tex Live is recommended, and is also the default on modern systems. On Mac OS X, you can install a package such as MacTeX for example. There are similar options on Windows, but I haven't tested any of them.

- The pdf2svg utility program by David Barton. You can download the source code of this utility from the linked page and build it yourself on your machine following the instructions given by the author (you need a working Xcode installation on Mac OS X, which you already have if you are a developer). pdf2svg depends on Poppler and Cairo, two open-source libraries that are readily available on Linux. On Mac OS X, you can install them easily using the MacPorts project.

The executables required by PIDoc's equation renderer are the following:

latex
dvips
epstopdf
pdf2svg

All of them must be accessible from the PATH environment variable. On Mac OS X, you may need to adjust your .profile, depending on the LaTeX distribution that you have installed.