makedoc - Generate documentation in various formats
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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'.
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 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.
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
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
Note that all the above which applies to HTML output also applies to
documentation formats which are HTML based, like Devhelp or CHM.