@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 and so to print error messages. When a

run time error occurs, the @command{centos-art.sh} script will suggest

you to execute 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 wrongly printed; if printed at all. In this

situation it would be required to change the terminal codification to

that one set in the Info file before reading the info file.

Notice also that, the main purpose of using Texinfo as documentation

backend when writing documentation related to each repository

directory, is the possibility of producing Info files as output. This

posibility is used by @command{centos-art.sh} script to build internal

documentation references to know where and why the error 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