.. index:: lgtdocp
.. _lgtdocp/0:

.. rst-class:: right

**protocol**

``lgtdocp``
===========

Documenting tool protocol.

| **Availability:** 
|    ``logtalk_load(lgtdoc(loader))``

| **Author:** Paulo Moura
| **Version:** 5:2:0
| **Date:** 2023-11-28

| **Compilation flags:**
|    ``static``


| **Dependencies:**
|   (none)


| **Remarks:**

   - Compiling files for generating XML documentation: All source files must be compiled with the ``source_data`` flag turned on.
   - ``xml_spec(Specification)`` option: XML documenting files specification format. Possible option values are ``dtd`` (DTD specification; default) and ``xsd`` (XML Schema specification).
   - ``xml_spec_reference(Reference)`` option: Reference to the XML specification file in XML documenting files. Possible values are ``local`` (default; DTD/XSD file in same folder as XML files), ``web`` (logtalk.org website DTD/XSD file), and ``standalone`` (no reference to specification files).
   - ``entity_xsl_file(File)`` option: XSLT file to use with generated XML documenting files. Default is ``logtalk_entity_to_xml.xsl``, allowing the XML files to be viewed by opening them with a browser supporting XSLT (after running the ``lgt2xml.sh`` script on the output directory).
   - ``index_xsl_file(File)`` option: XSLT file to use with generated XML documenting files. Default is ``logtalk_index_to_xml.xsl``, allowing the XML files to be viewed by opening them with a browser supporting XSLT (after running the ``lgt2xml.sh`` script on the output directory).
   - ``xml_docs_directory(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.
   - ``omit_path_prefixes(Prefixes)`` option: List of path prefixes (atoms) to omit when writing directory paths. The default value is to omit the home directory.
   - ``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 (default is ``[]``).
   - ``exclude_prefixes(List)`` option: List of path prefixes to exclude when generating the XML documenting files (default is ``[]``).
   - ``exclude_entities(List)`` option: List of entities to exclude when generating the XML documenting files (default is ``[]``).
   - ``sort_predicates(Boolean)`` option: Sort entity predicates (default is ``false``).
   - Known issues: Some options may depend on the used XSL processor. Most XSL processors support DTDs but only some of them support XML Schemas. Some processors (e.g. ``fop2``) reject reference to a DTD.

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: rlibraries/2
.. _lgtdocp/0::rlibraries/2:

``rlibraries/2``
^^^^^^^^^^^^^^^^

Creates XML documenting files for all entities in all given libraries and their sub-libraries using the specified options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``rlibraries(Libraries,Options)``
| **Mode and number of proofs:**
|    ``rlibraries(+list(atom),+list)`` - ``one``


------------

.. index:: rlibraries/1
.. _lgtdocp/0::rlibraries/1:

``rlibraries/1``
^^^^^^^^^^^^^^^^

Creates XML documenting files for all entities in all given libraries and their sub-libraries using default options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``rlibraries(Libraries)``
| **Mode and number of proofs:**
|    ``rlibraries(+list(atom))`` - ``one``


------------

.. index:: rlibrary/2
.. _lgtdocp/0::rlibrary/2:

``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 and 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``


------------

.. index:: rlibrary/1
.. _lgtdocp/0::rlibrary/1:

``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 and 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``


------------

.. index:: libraries/2
.. _lgtdocp/0::libraries/2:

``libraries/2``
^^^^^^^^^^^^^^^

Creates XML documenting files for all entities in all given libraries using the specified options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``libraries(Libraries,Options)``
| **Mode and number of proofs:**
|    ``libraries(+list(atom),+list)`` - ``one``


------------

.. index:: libraries/1
.. _lgtdocp/0::libraries/1:

``libraries/1``
^^^^^^^^^^^^^^^

Creates XML documenting files for all entities in all given libraries using default options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``libraries(Libraries)``
| **Mode and number of proofs:**
|    ``libraries(+list(atom))`` - ``one``


------------

.. index:: library/2
.. _lgtdocp/0::library/2:

``library/2``
^^^^^^^^^^^^^

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

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``library(Library,Options)``
| **Mode and 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('logtalk_entity_to_pdf_a4.xsl')])``
|      ``yes``


------------

.. index:: library/1
.. _lgtdocp/0::library/1:

``library/1``
^^^^^^^^^^^^^

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

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``library(Library)``
| **Mode and number of proofs:**
|    ``library(+atom)`` - ``one``


------------

.. index:: rdirectories/2
.. _lgtdocp/0::rdirectories/2:

``rdirectories/2``
^^^^^^^^^^^^^^^^^^

