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).
autodocformats
):- use_module(library(autodocformats)).
supported_format_suffix/2
,
index_comment/2
,
option_comment/2
,
format_front_matter/19
,
format_intro/10
,
format_module_usage/14
,
format_predicates_begin/4
,
format_predicate_begin/6
,
format_predicate_comment/3
,
format_predicate_end/2
,
format_native_declaration/3
,
format_predicates_end/2
,
format_multiple_usage_header/3
,
format_usage_header/2
,
format_head_descriptor/5
,
format_other_assrt_header/2
,
format_site_begin/4
,
format_site_end/2
,
format_properties_begin/2
,
format_property/7
,
format_properties_end/2
,
format_description/3
,
format_other_info/10
,
format_includes_and_end_matter/6
,
verbatimize_string/3
,
rewrite_command/4
.
supported_format/1
.
lpdoclib(autodoc)
,
lpdoclib(comments)
.
aggregates
,
format
,
write
,
streams
,
errhandle
,
operators
,
messages
,
lists
,
terms
,
assertions/assertions_props
.
arithmetic
,
atomic_basic
,
attributes
,
basic_props
,
basiccontrol
,
data_facts
,
exceptions
,
io_aux
,
io_basic
,
prolog_flags
,
streams_basic
,
system_info
,
term_basic
,
term_compare
,
term_typing
.
autodocformats
)
Usage: supported_format(Format)
Format
is a supported typesetting format.
Usage: supported_format_suffix(Format,Suffix)
Format
is a format for which formatting code is available. Suffix
is the suffix that should be used for the generated files.
Format
is a supported typesetting format.
(supported_format/1
)
Suffix
is currently instantiated to an atom.
(atom/1
)
Usage: index_comment(Index,Text)
Type
is a type of index which is supported. Text
describes the index contents.
Index
is currently instantiated to an atom.
(atom/1
)
Text
is a string (a list of character codes).
(string/1
)
Usage: option_comment(Option,Text)
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).").
Option
is a supported documentation option.
(supported_option/1
)
Text
is a string (a list of character codes).
(string/1
)
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)
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.
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 string
s.
(list/2
)
Subtitle
is a list of string
s.
(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 atom
s.
(list/2
)
StartPage
is an integer.
(int/1
)
PaperType
is an atom.
(atm/1
)
Opts
is a list of supported_option
s.
(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
)
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)
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
)
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).
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)
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
)
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)
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 atom
s.
(list/2
)
Opts
is a list of supported_option
s.
(list/2
)
OS
is an open stream.
(stream/1
)
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)
Format
and texinfo
unify.
(= /2
)
Comment
is a string (a list of character codes).
(string/1
)
OS
is an open stream.
(stream/1
)
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)
Format
and texinfo
unify.
(= /2
)
OS
is an open stream.
(stream/1
)
Usage: format_native_declaration(Format,Decl,OS)
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
).
Format
and texinfo
unify.
(= /2
)
Decl
is any term.
(term/1
)
OS
is an open stream.
(stream/1
)
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)
Format
and texinfo
unify.
(= /2
)
OS
is an open stream.
(stream/1
)
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)
Format
and texinfo
unify.
(= /2
)
N
is currently instantiated to an integer.
(integer/1
)
OS
is an open stream.
(stream/1
)
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)
Format
and texinfo
unify.
(= /2
)
OS
is an open stream.
(stream/1
)
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)
@code
format. ISO compliance is formatted using the @key
command.
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
)
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)
Format
and texinfo
unify.
(= /2
)
OS
is an open stream.
(stream/1
)
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)
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
)
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)
Format
and texinfo
unify.
(= /2
)
OS
is an open stream.
(stream/1
)
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)
Format
and texinfo
unify.
(= /2
)
OS
is an open stream.
(stream/1
)
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)
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 string
s.
(list/2
)
Opts
is a list of supported_option
s.
(list/2
)
OS
is an open stream.
(stream/1
)
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)
Format
and texinfo
unify.
(= /2
)
OS
is an open stream.
(stream/1
)
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)
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
)
No further documentation available for this predicate.
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)
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).
Format
and texinfo
unify.
(= /2
)
Name
is the name of a file.
(filename/1
)
Components
is a list of filename
s.
(list/2
)
Indices
is a list of atom
s.
(list/2
)
Opts
is a list of atom
s.
(list/2
)
OS
is an open stream.
(stream/1
)
Usage:
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
)
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
)
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)
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 atom
s.
(list/2
)
NewCommand
is a string (a list of character codes).
(string/1
)
Usage 2: rewrite_command(Format,Command,Indices,NewCommand)
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 atom
s.
(list/2
)
NewCommand
is a string (a list of character codes).
(string/1
)
Usage 3: rewrite_command(Format,Command,Indices,NewCommand)
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 atom
s.
(list/2
)
NewCommand
is a string (a list of character codes).
(string/1
)
Usage 4: rewrite_command(Format,Command,Indices,NewCommand)
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 atom
s.
(list/2
)
NewCommand
is a string (a list of character codes).
(string/1
)
autodocformats
)Go to the first, previous, next, last section, table of contents.