Name
----

The help functionlity is part of centos-art.sh script and standardizes documentation tasks related to The CentOS Artwork Repository Reference Manual in the working copy of CentOS Artwork Repository.

Synopsis
--------

centos-art help [OPTIONS] path/to/dir ...

The path/to/dir parameter specifies what directory structure inside the working copy of CentOS Artwork Repository you want to process.

The help functionality of centos-art.sh script accepts the following options:

--quiet

     Supress all output messages except error messages.  When this option is passed, all confirmation requests are supressed as well and a possitive answer is assumed for them, just as if the --answer-yes option had been provided.

--answer-yes

     Assume `yes' to all confirmation requests.

--dont-commit-changes

     Supress all commit and update actions realized over files, before and after the action itself had took place over files in the working copy.

--search="STRING"

     Go to node pointed by index entry STRING.

--edit "path/to/dir"

     Edit documentation entry related to path specified by path/to/dir.

     The path/to/dir must point to any directory inside the repository. When more than one path/to/dir are passed as non-option arguments to the centos-art.sh script command-line, they are queued for further edition.  The edition itself takes place through your default text editor (e.g., the one you specified in the EDITOR environment variable) and the text editor opens one file at time (i.e., the queue of files to edit is not loaded in the text editor.).

--read "path/to/dir"

     Read documentation entry specified by file/to/dir path.  This option is used internally by centos-art.sh script to print out the reference you can follow to know more about an error message.

--update

     Update output files rexporting them from the specified backend source files.

--copy "path/to/srcdir" "path/to/dstdir"

     Duplicate documentation entries inside the working copy of CentOS Artwork Repository.

     When documentation entries are copied, only two non-option arguments can be passed to centos-art.sh script. In this case, the first non-option argument is considered the source location and the second one the target location. Both source location and target location must point to a directory under the working copy or files under trunk/Manuals/Texinfo/Directories directory structure.

--delete "path/to/dir"

     Delete documentation entries inside the working copy of CentOS Artwork Repository.

--rename "path/to/srcdir" "path/to/dstdir"

     Rename documentation entries inside the working copy of CentOS Artwork Repository.

     When documentation entries are renamed, only two non-option arguments can be passed to centos-art.sh script. In this case, the first non-option argument is considered the source location and the second one the target location. Both source location and target location must point to a directory under the working copy or files under trunk/Manuals/Texinfo/Directories directory structure.

     Renaming a repository documentation entries introduce some complications because inclusions, menus, nodes and cross references are built using master path information as reference.  Now, to see what kind of complication we are trying to solve with path syncronization, consider what would happen to document structural definitions (i.e., inlusions, menus, nodes and cross refereces) when a master path that is suddenly renamed to something different.  At this point, if the path information is not updated, we lose connection between the master path and the auxiliar path created to store the related documentation entry, as well as the related structural definitions that will end up pointing to a master path that no longer exist.

When documentation entries are removed (e.g., through --delete or --rename options), the centos-art.sh script takes care of updating nodes, menus and cross references related to documentation entries in order to keep the manual structure in a correct state.

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

The help functionality uses Texinfo as documentation backend. Texinfo is a documentation system that can produce both online information and a printed manual from a single source. The help functionality is the interface the centos-art.sh script uses to control frequent documenting tasks (e.g., reading, editing, update output files, etc.) in the source files of a Texinfo documentation manual structure.

The help functionality uses the repository directory layout as reference to describe the conceptual ideas behind its existance. Each directory inside the repository can be documented, in order to provide the explanation of what it is for and how automation scripts use it. Documentation of each directory happens through ``repository documentation entries''.

     Caution When the repository directory layout changes, the documentation layout related must be changed as well in order for both locations to be consistent in their paths. Otherwise, you may end up having documentation entries that point to unexistent directories in the repository.

Structurely, the help functionality organizes repository documentation entries by sections inside a chapter named ``The repository directories''. Each section is organized through ``Goals'', ``Description'', ``Usage'' and ``See also'' subsections which, in turn, may be organized through subsubsections so as to describe what the related repository directory is for. The first three section (e.g., Goals, Description and Usage) are created in blank for you to fill with information, but the last one (e.g., See also) 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 ``document templates''. Document templates are organized in the trunk/Scripts/Functions/Help/Templates directory and are used when a new documentation structure is created and later, when a new documentation entry is created inside it. There is one set of document templates for each language-specific documentation structure supported. Inside each language-specific documentation structure there is one documentation entry for each directory inside the repository.

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$"

The help functionality takes the repository documentation manual in texinfo format as input and produces Info, Pdf, XML, DocBook, Xhtml and Txt output files in the trunk/Manuals/RepoReference/$LANG directory structure, where $LANG represents the language of the manual.  The Info, Pdf and Txt output files are produced through makeinfo command and the Xhtml output through texi2html command.

     Caution The DocBook output produced through makeinfo (texinfo-4.8-14.el5) doesn't conform with its DTD specification.

When producing Xhtml output, through texi2html command, the output customization is controlled by common and specific configuration files. Common configuration files are stored in trunk/Manuals/RepoReference and include repository.css, repository-init.pl and repository.sed. Specific configuration files, on the other hand, are stored inside the language-specific template directory (e.g., trunk/Scripts/Functions/Help/Templates/$LANG) and includes repository-init.pl, repository.conf, repository.sed.

When writting documentation entries through help functionality, the way absolute paths are defined inside them is important.  Absolute path definitions (e.g., through `@include' and `@image') must be set from trunk/ directory structure on.  This is necessary because the documentation manual is exported using $HOME/artwork directory structure as base.

