@subheading Name
 
The @code{help} functionlity is part of @command{centos-art.sh} script
and standardizes documentation tasks related to @emph{The CentOS
Artwork Repository Reference Manual} in the working copy of CentOS
Artwork Repository.
 
@subheading Synopsis
 
@command{centos-art help [OPTIONS] path/to/dir @dots{}}
 
The @file{path/to/dir} parameter specifies what directory structure
inside the working copy of CentOS Artwork Repository you want to
process. 
 
The @code{help} functionality of @command{centos-art.sh} script
accepts the following options:
 
@table @option
@item --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
@option{--answer-yes} option had been provided.
 
@item --answer-yes
 
Assume `yes' to all confirmation requests.
 
@item --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.
 
@item --search="STRING"
 
Go to node pointed by index entry @samp{STRING}.
 
@item --edit "path/to/dir"
 
Edit documentation entry related to path specified by
@file{path/to/dir}. 
 
The @file{path/to/dir} must point to any directory inside the
repository. When more than one @file{path/to/dir} are passed as
non-option arguments to the @command{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 @env{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.).
 
@item --read "path/to/dir"
 
Read documentation entry specified by @file{file/to/dir} path.  This
option is used internally by @command{centos-art.sh} script to print
out the reference you can follow to know more about an error message.
 
@item --update
 
Update output files rexporting them from the specified backend source
files.
 
@item --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 @command{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 @file{trunk/Manuals/Texinfo/Directories} directory structure.
 
@item --delete "path/to/dir"
 
Delete documentation entries inside the working copy of CentOS
Artwork Repository.
 
@item --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 @command{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 @file{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.
 
@end table
 
When documentation entries are removed (e.g., through
@option{--delete} or @option{--rename} options), the
@command{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.
 
@subheading Description
 
Inside the CentOS Artwork Repository, The CentOS Project corporate
identity is organized through directories. Each directory inside the
repository responds to one or more conceptual ideas. The conceptual
ideas each directory inside the repository is based on, is implemented
through files.  
 
The @code{help} functionality of @command{centos-art.sh} script 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 @emph{repository documentation
entries}.
 
@quotation
@strong{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.
@end quotation
 
The repository documentation entries are organized as sections inside
a chapter named @samp{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 @file{trunk/Scripts/Functions/Help/Templates}
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 repository.
 
The relation between template files and repository paths is set in the
@file{repository.conf} file. In this file, all lines begining with a
@samp{#} 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 @samp{template = "path-regex"}, where
@samp{template} is the relative path to section template and
@samp{"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:
 
@verbatim
# 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$"
@end verbatim
 
The @code{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 @code{help}
functionality is the interface the @command{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 @code{help} functionality takes the repository documentation
manual in texinfo format as input and produces Info, Pdf, XML, Xhtml
and Txt output files in the @file{trunk/Manuals/RepoReference/$LANG}
directory structure, where @var{$LANG} represents the language of the
manual.  The Info, Pdf and Txt output files are produced through
@command{makeinfo} command and the Xhtml output through
@command{texi2html} command. Using the @command{makeinfo} command it
is also possible to output the repository documentation manual in
DocBook format, however, the DocBook output produced by
@command{makeinfo} command seems to have some malformations.
 
When producing Xhtml output, through @command{texi2html} command, the
output customization is controlled by common and specific
configuration files. Common configuration files are stored in
@file{trunk/Manuals/RepoReference} and include @file{repository.css},
@file{repository-init.pl} and @file{repository.sed}. Specific
configuration files, on the other hand, are stored inside the
language-specific template directory (e.g.,
@file{trunk/Scripts/Functions/Help/Templates/$LANG}) and includes
@file{repository-init.pl}, @file{repository.conf},
@file{repository.sed}.
 
When writting documentation entries through @samp{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 @file{trunk/} directory structure on.  This is necessary because
the documentation manual is exported using @file{@var{$HOME}/artwork}
directory structure as base.
 
Internationalization of repository documentation manual is performed
trough document templates and the @env{LANG} environment variable.
There might be one repository documentation manual for each locale
specified by @env{LANG} environment variable. When no template is
available for a specific language, the @code{en_US} templates are used
as reference.
 
Each repository documentation manual written in a language other than
English, must include the @samp{@@documentlanguage} and
@samp{@@documentencoding} directives in the main document file (e.g.,
@file{repository.texinfo}) to provide the language and encoding
information respectively.  The language information can be any value
specified by ISO-639 language code standard and the ecoding
informormation can be either @samp{US-ASCII}, @samp{ISO-8859-1},
@samp{ISO-8859-15} or @samp{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., @samp{@@'a}, @samp{@@~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.,
@command{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
@command{texi2html} command to transform special characters to HTML
entities (e.g., @samp{á}, @samp{ñ}, etc.).  In the Pdf
output, special characters are printed well most of times with some
exceptions (e.g., the @samp{@@'i} don't replaces the dot over the
letter with the accentuation, but put the accentuation over it.).
 
@quotation
@strong{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
@samp{@@documentencoding} directive when you be writing documentation
entries through @code{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 read special
characters from Info files in UTF-8 terminals.
@end quotation
 
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
@command{centos-art.sh} script. If one of these functionalities
returns an error, the @command{centos-art.sh} script will suggest to
you executing a @code{help} command to know more about why the error
happend.  This @code{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 @command{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 @command{centos-art.sh} script and the conceptual ideas
behind it.
 
@subheading Examples
 
@table @command
@item centos-art help --edit trunk/Identity
 
This command edits the documentation entry related to
@file{trunk/Identity} directory.
 
@item centos-art help --read trunk/Identity
 
This command reads the doumentation entry related to
@file{trunk/Identity} directory in info format.
 
@end table
 
@subheading Author
 
Written by Alain Reguera Delgado.
 
@subheading Reporting bugs
 
Report bugs to @email{centos-artwork@@centos.org} mailing list.
 
@subheading Copyright
 
Copyright @copyright{}  2009, 2010, 2011 The CentOS Project.
 
This  is free software.  You may redistribute copies of it under the
terms of the @ref{GNU General Public License}.  There is NO WARRANTY,
to the extent permitted by law.
 
@subheading See also
 
@itemize
@item @ref{Directories trunk Scripts Functions}
@item @ref{Directories trunk Scripts}
@item @ref{Directories trunk}
@end itemize