protocol

# lgtdocp

> Documenting tool protocol.

author:
  `Paulo Moura`
version:
  `2.0`
date:
  `2014/12/2`

compilation flags:
  `static`

(no dependencies on other files)

## Public interface

### rlibrary/2

> Creates XML documenting files for all entities in a library and its sub-libraries using the specified options.

compilation flags:
  `static`
template:
  `rlibrary(Library,Options)`
mode – number of proofs:
  `rlibrary(+atom,+list) – one`
examples:
  Generate XML documenting files for all tool entities for later conversion to Markdown files
    rlibrary(tools,[xslfile('lgtmd.xsl')])
    yes

### rlibrary/1

> Creates XML documenting files for all entities in a library and its sub-libraries using default options.

compilation flags:
  `static`
template:
  `rlibrary(Library)`
mode – number of proofs:
  `rlibrary(+atom) – one`
examples:
  Generate XML documenting files for all tool entities for direct viewing in a browser (after indexing using the "lgt2xml" script)
    rlibrary(tools)
    yes

### library/2

> Creates XML documenting files for all entities in a library using the specified options.

compilation flags:
  `static`
template:
  `library(Library,Options)`
mode – number of proofs:
  `library(+atom,+list) – one`
examples:
  Generate XML documenting files for all library entities for later conversion to PDF A4 files
    library(library,[xslfile('lgtpdfa4.xsl')])
    yes

### library/1

> Creates XML documenting files for all entities in a library using default options.

compilation flags:
  `static`
template:
  `library(Library)`
mode – number of proofs:
  `library(+atom) – one`

### file/2

> Creates XML documenting files for all entities in a loaded source file using the specified options. The file can be given by name, basename, full path, or using library notation.

compilation flags:
  `static`
template:
  `file(File,Options)`
mode – number of proofs:
  `file(+atom,+list) – one`

### file/1

> Creates XML documenting files for all entities in a loaded source file using default options. The file can be given by name, basename, full path, or using library notation.

compilation flags:
  `static`
template:
  `file(File)`
mode – number of proofs:
  `file(+atom) – one`

### all/1

> Creates XML documenting files for all loaded entities using the specified options.

compilation flags:
  `static`
template:
  `all(File)`
mode – number of proofs:
  `all(+list) – one`

### all/0

> Creates XML documenting files for all loaded entities using default options.

compilation flags:
  `static`
mode – number of proofs:
  `all – one`

### option/2

> Returns, by backtracking, all options and their values.

compilation flags:
  `static`
template:
  `option(Option,Value)`
mode – number of proofs:
  `option(?atom,?nonvar) – zero_or_more`

### set_option/2

> Sets an option value.

compilation flags:
  `static`
template:
  `set_option(Option,Value)`
mode – number of proofs:
  `set_option(+atom,+nonvar) – zero_or_one`

## Protected interface

(none)

## Private predicates

(none)

## Operators

### (none)

## Remarks

Compiling files for generating XML documentation
  All source files must be compiled with the "source_data" compiler flag turned on.

xmlspec(Specification) option
  XML documenting files specification format. Possible option values are "dtd" (for the DTD specification; default) and "xsd" (for the XML Schema specification).

xmlsref(Reference) option
  Reference to the XML specification file in XML documenting files. Possible values are "local" (default; DTD/XSD file in the same folder as the XML files), "web" (logtalk.org website DTD/XSD file), and "standalone" (no reference to specification files).

xslfile(File) option
  XSLT file to use with the generated XML documenting files. The default value is "lgtxml.xsl", allowing the XML files to be viewed by simply opening them with a browser supporting XSLT (after running the "lgt2xml.sh" script on the XML files directory).

xmldir(Directory) option
  Directory where the XML documenting files will be generated. The default value is "./xml_docs", a sub-directory of the source files directory.

bom(Boolean) option
  Defines if a BOM should be added to the generated XML documenting files.

encoding(Encoding) option
  Encoding to be used for the generated XML documenting files.

exclude_files(List) option
  List of files to exclude when generating the XML documenting files.

exclude_paths(List) option
  List of (relative) library paths to exclude when generating the XML documenting files.

exclude_entities(List) option
  List of entities to exclude when generating the XML documenting files.

Known issues
  The most appropriated options may depends on the XSL processor you intend to use. Most XSL processors support DTDs but only some of them support XML Schemas. Some processors are buggy an may not work with the default option values.