Creates XML documenting files for all entities in all given directories and their sub-directories using the specified options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``rdirectories(Directories,Options)``
| **Mode and number of proofs:**
|    ``rdirectories(+list(atom),+list)`` - ``one``


------------

.. index:: rdirectories/1
.. _lgtdocp/0::rdirectories/1:

``rdirectories/1``
^^^^^^^^^^^^^^^^^^

Creates XML documenting files for all entities in all given directories and their sub-directories using default options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``rdirectories(Directories)``
| **Mode and number of proofs:**
|    ``rdirectories(+list(atom))`` - ``one``


------------

.. index:: rdirectory/2
.. _lgtdocp/0::rdirectory/2:

``rdirectory/2``
^^^^^^^^^^^^^^^^

Creates XML documenting files for all entities in a directory and its sub-directories using the specified options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``rdirectory(Directory,Options)``
| **Mode and number of proofs:**
|    ``rdirectory(+atom,+list)`` - ``one``

| **Examples:**
|    Generate XML documenting files for all entities in the tools directory for later conversion to Markdown files
|      ``rdirectory('./tools',[xslfile('lgtmd.xsl')])``
|      ``yes``


------------

.. index:: rdirectory/1
.. _lgtdocp/0::rdirectory/1:

``rdirectory/1``
^^^^^^^^^^^^^^^^

Creates XML documenting files for all entities in a directory and its sub-directories using default options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``rdirectory(Directory)``
| **Mode and number of proofs:**
|    ``rdirectory(+atom)`` - ``one``

| **Examples:**
|    Generate XML documenting files for all entities in the tools directory for direct viewing in a browser (after indexing using the ``lgt2xml`` script)
|      ``rdirectory('./tools')``
|      ``yes``


------------

.. index:: directories/2
.. _lgtdocp/0::directories/2:

``directories/2``
^^^^^^^^^^^^^^^^^

Creates XML documenting files for all entities in all given directories using the specified options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``directories(Directories,Options)``
| **Mode and number of proofs:**
|    ``directories(+list(atom),+list)`` - ``one``


------------

.. index:: directories/1
.. _lgtdocp/0::directories/1:

``directories/1``
^^^^^^^^^^^^^^^^^

Creates XML documenting files for all entities in all given directories using default options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``directories(Directories)``
| **Mode and number of proofs:**
|    ``directories(+list(atom))`` - ``one``


------------

.. index:: directory/2
.. _lgtdocp/0::directory/2:

``directory/2``
^^^^^^^^^^^^^^^

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

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``directory(Directory,Options)``
| **Mode and number of proofs:**
|    ``directory(+atom,+list)`` - ``one``

| **Examples:**
|    Generate XML documenting files for all the entities in the current directory for later conversion to PDF A4 files
|      ``directory('.',[xslfile('logtalk_entity_to_pdf_a4.xsl')])``
|      ``yes``


------------

.. index:: directory/1
.. _lgtdocp/0::directory/1:

``directory/1``
^^^^^^^^^^^^^^^

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

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``directory(Directory)``
| **Mode and number of proofs:**
|    ``directory(+atom)`` - ``one``


------------

.. index:: files/2
.. _lgtdocp/0::files/2:

``files/2``
^^^^^^^^^^^

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

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``files(Files,Options)``
| **Mode and number of proofs:**
|    ``files(+list(atom),+list)`` - ``one``


------------

.. index:: files/1
.. _lgtdocp/0::files/1:

``files/1``
^^^^^^^^^^^

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

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``files(Files)``
| **Mode and number of proofs:**
|    ``files(+list(atom))`` - ``one``


------------

.. index:: file/2
.. _lgtdocp/0::file/2:

``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 and number of proofs:**
|    ``file(+atom,+list)`` - ``one``


------------

.. index:: file/1
.. _lgtdocp/0::file/1:

``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 and number of proofs:**
|    ``file(+atom)`` - ``one``


------------

.. index:: all/1
.. _lgtdocp/0::all/1:

``all/1``
^^^^^^^^^

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

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``all(Options)``
| **Mode and number of proofs:**
|    ``all(+list)`` - ``one``


------------

.. index:: all/0
.. _lgtdocp/0::all/0:

``all/0``
^^^^^^^^^

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

| **Compilation flags:**
|    ``static``

| **Mode and number of proofs:**
|    ``all`` - ``one``


------------

Protected predicates
--------------------

(none)

Private predicates
------------------

(none)

Operators
---------

(none)

.. seealso::

   :ref:`lgtdoc <lgtdoc/0>`

