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.
