@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
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 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''.
@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
Structurely, the @code{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
@file{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
@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 takes the repository documentation
manual in texinfo format as input and produces Info, Pdf, XML,
DocBook, 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.
@quotation
@strong{Caution} The DocBook output produced by @command{makeinfo}
(@file{texinfo-4.8-14.el5}) doesn't conform with its @acronym{DTD,
Document Type Definition}. To determine whether the DocBook XML output
conforms its DTD or not, try the following command:
@verbatim
xmllint --valid --noout repository.docbook
@end verbatim
@end quotation
The Xhtml output produced by @command{texi2html} is customized through
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}) which
includes the @file{repository-init.pl}, @file{repository.conf},
@file{repository.sed} files.
The @code{help} functionality takes the @file{trunk/} directory
structure as top level directory for including external files inside
repository documention entries. This specification is imposed because
the action of exporting different outputs is performed from
@file{@var{$HOME}/artwork} directory structure. There is no obligation
to use this specific directory structure as base location for
exporting Texinfo outputs, it is a matter of convenience. Notice that,
all path information output from @command{centos-art.sh} script does
begin with @file{trunk/} directory structure as top level directory,
as convenction. In that sake, using the @file{@var{$HOME}/artwork}
directory structure as base directory location for including external
files in repository documentation entries provides consistency with
the way @command{centos-art.sh} script outputs path information.
Internationalization of document structures produced by @code{help}
functionality 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 provided by
@samp{@@documentlanguage} can be any value specified by ISO-639
language code standard. The encoding information provided by
@samp{@@documentencoding} 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 to 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