Merge branch 'master' of https://scm.cri.ensmp.fr/git/Faustine
[Faustine.git] / interpretor / faust-0.9.47mr3 / documentation / faust-quick-reference-src / chapters / mathdoc.tex
1 \chapter{Mathematical Documentation}
2 \label{chapter:mdoc}
3
4 The \faust compiler provides a mechanism to produce a self-describing documentation of the mathematical semantic of a \faust program, essentially as a pdf file. The corresponding options are \lstinline!-mdoc! (short) or \lstinline!--mathdoc! (long).
5
6 \section{Goals of the mathdoc}
7 \label{sec:goals-of-mdoc}
8
9 There are three main goals, or uses, of this mathematical documentation:
10 \begin{enumerate}
11 \item to preserve signal processors, independently from any computer language but only under a mathematical form;
12 \item to bring some help for debugging tasks, by showing the formulas as they are really computed after the compilation stage;
13 \item to give a new teaching support, as a bridge between code and formulas for signal processing.
14 \end{enumerate}
15
16 \section{Installation requirements}
17 \label{sec:inst-requ}
18
19 \begin{itemize}
20 \item \lstinline!faust!, of course!
21 \item \lstinline!svg2pdf! (from the Cairo 2D graphics library), to convert block-diagrams, as \latex doesn't eat \svg directly yet...
22 \item \lstinline!breqn!, a \latex package to handle automatic breaking of long equations,
23 \item \lstinline!pdflatex!, to compile the \latex output file.
24 \end{itemize}
25
26
27 \section{Generating the mathdoc}
28 \label{sec:generating-mdoc}
29
30 The easiest way to generate the complete mathematical documentation is to call the \lstinline!faust2mathdoc! script on a \faust file, as the \lstinline!-mdoc! option leave the documentation production unfinished. For example:
31 \begin{lstlisting}
32 faust2mathdoc noise.dsp
33 \end{lstlisting}
34
35 \subsection{Invoking the -mdoc option}
36 \label{sec:invoking-mdoc}
37
38 Calling directly \lstinline!faust -mdoc! does only the first part of the work, generating:
39 \begin{itemize}
40 \item a top-level directory, suffixed with "\texttt{-mdoc}",
41 \item 5 subdirectories (\lstinline!cpp/!, \lstinline!pdf/!, \lstinline!src/!, \lstinline!svg/!, \lstinline!tex/!),
42 \item a \latex file containing the formulas,
43 \item \svg files for block-diagrams.
44 \end{itemize}
45
46 At this stage:
47 \begin{itemize}
48 \item \lstinline!cpp/! remains empty,
49 \item \lstinline!pdf/! remains empty,
50 \item \lstinline!src/! contains all \faust sources used (even libraries),
51 \item \lstinline!svg/! contains \svg block-diagram files,
52 \item \lstinline!tex/! contains the generated \latex file.
53 \end{itemize}
54
55 \subsection{Invoking faust2mathdoc}
56 \label{sec:invok-faust2m}
57
58 The \lstinline!faust2mathdoc! script calls \lstinline!faust --mathdoc! first, then it finishes the work:
59 \begin{itemize}
60 \item moving the output C++ file into \lstinline!cpp/!,
61 \item converting all \svg files into pdf files (you must have \lstinline!svg2pdf! installed, from the Cairo 2D graphics library),
62 \item launching \lstinline!pdflatex! on the \latex file (you must have both \lstinline!pdflatex! and the \lstinline!breqn! package installed),
63 \item moving the resulting pdf file into \lstinline!pdf/!.
64 \end{itemize}
65
66 \subsection{Online examples}
67 \label{sec:mdoc-examples}
68
69 To get an idea of the results of this mathematical documentation, which captures the mathematical semantic of \faust programs, you can look at two pdf files online:
70 \begin{itemize}
71 \item \myurl{http://faust.grame.fr/pdf/karplus.pdf} (automatic documentation),
72 \item \myurl{http://faust.grame.fr/pdf/noise.pdf} (manual documentation).
73 \end{itemize}
74
75 You can also generate all \emph{mdoc} pdfs at once, simply invoking the \lstinline!make mathdoc! command inside the \lstinline!examples/! directory:
76 \begin{itemize}
77 \item for each \lstinline!%.dsp! file, a complete \lstinline!%-mdoc! directory will be generated,
78 \item a single \lstinline!allmathpdfs/! directory will gather all the generated pdf files.
79 \end{itemize}
80
81
82 \section{Automatic documentation}
83 \label{sec:auto-docum}
84
85 By default, when no \lstinline!<mdoc>! tag can be found in the input \faust file, the \lstinline!-mdoc! option automatically generates a \latex file with four sections:
86 \begin{enumerate}
87 \item ''\textbf{Equations of process}'', gathering all formulas needed for \lstinline!process!,
88 \item ''\textbf{Block-diagram schema of process}'', showing the top-level block-diagram of \lstinline!process!,
89 \item ''\textbf{Notice of this documentation}'', summing up generation and conventions information,
90 \item ''\textbf{Complete listing of the input code}'', listing all needed input files (including libraries).
91 \end{enumerate}
92
93
94 \section{Manual documentation}
95 \label{sec:manual-mdoc}
96
97 You can specify yourself the documentation instead of using the automatic mode, with five xml-like tags. That permits you to modify the presentation and to add your own comments, not only on \lstinline!process!, but also about any expression you'd like to. Note that as soon as you declare an \lstinline!<mdoc>! tag inside your \faust file, the default structure of the automatic mode is ignored, and all the \latex stuff becomes up to you!
98
99 \subsection{Six tags}
100 \label{sec:doc-tags}
101
102 Here are the six specific tags:
103 \begin{itemize}
104 \item \lstinline!<mdoc></mdoc>!, to open a documentation field in the \faust code,
105 \begin{itemize}
106 \item \lstinline!<equation></equation>!, to get equations of a \faust expression,
107 \item \lstinline!<diagram></diagram>!, to get the top-level block-diagram of a \faust expression,
108 \item \lstinline!<metadata></metadata>!, to reference \faust metadatas (cf. declarations), calling the corresponding keyword,
109 \item \lstinline!<notice />!, to insert the "adaptive'' notice all formulas actually printed,
110 \item \lstinline!<listing [attributes] />!, to insert the listing of \faust files called.
111 \end{itemize}
112 \end{itemize}
113
114 The \lstinline!<listing />! tag can have up to three boolean attributes (set to \lstinline!"true"! by default):
115 \begin{itemize}
116 \item \lstinline'mdoctags' for \lstinline'<mdoc>' tags;
117 \item \lstinline'dependencies' for other files dependencies;
118 \item \lstinline'distributed' for the distribution of interleaved \faust code between \lstinline'<mdoc>' sections.
119 \end{itemize}
120
121
122 \subsection{The mdoc top-level tags}
123 \label{sec:mdoc-tag}
124
125 The \lstinline!<mdoc></mdoc>! tags are the top-level delimiters for \faust mathematical documentation sections. This means that the four other documentation tags can't be used outside these pairs (see section \ref{sec:documentation}).
126
127 In addition of the four inner tags, \lstinline!<mdoc></mdoc>! tags accept free \latex text, including its standard macros (like \lstinline!\section!, \lstinline!\emph!, etc.). This allows to manage the presentation of resulting tex file directly from within the input \faust file.
128
129 The complete list of the \latex packages included by \faust can be found in the file \lstinline!architecture/latexheader.tex!.
130
131 \subsection{An example of manual mathdoc}
132 \label{sec:ex-mathdoc}
133
134 \footnotesize
135 \begin{lstlisting}
136 <mdoc>
137 \title{<metadata>name</metadata>}
138 \author{<metadata>author</metadata>}
139 \date{\today}
140 \maketitle
141
142 \begin{tabular}{ll}
143 \hline
144 \textbf{name} & <metadata>name</metadata> \\
145 \textbf{version} & <metadata>version</metadata> \\
146 \textbf{author} & <metadata>author</metadata> \\
147 \textbf{license} & <metadata>license</metadata> \\
148 \textbf{copyright} & <metadata>copyright</metadata> \\
149 \hline
150 \end{tabular}
151 \bigskip
152 </mdoc>
153 //-----------------------------------------------------------------
154 // Noise generator and demo file for the Faust math documentation
155 //-----------------------------------------------------------------
156
157 declare name "Noise";
158 declare version "1.1";
159 declare author "Grame";
160 declare author "Yghe";
161 declare license "BSD";
162 declare copyright "(c)GRAME 2009";
163
164 <mdoc>
165 \section{Presentation of the "noise.dsp" Faust program}
166 This program describes a white noise generator with an interactive volume, using a random function.
167
168 \subsection{The random function}
169 </mdoc>
170
171 random = +(12345)~*(1103515245);
172
173 <mdoc>
174 The \texttt{random} function describes a generator of random numbers, which equation follows. You should notice hereby the use of an integer arithmetic on 32 bits, relying on integer wrapping for big numbers.
175 <equation>random</equation>
176
177 \subsection{The noise function}
178 </mdoc>
179
180 noise = random/2147483647.0;
181
182 <mdoc>
183 The white noise then corresponds to:
184 <equation>noise</equation>
185
186 \subsection{Just add a user interface element to play volume!}
187 </mdoc>
188
189 process = noise * vslider("Volume[style:knob]", 0, 0, 1, 0.1);
190
191 <mdoc>
192 Endly, the sound level of this program is controlled by a user slider, which gives the following equation:
193 <equation>process</equation>
194
195 \section{Block-diagram schema of process}
196 This process is illustrated on figure 1.
197 <diagram>process</diagram>
198
199 \section{Notice of this documentation}
200 You might be careful of certain information and naming conventions used in this documentation:
201 <notice />
202
203 \section{Listing of the input code}
204 The following listing shows the input Faust code, parsed to compile this mathematical documentation.
205 <listing mdoctags="false" dependencies="false" distributed="true" />
206 </mdoc>
207 \end{lstlisting}
208 \normalsize
209
210 The following page which gathers the four resulting pages of \lstinline!noise.pdf! in small size. might give you an idea of the produced documentation.
211
212
213 \subsection{The -stripmdoc option}
214 \label{sec:striping-option}
215
216 As you can see on the resulting file \lstinline!noisemetadata.pdf! on its pages 3 and 4, the listing of the input code (section\,4) contains all the mathdoc text (here colored in grey). As it may be useless in certain cases (see Goals, section \ref{sec:goals-of-mdoc}), we provide an option to strip mathdoc contents directly at compilation stage: \lstinline!-stripmdoc! (short) or \lstinline!--strip-mdoc-tags! (long).
217
218
219 \section{Localization of mathdoc files}
220 \label{sec:localization-mdoc}
221
222 By default, texts used by the documentator are in English, but you can specify another language (French, German and Italian for the moment), using the \lstinline!-mdlang! (or \lstinline!--mathdoc-lang!) option with a two-letters argument (\lstinline!en!, \lstinline!fr!, \lstinline!it!, etc.).
223
224 The \lstinline!faust2mathdoc! script also supports this option, plus a third short form with \lstinline!-l!:
225 \begin{lstlisting}
226 faust2mathdoc -l fr myfaustfile.dsp
227 \end{lstlisting}
228
229 If you would like to contribute to the localization effort, feel free to translate the mathdoc texts from any of the \lstinline!mathdoctexts-*.txt! files, that are in the \lstinline!architecture! directory (\lstinline!mathdoctexts-fr.txt!, \lstinline!mathdoctexts-it.txt!, etc.). As these files are dynamically loaded, just adding a new file with an appropriate name should work.
230
231 \includepdf[pages=-, frame=true, angle=-90, scale=0.75, nup=1x2]{images/noisemetadata}
232
233
234 \section{Summary of the mathdoc generation steps}
235 \label{sec:mdoc-summary}
236
237 \begin{enumerate}
238 \item First, to get the full mathematical documentation done on your faust file, call \lstinline!faust2mathdoc myfaustfile.dsp!.
239 \item Then, open the pdf file \lstinline!myfaustfile-mdoc/pdf/myfaustfile.pdf!.
240 \item That's all !
241 \end{enumerate}
242
243
244