Go to the first, previous, next, last section, table of contents.


Low level documentation format definitions

Author(s): Manuel Hermenegildo.

Version: 1.9#58 (2002/4/19, 20:59:33 CEST)

Version of last change: 1.9#50 (2000/4/18, 3:22:13 CEST)

This module defines the interface for the auxiliary predicates needed by the automatic documentation generation library: these predicates determine the precise format in which the output is written.

Also, this module includes definitions of these predicates for a few formats. The main output format supported is texinfo (see The GNU Texinfo Documentation System manual for more info), from which printed manuals and several other printing and on-line formats can be easily generated automatically (including info, html, etc.). There is also some limited support for direct output in unix man format and direct html (but note that html can also be generated in a better way by first generating texinfo and then using one of the available converters). For texinfo, the documentation for a module is a texinfo chapter, suitable for inclusion in a wrapper "main" document file. A simple example of the use of this library for generating a texinfo reference manual (including a driver script, useful Makefiles, etc.) is included with the library source code. Other examples can be found in the Ciao documentation directory (i.e., the Ciao manuals themselves).

Usage and interface (autodocformats)

Documentation on exports (autodocformats)

REGTYPE: supported_format/1:

Usage: supported_format(Format)

PREDICATE: supported_format_suffix/2:

Usage: supported_format_suffix(Format,Suffix)

PREDICATE: index_comment/2:

Usage: index_comment(Index,Text)

PREDICATE: option_comment/2:

Usage: option_comment(Option,Text)

PREDICATE: format_front_matter/19:

format_front_matter(Format,ModuleType,MainOrComp,Name,NDName,Version,GVers,Title,Authors,Subtitle,Copyright,Summary,Indices,StartPage,PaperType,Opts,I,O,OS)

This predicate defines the first part of the format of the main file of a manual. Format is the type of output (e.g., texinfo, latex, etc.) -- different clauses of the predicate can be defined for different formats. Name is the name of the application (taken from the name of the input file). NDName is the same, but without _doc, if applicable. Version is the version of the first comment/2 entry which specifies a version number (which should be the current version). This is the version of the last local change. GVers is the global version. Title is the intended title of the application (taken from the approriate comment/2 declaration). Authors is a (possibly empty) list of author names. Subtitle is a (possibly empty) list of subtitle (e.g., address, explanation) lines. Copyright is the copyright text (taken from the appropriate comment/2 declaration). Summary is a brief summary of the contents of the manual (taken from the appropriate comment/2 declaration). Indices is a list of index names (the indices to be generated). StartPage is the page number of the first page of the manual. I and O are the names of the input and output files being processed (which can be used for example to put a comment in the generated file saying that the file has been generated automatically from these files and therefore should probably not be edited by hand). OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_front_matter(Format,ModuleType,MainOrComp,Name,NDName,Version,GVers,Title,Authors,Subtitle,Copyright,Summary,Indices,StartPage,PaperType,Opts,I,O,OS)

PREDICATE: format_intro/10:

format_intro(Format,FileType,ModuleType,Name,NDName,Summary,Version,Comment,OS,IntroOS)

This predicate defines the format of the introduction and some auxiliary information. Format is the type of output (e.g., texinfo, latex, etc.). FileType is the type of file (main, component, etc.). ModuleType is how the module is used (use_module, etc.). Name is the module/application name. NDName is the same, but without _doc, if applicable. Summary is a brief summary of the contents of the manual (taken from the appropriate comment/2 declaration, if available). Version is the version of the first comment/2 entry which specifies a version number (which should be the current version). Comment is the introductory text for the module (taken from the comment/2 declaration, if available). OS is the output stream to which writes should be made (normally points to the output file). IntroOS is the output stream for the introduction.

Usage: format_intro(Format,FileType,ModuleType,Name,NDName,Summary,Version,Comment,OS,IntroOS)

PREDICATE: format_module_usage/14:

format_module_usage(Format,Name,Type,Exports,Mults,UMods,IUMods,SMods,EMOds,Ops,NDecls,NModes,Indices,OS)

This predicate defines the format of the usage info for the module. Format is the type of output (e.g., texinfo, latex, etc.). Name is the name of the module (taken from the module/2 declaration). Exports contains the predicates exported by the module (taken from the module/2 declaration). UMods contains the user modules imported by the module. SMods contains the system modules imported by the module. EMods contains the internal (engine) modules imported by the module. Ops contains any exported operator definitions. NDecls contains any exported new declarations. NModes contains any new mode definitions. Indices is a list of index names (the indices to be generated). OS is the output stream to which writes should be made (normally points to the output file).

PREDICATE: format_predicates_begin/4:

format_predicates_begin(Format,Name,Text,OS)

This predicate defines the format of the first part of the documentation for a set of predicates. Format is the type of output (e.g., texinfo, latex, etc.). Name is the module name. Text describes which set of predicates is being documented (e.g., exported predicates, imported predicates, etc.). OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_predicates_begin(Format,Name,Text,OS)

PREDICATE: format_predicate_begin/6:

format_predicate_begin(Format,Type,Pred,Indices,Opts,OS)

This predicate defines the format of the first part of the documentation for a predicate (the header). Format is the type of output (e.g., texinfo, latex, etc.). Type is the type of predicate being documented (predicate, property, type, etc.). Pred is the name of the predicate. Indices is a list of index names (the indices to be generated). Opts are the formatting options. OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_predicate_begin(Format,Type,Pred,Indices,Opts,OS)

PREDICATE: format_predicate_comment/3:

format_predicate_comment(Format,Comment,OS)

