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