main.tex

\documentclass{documentation}
\makeatletter
\def\maketitle{%
\begin{titlepage}
\centering
{\Huge\@title}\vskip0.5ex
{\Large\@author}\vskip0.5ex
{version~\theversion}\vskip1ex
\includegraphics[height=10cm]{title_graph}
\setcounter{page}{-1}
\end{titlepage}
}
\make@equation{Rig}{\mathrm{R}}{8.3144621}{75}{J\,mol^{-1}\,K^{-1}}
\make@equation[23]{NAvo}{\mathcal{N}_\text{Avo}}{6.02214129}{27}{mol^{-1}}
\make@litteralEquation{vacPerme}{\mu_0}     {4\pi\,10^{-7}}{m\,kg\,s^2\,A^2}
\make@library{Antioch}
\makeatother
\begin{document}

\title{Documentation goodies}
\author{S.~Plessis}
\version{0}{0}{0}
\maketitle

\begin{abstract}
Some nice capabilities, most of them are for
preamble macros and definitions.
\end{abstract}

\tableofcontents

\chapter{A nice picture for a chapter}
\graphAtPaperCenter{chap_ex}

\section[section_ex]{Works with section too}

This class provides the command \verb!\graphAtPaperCenter[*width*]{*fig to insert*}! which
will place the figure at the center of the paper, taking into
account the two-sided margins, and will make it the paper width. A default
argument enables to change the width of the graph to be inserted.

The \verb!\section! command has been modified, it includes now an optional
argument wich is a graph to be inserted in the left margin.

\begin{verbatim}
\chapter{A nice picture for a chapter}
\graphAtPaperCenter{chap_ex}

\section[section_ex]{Works with section too}
\end{verbatim}

