Goals
-----

The trunk/Scripts/Functions/Help/Backends directory organizes documentation backends used by help functionality of centos-art.sh script.

Description
-----------

Documentation backends are organized inside directories. There is one directory for each documentation backend. Inside backend directories, documentation actions are implemented by mean of shell functions. There is one shell function for each documentation action (e.g., reading, editing, updating output, etc.) and auxiliar shell functions to backup documentation actions.

Inside backend directories, shell functions must have the same structure in their names. The name structure used by shell functions here is: suffix_funcname.sh, were suffix is the name of the directory backend in lowercase and funcname is the name of the function. Assuming, both texinfo and docbook backends have been already implemented, they must have a structure similar to the following:

trunk/Scripts/Functions/Help/Backends
|-- Docbook
|   |-- Templates
|   |   |-- en_US
|   |   `-- ...
|   |-- docbook_editEntry.sh
|   |-- docbook_updateOutputFiles.sh
|   `-- ...
`-- Texinfo
    |-- Templates
    |   |-- en_US
    |   `-- ...
    |-- texinfo_editEntry.sh
    |-- texinfo_updateOutputFiles.sh
    `-- ...

The repository documentation entries are organized as sections inside a chapter named The repository directories. Each section contains three subsections (e.g., Goals, Description, Usage and See also) and optionally one or more subsubsections inside them to describe what the related repository directory is for. The first three section are created in blank for you to fill with information, but the last one is created automatically and contains a list of links to previous sections.

The internal document organization and language used in repository documentation entries are both defined through templates.  Templates are organized in the Templates directory which is located inside the backend directory. Templates are used when a new documentation structure is created and later, when a new documentation entry is created inside it.  There is one documentation manual structure for each language supported and one documentation entry inside the documentation manual for each directory inside the repositroy.

The relation between template files and repository paths is set in the repository.conf file. In this file, all lines begining with a # character are considered comments. Both comments and empty lines are removed from the configuration file before evaluating it, so only configuration lines will remain to be evaluated.  Configuration lines must be in the form template = "path-regex", where template is the relative path to section template and "path-regex" a regular expression describing the path information where you want to apply the template on. Empty spaces are irrelevant around the equal sign. As example, consider the following configuration file:

# This file defines the relation between section templates and
# repository paths. Here you can customize the section template of
# specific directories inside the repository. The first match wins.
# ----------------------------------------------------------------------
# $Id: repository.conf 3222 2011-06-04 19:35:00Z al $
# ----------------------------------------------------------------------

Directories/section-functions.texinfo   = "(trunk|branches|tags)/Scripts/Functions/[[:alnum:]]+\.texinfo$"
Directories/section.texinfo             = "(trunk|branches|tags).*\.texinfo$"

Usage
-----

The following documentation backends are available:

  * Directories trunk Scripts Functions Help Backends Texinfo

  * Directories trunk Scripts Functions Help Backends Docbook

  * Directories trunk Scripts Functions Help Backends Linuxdoc

See also
--------

  * Directories trunk Scripts Functions Help

  * Directories trunk Scripts Functions

  * Directories trunk Scripts

  * Directories trunk