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)
• Version/Change Log (autodocformats)

Usage and interface (autodocformats)

Documentation on exports (autodocformats)

REGTYPE: supported_format/1:

Usage: supported_format(Format)

• Description: Format is a supported typesetting format.

PREDICATE: supported_format_suffix/2:

Usage: supported_format_suffix(Format,Suffix)

• Description: Format is a format for which formatting code is available. Suffix is the suffix that should be used for the generated files.
• The following properties should hold upon exit: Format is a supported typesetting format. (supported_format/1) Suffix is currently instantiated to an atom. (atom/1)

PREDICATE: index_comment/2:

Usage: index_comment(Index,Text)

• Description: Type is a type of index which is supported. Text describes the index contents.
• The following properties should hold upon exit: Index is currently instantiated to an atom. (atom/1) Text is a string (a list of character codes). (string/1)

PREDICATE: option_comment/2:

Usage: option_comment(Option,Text)

• Description: Option is a documentation option which is supported. Text describes the effect of selecting that option. Currently supported options are:

  
  
  option_comment('-v',"Verbose output (good for debugging).        ").
  option_comment('-nobugs',"Do not include information on bugs.         ").
  option_comment('-noauthors',"Do not include author names.                ").
  option_comment('-noversion',"Do not include version information.         ").
  option_comment('-nochangelog',"Do not include change log.                  ").
  option_comment('-nopatches',"Do not include comments for patches.        ").
  option_comment('-modes',"Do not translate modes and their arguments
                                  (except for properties)                     ").
  option_comment('-headprops',"Do not move head properties to body.        ").
  option_comment('-literalprops',"Do not use text to document properties.     ").
  option_comment('-nopropnames',"Do not include property names in prop text. ").
  option_comment('-noundefined',"Do not signal undefined properties in text. ").
  option_comment('-nopropsepln',"Do not put each property in a separate line.").
  option_comment('-norefs',"Do not include a 'References' appendix.     ").
  option_comment('-nobullet',"Do not generate initial bullet index        
                                  (.htmlbullet) with .htmlindex file. Select if
                                  only one manual will be installed in DOCDIR.").
  option_comment('-nosysmods',"Do not include system modules in list of 
                                  libraries used.").
  option_comment('-noengmods',"Do not include system engine modules in list 
                                  of libraries used.").
  option_comment('-noisoline',"Do not include *textual* description that a 
                                  given usage conforms to the ISO standard.").
  option_comment('-propmods',"Include module name to which props belong.").
  option_comment('-shorttoc',"Produce shorter table of contents (no entries
                                  for individual defs of preds, props, etc.).").
  option_comment('-regtypeprops',"Include in the doc for regtypes the global
                                  prop stating that they are indeed regtypes.").
  option_comment('-onesided',"For printing on one side (default is two).").
  
  
           
  

• The following properties should hold upon exit: Option is a supported documentation option. (supported_option/1) Text is a string (a list of character codes). (string/1)

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)

• Description: A texinfo main file is generated. Name is used as the name of the file. Title is used as the title of the document. The Version, Authors, and the Subtitle will go in the title page. Copyright goes in the back of the title page.
• The following properties should hold at call time: Format and texinfo unify. (= /2) Name is currently instantiated to an atom. (atom/1) NDName is currently instantiated to an atom. (atom/1) Version is a complete version descriptor. (version_descriptor/1) Title is a string (a list of character codes). (string/1) Authors is a list of strings. (list/2) Subtitle is a list of strings. (list/2) Copyright is a string (a list of character codes). (string/1) Summary is a string (a list of character codes). (string/1) Indices is a list of atoms. (list/2) StartPage is an integer. (int/1) PaperType is an atom. (atm/1) Opts is a list of supported_options. (list/2) I is the name of a file. (filename/1) O is the name of a file. (filename/1) OS is an open stream. (stream/1)

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)

• Description: Formats intro stuff: summary, intro, etc.
• The following properties should hold at call time: Format and texinfo unify. (= /2) FileType is any term. (term/1) ModuleType is currently instantiated to an atom. (atom/1) Name is a string (a list of character codes). (string/1) NDName is a string (a list of character codes). (string/1) Summary is a string (a list of character codes). (string/1) Version is a complete version descriptor. (version_descriptor/1) Comment is a string (a list of character codes). (string/1) OS is an open stream. (stream/1) IntroOS is an open stream. (stream/1)

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)

• Description: Predicates will formatted as an itemized list. Corresponds to a begin itemize.
• The following properties should hold at call time: Format and texinfo unify. (= /2) Name is currently instantiated to an atom. (atom/1) Text is a string (a list of character codes). (string/1) OS is an open stream. (stream/1)

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)

• Description: Each predicate is an item in an itemized list.
• The following properties should hold at call time: Format and texinfo unify. (= /2) Type is currently instantiated to an atom. (atom/1) Pred is a Name/Arity structure denoting a predicate name:

  predname(P/A) :-
          atm(P),
          nnegint(A).
  

  (predname/1) Indices is a list of atoms. (list/2) Opts is a list of supported_options. (list/2) OS is an open stream. (stream/1)

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)

• Description: Predicate comments are output as is (in a separate paragraph).
• The following properties should hold at call time: Format and texinfo unify. (= /2) Comment is a string (a list of character codes). (string/1) OS is an open stream. (stream/1)

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)

• Description: Noop (each predicate is an item in an itemized list).
• The following properties should hold at call time: Format and texinfo unify. (= /2) OS is an open stream. (stream/1)