The class takes automatically into account the size
of the left margin (as we're on a double-sided document). It's still
possible to lure it into thinking he's on the previous page, the
principle is to be at the bottom of the page, just at the right
amount of space so \TeX\ will make the changing page move after
the width calculation of the graphics and before printing
the section title. 
In that case, a simple \verb!\newpage! will increment the page
counter before the calculations of the width of the graphics,
thus fix the possible problem.

\section[sec_2]{Meta-meta macros and meta-macros}

\subsection{Names}

To define a formatting, there's the meta-meta macro \verb!make@!, it takes
three arguments including an optional. It needs to be used between
\verb!\makeatletter! and \verb!\makeatother! of course, and the
idea is to create a special formatting for concepts. For instance,
there are already defined the special formatting
\begin{verbatim}
\make@{program}   {sf}
\make@{library}   {tt}
\make@[bf]{object}{tt}
\make@{file}      {sf}
\make@{prog}      {prog@type}
\end{verbatim}

What is does is that for each call \verb!\make@[format again]{something}{format}!, it creates
the macros
\begin{itemize}
\item \verb!\something!, that will format its argument 
        (ex: \verb!\program{Doxygen}! gives \program{Doxygen});
\item \verb!\make@something{*a name*}!, \verb!make@something{hey}!
        for instance will define the macro \verb!\hey! that
        will print \verb!\something{hey}!;
\item \verb!\font@something!, which formats whatever argument you give it.
\end{itemize}
Typically, you provide a family (of font) as second argument, and a shape (of font)
as optional argument (default is \verb!upshape!).

\subsection{Physical quantities}

Another nice meta macro is the \verb!\make@equation!, it uses a meta-meta macro,
but there's not a real interest in going into too much details. An example
will be easier to understand:
\begin{verbatim}
\make@equation{Rig}{\mathrm{R}}{8.3144621}{75}{J\,mol^{-1}\,K^{-1}}
\end{verbatim}
will create the macros:
\begin{itemize}
\item \verb!\Rig!     which gives \Rig;
\item \verb!\Rigval!  which gives \Rigval;
\item \verb!\Rigdval! which gives \Rigdval;
\item \verb!\Rignum!  which gives \Rignum;
\item \verb!\Rigunit! which gives \Rigunit;
\item \verb!\RigEquation! which gives \RigEquation.
\end{itemize}
An optional argument gives the power in scientific notation if needed:
\begin{verbatim}
\make@equation[23] {NAvo} {\mathcal{N}_\text{Avo}}{6.02214129}{27}{mol^{-1}}
\end{verbatim}
\verb!\NAvoval! gives \NAvoval.

Sometimes, we want to define a physical quantity with respect to others:
\begin{verbatim}
\make@litteralEquation{vacPerme}{\mu_0}{4\pi\,10^{-7}}{m\,kg\,s^2\,A^2}
\end{verbatim}
and the vaccum permeability will be given by \verb!\vacPerme! and friends:
\begin{itemize}
\item \verb!\vacPerme!         gives \vacPerme;
\item \verb!\vacPermeval!      gives \vacPermeval;
\item \verb!\vacPermedval!     gives \vacPermedval;
\item \verb!\vacPermenum!      gives \vacPermenum;
\item \verb!\vacPermeunit!     gives \vacPermeunit;
\item \verb!\vacPermeEquation! gives \vacPermeEquation;
\end{itemize}

\section{Units}

The units are printed using the \verb!unit{}! command. It
works regardless if we are in math mode or not: the
commands \verb!$\unit{J}$! and \verb!\unit{J}! will produce
strictly the same output. As for formatting between units,
you \emph{\underline{\textbf{must}}} use  the small space \verb!\,!. If you want something
else, redefine the parser using the macro \verb!unitParser{*new definition*}!,
for instance:
\begin{verbatim}
\unitParser{\cdot}
\end{verbatim}
will make the units look from \unit{J\,s^{-1}} to
{\unitParser{\cdot}
\unit{J\,s^{-1}}}. In all cases, you write \verb!\unit{J\,s^{-1}}!.

The \verb!\unit{}! macro supports parenthesises:
\verb!\unit{(J\,mol^{-1})^2\,(g^2\,s^{-2})}! gives
\unit{(J\,mol^{-1})^2\,(g^2\,s^{-2})}.

Something important to note: only the parser is
actually in math mode, the unit itself, the power
and any subscript are in normal mode:\\
\verb!\unit{J_{abc $x = y \times z$}^{$x^2 + y^2 = z^2$}}!:
\unit{J_{abc $x = y \times z$}^{$x^2 + y^2 = z^2$}}.
\smallskip

To obtain the same font in math mode, use the \verb!\unitFont{}!
command (no more `\$'!):\\
\verb!\unit{J_{abc \unitFont{x = y \times z}}^{$x^2 + y^2 = z^2$}}!:
\unit{J_{abc \unitFont{x = y \times z}}^{$x^2 + y^2 = z^2$}}.

\chapter{Other stuff}
\graphAtPaperCenter{chap_2}

\section{Equations}

Now we refer to equations that are usually somewhere in the
code, and certainly in some object. Let's say we have a
\object{CppObject}
in which there is the fundamental equation
$x + y = z$, we will state it as:
\begin{verbatim}
\begin{equationCode}{CppObject}
x + y = z
\end{equationCode}
\end{verbatim}
it will print
\begin{equationCode}{CppObject}
x + y = z
\label{eqCode}
\end{equationCode}
The nice thing is that the length of the object's name will adapt
if need be:
\begin{equationCode}{ALongCppObjectNameForAComplicatedThing}
x^2 + y^2 = z^2
\end{equationCode}

Of course, because we are civilized people, we want chemical
reactions:
\begin{verbatim}
\begin{chemicalEquation}
\ce{N2 + O2 -> Air}
\end{chemicalEquation}
\end{verbatim}
which will print as:
\begin{chemicalEquation}
\ce{N2 + O2 -> Air}
\label{chemEq}
\end{chemicalEquation}

And ``bien s\^ur'', you can label them, as show Eq.~\ref{eqCode} and
Reac.~\ref{chemEq}.

\section{Codes}

It happens quite often for some serious application that
you want to give some terminal examples:
\begin{verbatim}
\terminal{I am writing in the terminal}
\end{verbatim}

\terminal{I am writing in the terminal}

Now the terminal is fully customizable. Its parameters are:
\begin{itemize}
\item the characters' color;
\item the background color;
\item the font; and
\item the PS1.
\end{itemize}
All are modifiable via the commands \verb!terminalMod*name*!,
and all modifications follows \TeX's rules of scope.
{
\begin{verbatim}
\terminalModPSone{[other user@somewhere else \$]}
\terminalModwrite{black}
\terminalModfont{\tt}
\terminalModbackground{cyan}
\terminal{I am writing too!}
\end{verbatim}
\terminalModPSone{[other user@somewhere else \$]}
\terminalModwrite{black}
\terminalModfont{\tt}
\terminalModbackground{cyan}
\terminal{I am writing too!}
}

Now the real interest in having a terminal is not
necessarily showing off, we may want to show the effect
of some program we wrote the world can't live without.
Using the package \textsf{listings}, this class defines
a \texttt{C++} and a \texttt{xml} environment. More
details on the subtleties to be found in the
\textsf{listings} package documentation.

Here are some example taken from \Antioch's documentation.
The \texttt{xml} environment,
\begin{verbatim}
\begin{xml}
<?xml version="1.0"?>
<ctml>
  <reactionData>
    <!-- my very first xml reaction, how cute! -->
    <reaction reversible="yes" type="Elementary" id="Reaction1">
      <equation>NO + O [=] O2 + N </equation>
      <reactants>NO:1 O:1 </reactants>
      <products>O2:1 N:1 </products>
      <rateCoeff>
        <Arrhenius>
           <A units="m3/kmol/s">8.4e+09</A>
           <E units="cal/mol">38526.0</E>
        </Arrhenius>
      </rateCoeff>
    </reaction>
  </reactionData>
</ctml>
\end{xml}
\end{verbatim}
gives
\begin{xml}
<?xml version="1.0"?>
<ctml>
  <reactionData>
    <!-- my very first xml reaction, how cute! -->
    <reaction reversible="yes" type="Elementary" id="Reaction1">
      <equation>NO + O [=] O2 + N </equation>
      <reactants>NO:1 O:1 </reactants>
      <products>O2:1 N:1 </products>
      <rateCoeff>
        <Arrhenius>
           <A units="m3/kmol/s">8.4e+09</A>
           <E units="cal/mol">38526.0</E>
        </Arrhenius>
      </rateCoeff>
    </reaction>
  </reactionData>
</ctml>
\end{xml}

And the \textsf{cpp} environment
\begin{verbatim}
\begin{cpp} 
// 1 gram 
// light celerity
// Energy contained in 1 gram
Antioch::PhysicalQuantity<double> m(1.,"g"), c(299792458.,"m.s-1"), 
                                  E = m * c * c; 

std::cout << E.value() << " " << E.unit() << std::endl;

E.change_unit_to("J");
std::cout << E.value() << " " << E.unit() << std::endl;

E.change_unit_to("cal");
std::cout << E.value() << " " << E.unit() << std::endl;

E.change_unit_to_SI();
std::cout << E.value() << " " << E.unit() << std::endl;
\end{cpp}
\end{verbatim}
which gives
\begin{cpp} 
// 1 gram 
// light celerity
// Energy contained in 1 gram
Antioch::PhysicalQuantity<double> m(1.,"g"), c(299792458.,"m.s-1"), 
                                  E = m * c * c; 

std::cout << E.value() << " " << E.unit() << std::endl;

E.change_unit_to("J");
std::cout << E.value() << " " << E.unit() << std::endl;

E.change_unit_to("cal");
std::cout << E.value() << " " << E.unit() << std::endl;

E.change_unit_to_SI();
std::cout << E.value() << " " << E.unit() << std::endl;
\end{cpp}

It is often useful to show the results of a specific program
on the terminal, as in the example above. Thus there are
also the \verb!cpp|! and \verb!|cpp! environments that will
basically only draw a vertical line where we expect it. It
is useful in the given cases below:
\begin{multicols}{2}
\begin{verbatim}
\noindent
\begin{minipage}{0.55\linewidth}
\begin{cpp|} 
// 1 gram 
// light celerity
// Energy contained in 1 gram
Antioch::PhysicalQuantity<double> 
        m(1.,"g"),
        c(299792458.,"m.s-1"),
        E = m * c * c; 

std::cout << E.value() << " " 
          << E.unit() << std::endl;

E.change_unit_to("J");
std::cout << E.value() << " " 
          << E.unit() << std::endl;

E.change_unit_to("cal");
std::cout << E.value() << " " 
          << E.unit() << std::endl;

E.change_unit_to_SI();
std::cout << E.value() << " " 
          << E.unit() << std::endl;
\end{cpp|}
\end{minipage}\hfill
\begin{minipage}{0.44\linewidth}
\terminal{%
./program.x\\
8.987552e+16 g.m.s-1.m.s-1\\
8.987552e+13 J\\
2.146640e+13 cal \\
8.987552e+13 kg.m2.s-2%
}
\end{minipage}
\end{verbatim}
\end{multicols}
That will produces\\
\noindent
\begin{minipage}{0.55\linewidth}
\begin{cpp|} 
// 1 gram 
// light celerity
// Energy contained in 1 gram
Antioch::PhysicalQuantity<double> 
        m(1.,"g"),
        c(299792458.,"m.s-1"),
        E = m * c * c; 

std::cout << E.value() << " " 
          << E.unit() << std::endl;

E.change_unit_to("J");
std::cout << E.value() << " " 
          << E.unit() << std::endl;

E.change_unit_to("cal");
std::cout << E.value() << " " 
          << E.unit() << std::endl;

E.change_unit_to_SI();
std::cout << E.value() << " " 
          << E.unit() << std::endl;
\end{cpp|}
\end{minipage}\hfill
\begin{minipage}{0.44\linewidth}
\terminal{%
./program.x\\
8.987552e+16 g.m.s-1.m.s-1\\
8.987552e+13 J\\
2.146640e+13 cal \\
8.987552e+13 kg.m2.s-2%
}
\end{minipage}

And the same thing but the other way
around:
\begin{multicols}{2}
\begin{verbatim}
\noindent
\begin{minipage}{0.44\linewidth}
\terminal{%
./program.x\\
8.987552e+16 g.m.s-1.m.s-1\\
8.987552e+13 J\\
2.146640e+13 cal \\
8.987552e+13 kg.m2.s-2%
}
\end{minipage}\hfill
\begin{minipage}{0.55\linewidth}
\begin{|cpp} 
// 1 gram 
// light celerity
// Energy contained in 1 gram
Antioch::PhysicalQuantity<double> 
        m(1.,"g"),
        c(299792458.,"m.s-1"),
        E = m * c * c; 

std::cout << E.value() << " " 
          << E.unit() << std::endl;

E.change_unit_to("J");
std::cout << E.value() << " " 
          << E.unit() << std::endl;

E.change_unit_to("cal");
std::cout << E.value() << " " 
          << E.unit() << std::endl;

E.change_unit_to_SI();
std::cout << E.value() << " " 
          << E.unit() << std::endl;
\end{|cpp}
\end{minipage}
\end{verbatim}
\end{multicols}
\noindent
\begin{minipage}{0.44\linewidth}
\terminal{%
./program.x\\
8.987552e+16 g.m.s-1.m.s-1\\
8.987552e+13 J\\
2.146640e+13 cal \\
8.987552e+13 kg.m2.s-2%
}
\end{minipage}\hfill
\begin{minipage}{0.55\linewidth}
\begin{|cpp} 
// 1 gram 
// light celerity
// Energy contained in 1 gram
Antioch::PhysicalQuantity<double> 
        m(1.,"g"),
        c(299792458.,"m.s-1"),
        E = m * c * c; 

std::cout << E.value() << " " 
          << E.unit() << std::endl;

E.change_unit_to("J");
std::cout << E.value() << " " 
          << E.unit() << std::endl;

E.change_unit_to("cal");
std::cout << E.value() << " " 
          << E.unit() << std::endl;

E.change_unit_to_SI();
std::cout << E.value() << " " 
          << E.unit() << std::endl;
\end{|cpp}
\end{minipage}

\section{Others}

\begin{remark}
There is a \texttt{remark} environment, where you can
put your remarks. This remark is produced by:
\begin{verbatim}
\begin{remark}
There is a \texttt{remark} environment, where you can
put your remarks. This remark is produced by:
verbatim-mise-en-abyme
\end{remark}
\end{verbatim}
\end{remark}

\warning{In case something needs to be known, there is a \textbackslash warning\{*text*\} macro.}

There is a \verb!\version{major}{minor}{micro}! macro,
\verb!\theversion! will print it (see title page).

\end{document}