

The makedoc tool



=======================================
============ Using makedoc ============
=======================================

Not only the library is built from source code but the actual documentation
too. Allegro is bundled with makedoc, a convulsed C program which started
small and has grown to support many different output formats. The
documentation source and documentation generator can be found both under the
`docs/src' directory. Running `make' in Allegro's top directory will generate
the documentation along with the library, but there are more specific make
targets which you can use to selectively build only the documentation or
specific versions of the documentation which by default won't be generated.
You can find more about these in the "Makefile targets" chapter.

Output formats
--------------

Makedoc output will be placed in the `docs/format' directory or directly in
the `docs' directory. Usually if an output format requires an external tool
which doesn't come bundled with Allegro you will have to generate it manually
with the correct makefile target.

   `.txt'
   Plain text version of the documentation. It is basically a dump of the
   `._tx' source file stripping the custom tags. This output is generated by
   default and available on all supported platforms.

   `.rtf'
   Rich text format version of the documentation. This is a slightly improved
   version of the text output. Makedoc will generate a few nice things like
   a table of contents and will use different fonts in the output, which
   are nicer to read or print than the text version. This output is generated
   by default and available on all supported platforms.

   `.html'
   Html version of the documentation. Depending on some tags in the `._tx'
   source file it can be built as multiple files or a single big page (see
   below). The documentation is generated in two steps: first the normal
   output is generated. This output doesn't contain hyperlinks between
   chapters since the makedoc tool doesn't know in advance in which file will
   be found a specific symbol. The second pass will go through all the links
   and make them point to the correct files. Thanks to cascade style sheets
   you can customize the outlook of the documentation without having to
   modify the makedoc tool. This output is generated by default and available
   on all supported platforms.

   `.3'
   Unix man pages for the section "Library calls (functions within program
   libraries)". As usual these man pages will contain a synopsis,
   description and see also sections. Certain parts of the documentation
   like chapter introductions won't have man pages. This output is generated
   by default on Unix platforms. Note that you have to install the man pages
   manually with a specific makefile target.

   `.texi'
   Intermediate format for GNU tools. This format is not readable alone and
   requires processing to be transformed into something else. This output can
   be generated on all platforms because it doesn't require external
   programs, but all by itself is not very useful.

   `.info'
   GNU online info format. Generated from the `.texi' output this format can
   be used with the GNU `info' tool. The produced output looks similar to the
   plain text version but features hyperlinked navigation. This output is
   generated by default on platforms supporting the GNU tools like Unix or
   DJGPP (DOS). You need the `makeinfo' tool to generate the output and the
   `info' tool to view it. You have to install this manually on your system
   with a specific makefile target.

   `.chm'
   Compiled HTML. Similar to the HTML output but instead of having lots of
   separate files you end up with a single file. You need Microsoft's HTML
   compiler to build this version of the documentation. Windows users can
   view `.chm' files by default. Non Windows users can go to
   http://freshmeat.net/ and search for "chm viewer". Read more in the
   "Makefile targets" chapter.

   `.dvi'
   Device independent documentation file. While this format is usable, it is
   also used as intermediate step to other formats. In fact, this one is
   build from the texi output. By default not build, as it relies on the
   external tool texi2dvi.

   `.ps'
   Postscript version of the documentation, ideal for printing. This is not
   generated by default because it needs to generate the DVI output and
   then use the external tool `dvips'.

   `.pdf'
   Portable document format. Similar in output quality to the postscript
   output, this has the advantage of having hyperlinks. Generated from the
   texi output with the external tool `texi2pdf'.

   `.devhelp'
   Devhelp HTML + XML index format. Similar to the HTML output, this also
   carries a separate index which can be used by external programs (usually
   programming editors) to look up context sensitive help. Basically it is
   like the info output but using the more flexible HTML format as base.
   This format doesn't require external tools to be built, but it is not
   built by default. You have to create and install it manually.

   `.api'
   SciTE api format. This is an index of all Allegro functions of the
   library for the SciTE editor (http://www.scintilla.org/SciTE.html).
   This output is generated by default and available on all supported
   platforms.

Customizing the output
----------------------

Some of the output formats can be customized even further by modifying some
of the generated files or directly the original source file. The
documentation source file format is described with more detail in
`docs/src/makedoc/format.txt'. Usually the interesting bits to users are:

   The HTML output generates by default individual HTML files for each
   chapter. By uncommenting the `multiplefiles' command you can create a
   single file with the whole manual. Note that external documentation files
   like the FAQ or hacking guide will still be linked, but not included.

   The HTML output also uses cascade style sheets to specify the outlook of
   the generated pages. You can disable CSS with the `ignore_css' command or
   specify a different CSS file with external-css=. The default CSS file
   generated by makedoc also has something to tweak.

   When using the multiple file output, makedoc places a "Back to contents"
   link at the bottom of each chapter. If you follow a hyperlink you can end
   up pointing at one of the last descriptions of the page but your browser
   might not scroll to the correct height because the page ends up before.
   To avoid this effect, you can uncomment one of the last lines in the CSS
   related to a bottom margin. Making the bottom margin higher puts more
   space between the "Back to contents" link and the physical end of the
   page.

Note that all the above which applies to HTML output also applies to
documentation formats which are HTML based, like Devhelp or CHM.

