Build Documentation
===================

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

  * GNU texinfo 4.8 or higher (lower versions should work)

  * Doxygen 1.5.7 or higher (lower versions should work)

Documentation that is shipped with is generated as part of the 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. Documentation must be build from the repository.

Man-pages are automatically generated for command-line utilities by using html2man which invokes standard options --help and --version and gleans the information, generating a man-page in 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 makeinfo. A Texinfo manual (http://www.gnu.org/software/texinfo) 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 site (http://www.doxygen.org) .

The project's goal is to document as thoroughly as possible the public API in. 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 libplatform.

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

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

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

make html
     Generate articles in HTML format from texi files.

make txt
     Generate articles in plaintext format from texi files.

make wiki
     Generate articles in Google Code Wiki format from texi files.

make xml
     Generate articles in (Texinfo) XML format from texi files.

make api
     Generate API in HTML format from header files.

make articles
     Convenience; the equivalent of make html txt wiki xml .

make doc
     Convenience; the equivalent of make man articles api .

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

     make manclean
     make htmlclean
     make txtclean
     make wikiclean
     make xmlclean
     make apiclean
     make articlesclean
     make docclean