7.13 Automated Info Docs

AutoOpts provides two templates for producing ‘.texi’ documentation. ‘agtexi-cmd.tpl’ for the invoking section, and ‘aginfo3.tpl’ for describing exported library functions and macros.

For both types of documents, the documentation level is selected by passing a ‘-DLEVEL=<level-name>’ argument to AutoGen when you build the document. (See the example invocation below.)

Two files will be produced, a ‘.texi’ file and a ‘.menu’ file. You should include the text in the ‘.menu’ file in a ‘@menu’ list, either with ‘@include’-ing it or just copying text. The ‘.texi’ file should be ‘@include’-ed where the invoking section belongs in your document.

The ‘.texi’ file will contain an introductory paragraph, a menu and a subordinate section for the invocation usage and for each documented option. The introductory paragraph is normally the boiler plate text, along the lines of:

This chapter documents the @file{AutoOpts} generated usage text
and option meanings for the @file{your-program} program.

or:

These are the publicly exported procedures from the libname library.
Any other functions mentioned in the header file are for the private use
of the library.

7.13.1 invoking info docs

Using the option definitions for an AutoOpt client program, the ‘agtexi-cmd.tpl’ template will produce texinfo text that documents the invocation of your program. The text emitted is designed to be included in the full texinfo document for your product. It is not a stand-alone document. The usage text for the autogen help/usage (‘--help’), getdefs help/usage (‘help’) and columns help/usage (‘--help’) programs, are included in this document and are all generated using this template.

If your program’s option definitions include a ‘prog-info-descrip’ section, then that text will replace the boilerplate introductory paragraph.

These files are produced by invoking the following command:

autogen -L ${prefix}/share/autogen -Tagtexi-cmd.tpl \
        -DLEVEL=section your-opts.def

Where ‘${prefix}’ is the AutoGen installation prefix and ‘your-opts.def’ is the name of your product’s option definition file.

7.13.2 library info docs

The texinfo doc for libraries is derived from mostly the same information as is used for producing man pages See section library man pages. The main difference is that there is only one output file and the individual functions are referenced from a texi menu. There is also a small difference in the global attributes used:

These files are produced by invoking the following commands:

getdefs linenum srcfile template=aginfo3.tpl output=libexport.def \
       <source-file-list>

autogen -L ${prefix}/share/autogen -DLEVEL=section libexport.def

Where ‘${prefix}’ is the AutoGen installation prefix and ‘libexport.def’ is some name that suits you.

An example of this can be seen in this document, See section libopts External Procedures.

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.