PREDICATE: format_native_declaration/3:

Usage: format_native_declaration(Format,Decl,OS)

• Description: This predicate defines the format for documenting miscellaneous declarations such as meta_predicate/1, multifile/1, dynamic/1, data/1, etc. Format is the type of output (e.g., texinfo, latex, etc.). Decl contains the declaration info. OS is the output stream to which writes should be made (normally points to the output file). No special comment is generated for the default value (static).
• The following properties should hold at call time: Format and texinfo unify. (= /2) Decl is any term. (term/1) OS is an open stream. (stream/1)

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)

• Description: Predicates will formatted as an itemized list. Corresponds to an end itemize.
• The following properties should hold at call time: Format and texinfo unify. (= /2) OS is an open stream. (stream/1)

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)

• Description: Usage header in bold in separate paragraph.
• The following properties should hold at call time: Format and texinfo unify. (= /2) N is currently instantiated to an integer. (integer/1) OS is an open stream. (stream/1)

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)

• Description: Usage header in bold in separate paragraph.
• The following properties should hold at call time: Format and texinfo unify. (= /2) OS is an open stream. (stream/1)

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)

• Description: Head descriptors are formatted literally, in @code format. ISO compliance is formatted using the @key command.
• The following properties should hold at call time: Format is currently instantiated to an atom. (atom/1) HD is any term. (term/1) Type is currently instantiated to an atom. (atom/1) Standard is currently instantiated to an atom. (atom/1) OS is an open stream. (stream/1)

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)

• Description: Header in bold in separate paragraph.
• The following properties should hold at call time: Format and texinfo unify. (= /2) OS is an open stream. (stream/1)

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)

• Description: Each site is an item in an itemized list.
• The following properties should hold at call time: Format and texinfo unify. (= /2) Text is a string (a list of character codes). (string/1) Bullet is an atom. (atm/1) OS is an open stream. (stream/1)

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)

• Description: Simply end of item (a newline).
• The following properties should hold at call time: Format and texinfo unify. (= /2) OS is an open stream. (stream/1)

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)

• Description: Properties are formatted as a (second level) itemized list.
• The following properties should hold at call time: Format and texinfo unify. (= /2) OS is an open stream. (stream/1)

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)

• Description: Properties are formatted as running text.
• The following properties should hold at call time: Format is an atom. (atm/1) Prop is any term. (term/1) PM is an atom. (atm/1) DocString is a string (a list of character codes). (string/1) VarNames is a list of strings. (list/2) Opts is a list of supported_options. (list/2) OS is an open stream. (stream/1)

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)

• Description: End of the (second level) itemized list.
• The following properties should hold at call time: Format and texinfo unify. (= /2) OS is an open stream. (stream/1)

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)

• Description: The description of the usage is a separate item in the site item list.
• The following properties should hold at call time: Format is currently instantiated to an atom. (atom/1) Desc is a string (a list of character codes). (string/1) OS is an open stream. (stream/1)

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)

• Description: The components in Components, if any, are included as chapters. Name is used as the basename of the index component files. If no components, then everything should go in-line (including indices).
• The following properties should hold at call time: Format and texinfo unify. (= /2) Name is the name of a file. (filename/1) Components is a list of filenames. (list/2) Indices is a list of atoms. (list/2) Opts is a list of atoms. (list/2) OS is an open stream. (stream/1)

PREDICATE: verbatimize_string/3:

Usage:

• Description: Escapes needed characters in string as needed for the verbatim command supported natively by the format.
• The following properties should hold at call time: Format is a supported typesetting format. (supported_format/1) Arg2 is a string (a list of character codes). (string/1) Arg3 is any term. (term/1)
• The following properties should hold upon exit: Format is a supported typesetting format. (supported_format/1) Arg2 is a string (a list of character codes). (string/1) Arg3 is a string (a list of character codes). (string/1)

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)

• Description: Defines the translation between the special commands which can appear in strings inside assertions and texinfo.
• The following properties should hold at call time: Format and texinfo unify. (= /2) Command is a structure denoting a command that is admissible in strings inside assertions. (stringcommand/1) Indices is a list of atoms. (list/2)
• The following properties should hold upon exit: NewCommand is a string (a list of character codes). (string/1)

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

• Description: Defines the translation between the special commands which can appear in strings inside assertions and html. This is still somewhat incomplete.
• The following properties should hold at call time: Format and html unify. (= /2) Command is a structure denoting a command that is admissible in strings inside assertions. (stringcommand/1) Indices is a list of atoms. (list/2)
• The following properties should hold upon exit: NewCommand is a string (a list of character codes). (string/1)

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

• Description: Defines the translation between the special commands which can appear in strings inside assertions and man.
• The following properties should hold at call time: Format and man unify. (= /2) Command is a structure denoting a command that is admissible in strings inside assertions. (stringcommand/1) Indices is a list of atoms. (list/2)
• The following properties should hold upon exit: NewCommand is a string (a list of character codes). (string/1)

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

• Description: Defines the translation between the special commands which can appear in strings inside assertions and ascii.
• The following properties should hold at call time: Format and ascii unify. (= /2) Command is a structure denoting a command that is admissible in strings inside assertions. (stringcommand/1) Indices is a list of atoms. (list/2)
• The following properties should hold upon exit: NewCommand is a string (a list of character codes). (string/1)

Version/Change Log (autodocformats)

Version 0.0 (1996/10/10)

First prototype.

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