This predicate defines the format of Comment, an introductory text for the predicate (taken from the comment/2 declaration, if available). Format is the type of output (e.g., texinfo, latex, etc.). OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_predicate_comment(Format,Comment,OS)

PREDICATE: format_predicate_end/2:

format_predicate_end(Format,OS)

This predicate defines the format of the last part of the documentation for a predicate. Format is the type of output (e.g., texinfo, latex, etc.). OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_predicate_end(Format,OS)

PREDICATE: format_native_declaration/3:

Usage: format_native_declaration(Format,Decl,OS)

PREDICATE: format_predicates_end/2:

format_predicates_end(Format,OS)

This predicate defines the format of the last part of the documentation for a set of predicates. Format is the type of output (e.g., texinfo, latex, etc.). OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_predicates_end(Format,OS)

PREDICATE: format_multiple_usage_header/3:

format_multiple_usage_header(Format,N,OS)

This predicate defines the format of the header describing each usage for a predicate with multiple declarations. Format is the type of output (e.g., texinfo, latex, etc.). N is the usage number. OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_multiple_usage_header(Format,N,OS)

PREDICATE: format_usage_header/2:

format_usage_header(Format,OS)

This predicate defines the format of the header describing a single usage for a predicate. Format is the type of output (e.g., texinfo, latex, etc.). OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_usage_header(Format,OS)

PREDICATE: format_head_descriptor/5:

format_head_descriptor(Format,HD,Type,Standard,OS)

This predicate defines the format of a predicate descriptor. Format is the type of output (e.g., texinfo, latex, etc.). HD describes the head of the predicate (as a structure whose argunents are the variable names). Type is the type of predicate (predicate, function, declaration, ...). Standard contains the atom iso is the predicate is iso-compliant. OS is the output stream to which writes should be made (normally points to the output file.

Usage: format_head_descriptor(Format,HD,Type,Standard,OS)

PREDICATE: format_other_assrt_header/2:

format_other_assrt_header(Format,OS)

This predicate defines the format of the header general properties of a predicate. Format is the type of output (e.g., texinfo, latex, etc.). OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_other_assrt_header(Format,OS)

PREDICATE: format_site_begin/4:

format_site_begin(Format,Text,Bullet,OS)

This predicate defines the format of the header of the description of a set of properties for a given site (at calls, on success, global properties, etc.). Format is the type of output (e.g., texinfo, latex, etc.). Text describes the site. Bullet says if a bullet should precede the text. OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_site_begin(Format,Text,Bullet,OS)

PREDICATE: format_site_end/2:

format_site_end(Format,OS)

This predicate defines the format of the end of the description of a set of properties for a given site. Format is the type of output (e.g., texinfo, latex, etc.). OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_site_end(Format,OS)

PREDICATE: format_properties_begin/2:

format_properties_begin(Format,OS)

This predicate defines the beginning of the description of the properties for a given predicate. Format is the type of output (e.g., texinfo, latex, etc.). N is the usage number. OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_properties_begin(Format,OS)

PREDICATE: format_property/7:

format_property(Format,Prop,PM,DocString,VarNames,Opts,OS)

This predicate defines the formatting for a property. Format is the type of output (e.g., texinfo, latex, etc.). Prop is the actual property (a term). PM is the module in which the property is defined. VarNames is a list of (possibly repeated) variable names, corresponding to the names in the head pattern. DocString contains ~s in the places where the variables names should appear. Note that this is suitable for use as arguments for a call to format/2. OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_property(Format,Prop,PM,DocString,VarNames,Opts,OS)

PREDICATE: format_properties_end/2:

format_properties_end(Format,OS)

This predicate defines the end of the description of the properties for a given predicate. Format is the type of output (e.g., texinfo, latex, etc.). N is the usage number. OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_properties_end(Format,OS)

PREDICATE: format_description/3:

format_description(Format,Desc,OS)

This predicate defines the format of Desc, an introductory text for the predicate (taken from the comment part of a pred/1 declaration, if available). These coments are generally used to describe a particular usage of the predicate. Format is the type of output (e.g., texinfo, latex, etc.). OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_description(Format,Desc,OS)

PREDICATE: format_other_info/10:

No further documentation available for this predicate.

PREDICATE: format_includes_and_end_matter/6:

format_includes_and_end_matter(Format,Name,Components,Indices,Opts,OS)

This predicate generates code for including the components of a complex document if needed, and produces the final matter of the main file. Format is the type of output (e.g., texinfo, latex, etc.) -- different clauses of the predicate can be defined for different formats. Name is the name of the application (taken from the name of the input file). If the manual should include other files (e.g., as chapters) Components is nonempty and contains the complete names of the component files. These files will appear in the manual in the order in which they appear in Components. These files can be written manually or generated automatically by document_module/2 or any other means, but must be in a format compatible with Format. Indices contains the index names (the indices to be generated). OS is the output stream to which writes should be made (normally points to the output file).

Usage: format_includes_and_end_matter(Format,Name,Components,Indices,Opts,OS)

PREDICATE: verbatimize_string/3:

Usage:

PREDICATE: rewrite_command/4:

rewrite_command(Format,Command,Indices,NewCommand)

Defines the translation between the special commands which can appear in strings inside assertions and the formatting target. Indices is a list of index names (the indices to be generated).

Usage 1: rewrite_command(Format,Command,Indices,NewCommand)

Usage 2: rewrite_command(Format,Command,Indices,NewCommand)

Usage 3: rewrite_command(Format,Command,Indices,NewCommand)

Usage 4: rewrite_command(Format,Command,Indices,NewCommand)

Version/Change Log (autodocformats)

Version 0.0 (1996/10/10)
First prototype.


Go to the first, previous, next, last section, table of contents.