@section Build Documentation

This step in the build process introduces some significant requirements to the host system:

@itemize
@item GNU texinfo 4.8 or higher (lower versions should work)
@item Doxygen 1.5.7 or higher (lower versions should work)
@end itemize

Documentation that is shipped with @value{TERM.srcdist} is generated as part of the @ref{Build Process} step. This section documents builds all of the supported methods to build documentation. There are three kinds of documentation in this project; man-pages, articles and API. @b{Documentation must be build from the repository}.

Man-pages are automatically generated for command-line utilities by using @command{html2man} which invokes standard options @command{--help} and @command{--version} and gleans the information, generating a man-page in @b{nroff} script. Note that the utilities will first be built as they are depdendencies of man-page generation.

Artcles are usually hand-written and authored in Texinfo format which permits macro-expansions, simple formatting and conversion to several popular formats using the GNU @command{makeinfo}. A Texinfo @url{http://www.gnu.org/software/texinfo,manual} is available.

API is documented inline to C and C++ source files, usually headers using Doxygen comment-formatting. Doxygen is then used to post-process these files and generate documentation in various formats. A Doxygen manual is available at it's main @url{http://www.doxygen.org,site} .

The project's goal is to document as thoroughly as possible the public API in @value{PROJECT.name}. Since we never have enough time to document everything, we try to set some priorities in this regard. Generally the public API is the highest priority to document. Next most important is probably underlying utility code which is shared by many developers; for example @b{libplatform}.

If you need examples of how to document C-compatible source see @file{include/mp4v2/mp4v2.h} and for C++-only source
see @file{libplatform/io/File.h} .

The following table describes the various make targets available for building docs. Note you must first have completed the @ref{Configure} step.

@table @samp

@item make man
Generate man-pages for command-line utilities.

@item make html
Generate articles in HTML format from @file{texi} files.

@item make txt
Generate articles in plaintext format from @file{texi} files.

@item make wiki
Generate articles in Google Code Wiki format from @file{texi} files.

@item make xml
Generate articles in (Texinfo) XML format from @file{texi} files.

@item make api
Generate API in HTML format from header files.

@item make articles
Convenience; the equivalent of @command{make html txt wiki xml} .

@item make doc
Convenience; the equivalent of @command{make man articles api} .

@end table

And finally all of the document targets have a corresponding @b{clean} target which cleans up generated files. Simply prefix as follows:

@example
make manclean
make htmlclean
make txtclean
make wikiclean
make xmlclean
make apiclean
make articlesclean
make docclean
@end example