1\section{Tricks used to produce the documentation}
2
3\subsection{autodoc - extraction of function documentation}
4
5
6\subsection{cexcerpt - extraction of verbatim code examples}
7
8This guide includes many examples of C code from Easel. These examples
9are extracted verbatim from C source files using SSDK's
10\prog{cexcerpt} program. The \prog{cexcerpt} program extracts tagged
11code chunks from a C source file for verbatim inclusion in LaTeX
12documentation.
13
14The \ccode{documentation/Makefile} runs \prog{cexcerpt} on every
15module .c and .h file. The cexcerpts are stored in the temporary
16\ccode{cexcerpts/} subdirectory.
17
18Usage: \ccode{cexcerpt <file.c> <dir>}. Processes C source file
19\ccode{file.c}; extracts all tagged excerpts, and puts them in a file
20in directory \ccode{<dir>}.
21
22An excerpt is marked with special comments in the C file:
23\begin{cchunk}
24/*::cexcerpt::my_example::begin::*/
25   while (esl_sq_Read(sqfp, sq) == eslOK)
26     { n++; }
27/*::cexcerpt::my_example::end::*/
28\end{cchunk}
29
30The cexcerpt marker's format is \ccode{::cexcerpt::<tag>::begin::} (or
31end). A comment containing a cexcerpt marker must be the first text on
32the source line. A cexcerpt comment may be followed on the line by
33whitespace or a second comment.
34
35The \ccode{<tag>} is used to construct the file name, as
36\ccode{<tag>.tex}.  In the example, the tag \ccode{my\_example} creates
37a file \ccode{my\_example.tex} in \ccode{<dir>}.
38
39All the text between the cexcerpt markers is put in the file.  In
40addition, this text is wrapped in a \ccode{cchunk} environment.  This
41file can then be included in a \LaTeX\ file.
42
43For best results, the C source should be free of TAB characters.
44"M-x untabify" on the region to clean them out.
45
46Cexcerpts can't overlap or nest in any way in the C file. Only one can
47be active at any given time.
48
49
50