Documentation configuration options

These are the predicates that define the options that can be used in documentation configuration files. Their admissible values are given in their corresponding types in Admissible values for the documentation configuration options. See Writing documentation for an introduction.

Usage and interface

Documentation on exports

Usage:doc_structure(Term)

It defines the document structure as a tree.

The tree is defined as a root node with optional children. Nodes can be atoms or pairs (N-Cs), where Cs is a list of nodes. The root of the tree is the main file of the manual, i.e., the file which determines the manual's cover page, and first chapter. The children files are used as components, i.e., they will constitute the subsequent chapters of the manual.

If the main or any component file name ends with _doc, then it is treated as documenting the same file name without the _doc suffix. This is useful for separating the documentation from the source file (see Separating the documentation from the source file).

    PREDICATEfilepath/1

    Usage:filepath(Path)

    It defines the directories where the .pl files to be documented can be found.

    You also need to specify all the paths containing files which are used by the files being documented. For example, the paths to files included by an @include command or to figures.

    • The following properties should hold upon exit:
      (dirpath/1)Path is a full path to a directory.

    PREDICATEoutput_name/1

    Usage:output_name(Base)

    It determines the base file name of the main documents generated by lpdoc.

    By default it is equal to the main file name (root) specified in doc_structure/1.

    If the main file name ends with _doc, then it is equal to the name without the _doc suffix (see doc_structure/1).

    If the versioned_output option is specified in doc_mainopts/1, the bundle version number is appended to the output name.

    • The following properties should hold upon exit:
      (sourcename/1)Base is a source name.

    PREDICATEoutput_dir/1

    Usage:output_dir(Base)

    Output directory. If undefined, uses directory of input

    • The following properties should hold upon exit:
      (sourcename/1)Base is a source name.

    Usage:doc_mainopts(Option)

    Option is a processing option which should be activated when processing the main file.

    It can be set to a series of options which allow more detailed control of what is included in the documentation for the main file and how (i.e., including bug information , versions and patches or only patches , authors , changelog , explanation of modes, one-sided printing (two-sided is the default), etc.).

    See option_comment/2 for a description of these options.

    The default values are: no_bugs, no_patches.

    • Call and exit should be compatible with:
      (supported_option/1)Documentation generation options.

    Usage:doc_compopts(Option)

    Option is a processing option which should be activated when processing the secondary files (all except the main file).

    Currently these options are common to all component files but they can be different from doc_mainopts/1.

    See option_comment/2 for a description of these options.

    The default values are: no_bugs, no_patches.

    • Call and exit should be compatible with:
      (supported_option/1)Documentation generation options.

    PREDICATEdocformat/1

    Usage:docformat(Format)

    Defines the documentation formats to be generated by default.

    If the main file is an application, and the manl option is selected, then lpdoc looks for a usage_message/1 fact, which should contain a string as argument, and will use that string to document the usage of the application (i.e., it will be used to fill in the synopsis section of the man page).

    See supported_format/1 for the available formats.

    The default values are: pdf, manl, info, html.

    PREDICATEindex/1

    Usage:index(Idx)

    Defines the index sections to be generated by default.

    Selecting all generates all the supported indices. However, note that this (as well as selecting many indices explicitely) exceeds the capacity of most texinfo installations.

    See index_comment/1 for a description of the indices.

    The default values are: concept, lib, pred, prop, regtype, decl, author, global.

    • The following properties should hold upon exit:
      (supported_index/1)Supported indexes

    PREDICATEbibfile/1

    Usage:bibfile(F)

    It determines a list of .bib files (one file per path), i.e., files containing bibliographic entries in bibtex format.

    This is only relevant if you are using citations in the text (using the @cite command). In that case those will be the files in which the citations will be searched for. All the references will appear together in a References appendix at the end of the manual.

    If you are not using citations, then select the no_biblio option on the main file, which will prevent an empty 'References' appendix from appearing in the manual.

    • The following properties should hold upon exit:
      (filename/1)F is a full path to a file.

    PREDICATEstartpage/1

    Usage:startpage(PageNumber)

    Page number of the first page of the manual.

    Setting this to a different value allows changing the page number of the first page of the manual. This can be useful if the manual is to be included in a larger document or set of manuals. Typically, this should be an odd number.

    The default value is 1.

    • The following properties should hold upon exit:
      (int/1)PageNumber is an integer.

    PREDICATEpapertype/1

    Usage:papertype(PageNumber)

    Type of paper/format for printable outputs (e.g., pdf).

    The currently supported outputs (most of them inherited from texinfo) are:

    afourpaper

    The default, usable for printing on A4 paper. Rather busy, but saves trees.

    afourwide

    This one crams even more stuff than afourpaper on an A4 page. Useful for generating manuals in the least amount of space. It saves more trees.

    afourlatex

    This one is a little less compressed than afourpaper.

    smallbook

    Small pages, like in a handbook.

    letterpaper

    For printing on American letter size paper.

    afourthesis

    A thesis-like style (i.e., double spaced, wide margins etc.). Useful -- for inserting lpdoc output as appendices of a thesis or similar document. It does not save trees.

    See also the onesided option for the main file.

    The default value is: afourpaper.

    PREDICATElibtexinfo/1

    Usage:

    If set to yes the texinfo.tex file that comes with the lpdoc distribution will be used when generating manuals in formats such as dvi and ps. Otherwise, the texinfo file that comes with your tex installation will be used. It is recommended that you leave this set to 'yes'.

    • The following properties should hold upon exit:
      (yesno/1)Enumerated type for yes/no

    Usage:

    The source files contain version information. If not specified lpdoc will assume the opposite

    • The following properties should hold upon exit:
      (yesno/1)Enumerated type for yes/no

    Usage:

    Allow LPdoc-flavored markdown in docstrings

    • The following properties should hold upon exit:
      (yesno/1)Enumerated type for yes/no

    Usage:

    Syntax highlight code blocks (only for HTML backend)

    • The following properties should hold upon exit:
      (yesno/1)Enumerated type for yes/no

    PREDICATEverbosity/1

    Usage:

    Level of verbosity of (normally progress) messages. quiet means no messages printed, normal means standard messages, and all means more detailed messages. See autodoc_message_t/1.

    • The following properties should hold upon exit:
      (verbosity_t/1)Arg1 is a verbosity level.

    Usage:

    Warning reporting level. none means only error messages are printed, normal means errors and warnings, all means also notes. See autodoc_message_t/1.

    • The following properties should hold upon exit:
      (warning_level_t/1)Arg1 is a warning level.

    Usage:

    Include an automatically generated notice inside the output text.

    • The following properties should hold upon exit:
      (yesno/1)Enumerated type for yes/no

    PREDICATEhtml_layout/1

    Usage:

    Layout for html output.

    • The following properties should hold upon exit:
      (term/1)Arg1 is any term.

    PREDICATEhtmlurl/1

    Usage:

    Deploy URL for html output

    • The following properties should hold upon exit:
      (term/1)Arg1 is any term.

    PREDICATEhtml_asset/1

    Usage:

    Directory with additional files for HTML backend

    • The following properties should hold upon exit:
      (dirpath/1)Arg1 is a full path to a directory.

    PREDICATEtmplpath/1

    Usage:

    Directory for HTML templates

    • The following properties should hold upon exit:
      (dirpath/1)Arg1 is a full path to a directory.

    Usage:load_doc_module(F)

    Documentation module (doc_module) for extensions (see doc_module).

    • The following properties should hold upon exit:
      (term/1)F is any term.

    PREDICATEend_of_file/0
    No further documentation available for this predicate.