Internationalization of document structures produced by help functionality is performed trough document templates and the LANG environment variable.  There might be one repository documentation manual for each locale specified by LANG environment variable. When no template is available for a specific language, the en_US templates are used as reference.  Each repository documentation manual written in a language other than English, must include the @documentlanguage and @documentencoding directives in the main document file (e.g., repository.texinfo) to provide the language and encoding information, respectively.  The language information provided by @documentlanguage can be any value specified by ISO-639 language code standard.  The encoding information provided by @documentencoding can be either US-ASCII, ISO-8859-1, ISO-8859-15 or ISO-8859-2.

The encoding information is required in order for Txt and Info outputs to show special characters, defined through Texinfo special way of accentuation (e.g., @'a, @~n, etc.), correctly. In this specific case, to read both Txt and Info files, it is required that the terminal you are performing the reading action (e.g., gnome-terminal) be encoded with the same value you specified inside the repository documentation manual. Otherwise, special characters may not look as expected.  Using Texinfo special way of accentuation is also required for texi2html command to transform special characters to HTML entities (e.g., &aacute;, &ntilde;, etc.).  In the Pdf output, special characters are printed well most of times with some exceptions (e.g., the @'i don't replaces the dot over the letter with the accentuation, but put the accentuation over it.).

     Note Using other codifications but UTF-8 in the terminal might be not convenient in some situations. Prevent yourself from using Texinfo special way of accentuation and the @documentencoding directive when you be writing documentation entries through help functionality. This will hide special characters in Pdf output and, in XHTML output no entity will be translated. However, this configuration will let you to read special characters from Info files in UTF-8 terminals.

Notice that, UTF-8 is the default character codification used by the terminal inside The CentOS Distribution. This is the terminal configuration we use for executing functionalities of centos-art.sh script. If one of these functionalities returns an error, the centos-art.sh script will suggest to you executing a help command to know more about why the error happend.  This help command will read the information from an Info file. If the Info file is codified to be read in an encoding different to the one the terminal we are performing the action is set, special characters will be printed wrongly; if printed at all. In this situation it would be required to change the terminal codification to that one set in the Info file, which might be something not desirable.

Notice also that, the main purpose of using Texinfo as documentation backend to write documentation related to each repository directory, is the possibility it provides of producing Info files as output. This posibility is used by centos-art.sh script to build internal references where documentation can be found when errors happen.  It lets users to type a command immediatly after errors to know more about them, once they happen. It is about creating a direct connection between the centos-art.sh script and the conceptual ideas behind it.

Examples
--------

centos-art help --edit trunk/Identity

     This command edits the documentation entry related to trunk/Identity directory.

centos-art help --read trunk/Identity

     This command reads the doumentation entry related to trunk/Identity directory in info format.

Author
------

Written by Alain Reguera Delgado.

Reporting bugs
--------------

Report bugs to centos-artwork@centos.org mailing list.

Copyright
---------

Copyright ©  2009, 2010, 2011 The CentOS Project.

This  is free software.  You may redistribute copies of it under the terms of the GNU General Public License.  There is NO WARRANTY, to the extent permitted by law.

See also
--------

  * Directories trunk Scripts Functions

  * Directories trunk Scripts

  * Directories trunk