|
|
b32b45 |
@subheading Name
|
|
|
b32b45 |
|
|
|
b32b45 |
The @code{help} functionlity is part of @command{centos-art.sh} script
|
|
|
561a00 |
and standardizes documentation tasks related to @emph{The CentOS
|
|
|
561a00 |
Artwork Repository Reference Manual} in the working copy of CentOS
|
|
|
b32b45 |
Artwork Repository.
|
|
|
b32b45 |
|
|
|
b32b45 |
@subheading Synopsis
|
|
|
b32b45 |
|
|
|
b32b45 |
@command{centos-art help [OPTIONS] path/to/dir @dots{}}
|
|
|
b32b45 |
|
|
|
b32b45 |
The @file{path/to/dir} parameter specifies what directory structure
|
|
|
b32b45 |
inside the working copy of CentOS Artwork Repository you want to
|
|
|
b32b45 |
process.
|
|
|
b32b45 |
|
|
|
b32b45 |
The @code{help} functionality of @command{centos-art.sh} script
|
|
|
b32b45 |
accepts the following options:
|
|
|
b32b45 |
|
|
|
b32b45 |
@table @option
|
|
|
b32b45 |
@item --quiet
|
|
|
b32b45 |
|
|
|
b32b45 |
Supress all output messages except error messages. When this option
|
|
|
b32b45 |
is passed, all confirmation requests are supressed as well and a
|
|
|
b32b45 |
possitive answer is assumed for them, just as if the
|
|
|
b32b45 |
@option{--answer-yes} option had been provided.
|
|
|
b32b45 |
|
|
|
b32b45 |
@item --answer-yes
|
|
|
b32b45 |
|
|
|
b32b45 |
Assume `yes' to all confirmation requests.
|
|
|
b32b45 |
|
|
|
b32b45 |
@item --dont-commit-changes
|
|
|
b32b45 |
|
|
|
b32b45 |
Supress all commit and update actions realized over files, before and
|
|
|
b32b45 |
after the action itself had took place over files in the working copy.
|
|
|
b32b45 |
|
|
|
b32b45 |
@item --search="STRING"
|
|
|
b32b45 |
|
|
|
b32b45 |
Go to node pointed by index entry @samp{STRING}.
|
|
|
b32b45 |
|
|
|
b32b45 |
@item --edit "path/to/dir"
|
|
|
b32b45 |
|
|
|
b32b45 |
Edit documentation entry related to path specified by
|
|
|
b32b45 |
@file{path/to/dir}.
|
|
|
b32b45 |
|
|
|
b32b45 |
The @file{path/to/dir} must point to any directory inside the
|
|
|
b32b45 |
repository. When more than one @file{path/to/dir} are passed as
|
|
|
b32b45 |
non-option arguments to the @command{centos-art.sh} script
|
|
|
b32b45 |
command-line, they are queued for further edition. The edition itself
|
|
|
b32b45 |
takes place through your default text editor (e.g., the one you
|
|
|
b32b45 |
specified in the @env{EDITOR} environment variable) and the text
|
|
|
b32b45 |
editor opens one file at time (i.e., the queue of files to edit is not
|
|
|
b32b45 |
loaded in the text editor.).
|
|
|
b32b45 |
|
|
|
b32b45 |
@item --read "path/to/dir"
|
|
|
b32b45 |
|
|
|
b32b45 |
Read documentation entry specified by @file{file/to/dir} path. This
|
|
|
b32b45 |
option is used internally by @command{centos-art.sh} script to print
|
|
|
b32b45 |
out the reference you can follow to know more about an error message.
|
|
|
b32b45 |
|
|
|
b32b45 |
@item --update
|
|
|
b32b45 |
|
|
|
b32b45 |
Update output files rexporting them from the specified backend source
|
|
|
b32b45 |
files.
|
|
|
b32b45 |
|
|
|
b32b45 |
@item --copy "path/to/srcdir" "path/to/dstdir"
|
|
|
b32b45 |
|
|
|
b32b45 |
Duplicate documentation entries inside the working copy of CentOS
|
|
|
b32b45 |
Artwork Repository.
|
|
|
b32b45 |
|
|
|
b32b45 |
When documentation entries are copied, only two non-option arguments
|
|
|
b32b45 |
can be passed to @command{centos-art.sh} script. In this case, the
|
|
|
b32b45 |
first non-option argument is considered the source location and the
|
|
|
b32b45 |
second one the target location. Both source location and target
|
|
|
b32b45 |
location must point to a directory under the working copy or files
|
|
|
b32b45 |
under @file{trunk/Manuals/Texinfo/Directories} directory structure.
|
|
|
b32b45 |
|
|
|
b32b45 |
@item --delete "path/to/dir"
|
|
|
b32b45 |
|
|
|
b32b45 |
Delete documentation entries inside the working copy of CentOS
|
|
|
b32b45 |
Artwork Repository.
|
|
|
b32b45 |
|
|
|
b32b45 |
@item --rename "path/to/srcdir" "path/to/dstdir"
|
|
|
b32b45 |
|
|
|
b32b45 |
Rename documentation entries inside the working copy of CentOS Artwork
|
|
|
b32b45 |
Repository.
|
|
|
b32b45 |
|
|
|
b32b45 |
When documentation entries are renamed, only two non-option arguments
|
|
|
b32b45 |
can be passed to @command{centos-art.sh} script. In this case, the
|
|
|
b32b45 |
first non-option argument is considered the source location and the
|
|
|
b32b45 |
second one the target location. Both source location and target
|
|
|
b32b45 |
location must point to a directory under the working copy or files
|
|
|
b32b45 |
under @file{trunk/Manuals/Texinfo/Directories} directory structure.
|
|
|
b32b45 |
|
|
|
b32b45 |
Renaming a repository documentation entries introduce some
|
|
|
b32b45 |
complications because inclusions, menus, nodes and cross references
|
|
|
b32b45 |
are built using master path information as reference. Now, to see
|
|
|
b32b45 |
what kind of complication we are trying to solve with path
|
|
|
b32b45 |
syncronization, consider what would happen to document structural
|
|
|
b32b45 |
definitions (i.e., inlusions, menus, nodes and cross refereces) when a
|
|
|
b32b45 |
master path that is suddenly renamed to something different. At this
|
|
|
b32b45 |
point, if the path information is not updated, we lose connection
|
|
|
b32b45 |
between the master path and the auxiliar path created to store the
|
|
|
b32b45 |
related documentation entry, as well as the related structural
|
|
|
b32b45 |
definitions that will end up pointing to a master path that no longer
|
|
|
b32b45 |
exist.
|
|
|
b32b45 |
|
|
|
b32b45 |
@end table
|
|
|
b32b45 |
|
|
|
b32b45 |
When documentation entries are removed (e.g., through
|
|
|
b32b45 |
@option{--delete} or @option{--rename} options), the
|
|
|
b32b45 |
@command{centos-art.sh} script takes care of updating nodes, menus and
|
|
|
b32b45 |
cross references related to documentation entries in order to keep the
|
|
|
b32b45 |
manual structure in a correct state.
|
|
|
b32b45 |
|
|
|
b32b45 |
@subheading Description
|
|
|
b32b45 |
|
|
|
7a0691 |
The @code{help} functionality uses Texinfo as documentation backend.
|
|
|
7a0691 |
Texinfo is a documentation system that can produce both online
|
|
|
7a0691 |
information and a printed manual from a single source. The @code{help}
|
|
|
7a0691 |
functionality is the interface the @command{centos-art.sh} script uses
|
|
|
7a0691 |
to control frequent documenting tasks (e.g., reading, editing, update
|
|
|
7a0691 |
output files, etc.) in the source files of a Texinfo documentation
|
|
|
7a0691 |
manual structure.
|
|
|
7a0691 |
|
|
|
efd1d6 |
The @code{help} functionality uses the repository directory layout as
|
|
|
efd1d6 |
reference to describe the conceptual ideas behind its existance. Each
|
|
|
efd1d6 |
directory inside the repository can be documented, in order to provide
|
|
|
efd1d6 |
the explanation of what it is for and how automation scripts use it.
|
|
|
16a015 |
Documentation of each directory happens through ``repository
|
|
|
16a015 |
documentation entries''.
|
|
|
b32b45 |
|
|
|
b32b45 |
@quotation
|
|
|
b32b45 |
@strong{Caution} When the repository directory layout changes, the
|
|
|
b32b45 |
documentation layout related must be changed as well in order for both
|
|
|
b32b45 |
locations to be consistent in their paths. Otherwise, you may end up
|
|
|
b32b45 |
having documentation entries that point to unexistent directories in
|
|
|
b32b45 |
the repository.
|
|
|
b32b45 |
@end quotation
|
|
|
b32b45 |
|
|
|
974695 |
Structurely, the @code{help} functionality organizes repository
|
|
|
974695 |
documentation entries by sections inside a chapter named @samp{The
|
|
|
974695 |
repository directories}. Each section is organized through ``Goals'',
|
|
|
974695 |
``Description'', ``Usage'' and ``See also'' subsections which, in
|
|
|
974695 |
turn, may be organized through subsubsections to describe what the
|
|
|
974695 |
related repository directory is for. The first three section (e.g.,
|
|
|
974695 |
Goals, Description and Usage) are created in blank for you to fill
|
|
|
974695 |
with information, but the last one (e.g., See also) is created
|
|
|
974695 |
automatically and contains a list of links to previous sections.
|
|
|
561a00 |
|
|
|
561a00 |
The internal document organization and language used in repository
|
|
|
16a015 |
documentation entries are both defined through ``document templates''.
|
|
|
16a015 |
Document templates are organized in the
|
|
|
df36b6 |
@file{trunk/Scripts/Functions/Help/Templates} directory and are used
|
|
|
df36b6 |
when a new documentation structure is created and later, when a new
|
|
|
df36b6 |
documentation entry is created inside it. There is one set of document
|
|
|
df36b6 |
templates for each language-specific documentation structure
|
|
|
df36b6 |
supported. Inside each language-specific documentation structure there
|
|
|
df36b6 |
is one documentation entry for each directory inside the repository.
|
|
|
561a00 |
|
|
|
561a00 |
The relation between template files and repository paths is set in the
|
|
|
561a00 |
@file{repository.conf} file. In this file, all lines begining with a
|
|
|
561a00 |
@samp{#} character are considered comments. Both comments and empty
|
|
|
561a00 |
lines are removed from the configuration file before evaluating it, so
|
|
|
561a00 |
only configuration lines will remain to be evaluated. Configuration
|
|
|
561a00 |
lines must be in the form @samp{template = "path-regex"}, where
|
|
|
561a00 |
@samp{template} is the relative path to section template and
|
|
|
561a00 |
@samp{"path-regex"} a regular expression describing the path
|
|
|
561a00 |
information where you want to apply the template on. Empty spaces are
|
|
|
561a00 |
irrelevant around the equal sign. As example, consider the following
|
|
|
561a00 |
configuration file:
|
|
|
561a00 |
|
|
|
561a00 |
@verbatim
|
|
|
561a00 |
# This file defines the relation between section templates and
|
|
|
561a00 |
# repository paths. Here you can customize the section template of
|
|
|
561a00 |
# specific directories inside the repository. The first match wins.
|
|
|
561a00 |
# ----------------------------------------------------------------------
|
|
|
561a00 |
# $Id: repository.conf 3222 2011-06-04 19:35:00Z al $
|
|
|
561a00 |
# ----------------------------------------------------------------------
|
|
|
561a00 |
|
|
|
561a00 |
Directories/section-functions.texinfo = "(trunk|branches|tags)/Scripts/Functions/[[:alnum:]]+\.texinfo$"
|
|
|
561a00 |
Directories/section.texinfo = "(trunk|branches|tags).*\.texinfo$"
|
|
|
561a00 |
@end verbatim
|
|
|
561a00 |
|
|
|
7e4b2b |
The @code{help} functionality takes the repository documentation
|
|
|
7e4b2b |
manual in texinfo format as input and produces Info, Pdf, XML, Xhtml
|
|
|
7e4b2b |
and Txt output files in the @file{trunk/Manuals/RepoReference/$LANG}
|
|
|
7e4b2b |
directory structure, where @var{$LANG} represents the language of the
|
|
|
7e4b2b |
manual. The Info, Pdf and Txt output files are produced through
|
|
|
561a00 |
@command{makeinfo} command and the Xhtml output through
|
|
|
561a00 |
@command{texi2html} command. Using the @command{makeinfo} command it
|
|
|
561a00 |
is also possible to output the repository documentation manual in
|
|
|
7e4b2b |
DocBook format, however, the DocBook output produced by
|
|
|
7e4b2b |
@command{makeinfo} command seems to have some malformations.
|
|
|
561a00 |
|
|
|
561a00 |
When producing Xhtml output, through @command{texi2html} command, the
|
|
|
561a00 |
output customization is controlled by common and specific
|
|
|
561a00 |
configuration files. Common configuration files are stored in
|
|
|
7e4b2b |
@file{trunk/Manuals/RepoReference} and include @file{repository.css},
|
|
|
561a00 |
@file{repository-init.pl} and @file{repository.sed}. Specific
|
|
|
7e4b2b |
configuration files, on the other hand, are stored inside the
|
|
|
7e4b2b |
language-specific template directory (e.g.,
|
|
|
7e4b2b |
@file{trunk/Scripts/Functions/Help/Templates/$LANG}) and includes
|
|
|
7e4b2b |
@file{repository-init.pl}, @file{repository.conf},
|
|
|
561a00 |
@file{repository.sed}.
|
|
|
561a00 |
|
|
|
7e4b2b |
When writting documentation entries through @samp{help} functionality,
|
|
|
7e4b2b |
the way absolute paths are defined inside them is important. Absolute
|
|
|
7e4b2b |
path definitions (e.g., through `@@include' and `@@image') must be set
|
|
|
7e4b2b |
from @file{trunk/} directory structure on. This is necessary because
|
|
|
7e4b2b |
the documentation manual is exported using @file{@var{$HOME}/artwork}
|
|
|
561a00 |
directory structure as base.
|
|
|
561a00 |
|
|
|
227f88 |
Internationalization of document structures produced by @code{help}
|
|
|
227f88 |
functionality is performed trough document templates and the
|
|
|
227f88 |
@env{LANG} environment variable. There might be one repository
|
|
|
227f88 |
documentation manual for each locale specified by @env{LANG}
|
|
|
227f88 |
environment variable. When no template is available for a specific
|
|
|
227f88 |
language, the @code{en_US} templates are used as reference. Each
|
|
|
227f88 |
repository documentation manual written in a language other than
|
|
|
227f88 |
English, must include the @samp{@@documentlanguage} and
|
|
|
227f88 |
@samp{@@documentencoding} directives in the main document file (e.g.,
|
|
|
227f88 |
@file{repository.texinfo}) to provide the language and encoding
|
|
|
2f6bac |
information, respectively. The language information provided by
|
|
|
2f6bac |
@samp{@@documentlanguage} can be any value specified by ISO-639
|
|
|
2f6bac |
language code standard. The encoding information provided by
|
|
|
2f6bac |
@samp{@@documentencoding} can be either @samp{US-ASCII},
|
|
|
2f6bac |
@samp{ISO-8859-1}, @samp{ISO-8859-15} or @samp{ISO-8859-2}.
|
|
|
2f6bac |
|
|
|
2f6bac |
The encoding information is required in order for Txt and Info outputs
|
|
|
2f6bac |
to show special characters, defined through Texinfo special way of
|
|
|
2f6bac |
accentuation (e.g., @samp{@@'a}, @samp{@@~n}, etc.), correctly. In
|
|
|
2f6bac |
this specific case, to read both Txt and Info files, it is required
|
|
|
2f6bac |
that the terminal you are performing the reading action (e.g.,
|
|
|
2f6bac |
@command{gnome-terminal}) be encoded with the same value you specified
|
|
|
2f6bac |
inside the repository documentation manual. Otherwise, special
|
|
|
2f6bac |
characters may not look as expected. Using Texinfo special way of
|
|
|
2f6bac |
accentuation is also required for @command{texi2html} command to
|
|
|
2f6bac |
transform special characters to HTML entities (e.g., @samp{á},
|
|
|
2f6bac |
@samp{ñ}, etc.). In the Pdf output, special characters are
|
|
|
2f6bac |
printed well most of times with some exceptions (e.g., the @samp{@@'i}
|
|
|
2f6bac |
don't replaces the dot over the letter with the accentuation, but put
|
|
|
2f6bac |
the accentuation over it.).
|
|
|
561a00 |
|
|
|
7e4b2b |
@quotation
|
|
|
7e4b2b |
@strong{Note} Using other codifications but UTF-8 in the terminal
|
|
|
7e4b2b |
might be not convenient in some situations. Prevent yourself from
|
|
|
7e4b2b |
using Texinfo special way of accentuation and the
|
|
|
7e4b2b |
@samp{@@documentencoding} directive when you be writing documentation
|
|
|
3d2104 |
entries through @code{help} functionality. This will hide special
|
|
|
3d2104 |
characters in Pdf output and, in XHTML output no entity will be
|
|
|
765349 |
translated. However, this configuration will let you to read special
|
|
|
3d2104 |
characters from Info files in UTF-8 terminals.
|
|
|
7803e6 |
@end quotation
|
|
|
7e4b2b |
|
|
|
7e4b2b |
Notice that, UTF-8 is the default character codification used by the
|
|
|
7e4b2b |
terminal inside The CentOS Distribution. This is the terminal
|
|
|
7e4b2b |
configuration we use for executing functionalities of
|
|
|
7e4b2b |
@command{centos-art.sh} script. If one of these functionalities
|
|
|
7e4b2b |
returns an error, the @command{centos-art.sh} script will suggest to
|
|
|
7e4b2b |
you executing a @code{help} command to know more about why the error
|
|
|
7e4b2b |
happend. This @code{help} command will read the information from an
|
|
|
7e4b2b |
Info file. If the Info file is codified to be read in an encoding
|
|
|
7e4b2b |
different to the one the terminal we are performing the action is set,
|
|
|
7e4b2b |
special characters will be printed wrongly; if printed at all. In this
|
|
|
7e4b2b |
situation it would be required to change the terminal codification to
|
|
|
4c2db8 |
that one set in the Info file, which might be something not desirable.
|
|
|
7e4b2b |
|
|
|
558340 |
Notice also that, the main purpose of using Texinfo as documentation
|
|
|
558340 |
backend to write documentation related to each repository directory,
|
|
|
558340 |
is the possibility it provides of producing Info files as output. This
|
|
|
60c668 |
posibility is used by @command{centos-art.sh} script to build internal
|
|
|
60c668 |
references where documentation can be found when errors happen. It
|
|
|
f5e1f1 |
lets users to type a command immediatly after errors to know more
|
|
|
f5e1f1 |
about them, once they happen. It is about creating a direct connection
|
|
|
f5e1f1 |
between the @command{centos-art.sh} script and the conceptual ideas
|
|
|
f5e1f1 |
behind it.
|
|
|
7e4b2b |
|
|
|
b32b45 |
@subheading Examples
|
|
|
b32b45 |
|
|
|
b32b45 |
@table @command
|
|
|
b32b45 |
@item centos-art help --edit trunk/Identity
|
|
|
b32b45 |
|
|
|
b32b45 |
This command edits the documentation entry related to
|
|
|
b32b45 |
@file{trunk/Identity} directory.
|
|
|
b32b45 |
|
|
|
b32b45 |
@item centos-art help --read trunk/Identity
|
|
|
b32b45 |
|
|
|
b32b45 |
This command reads the doumentation entry related to
|
|
|
b32b45 |
@file{trunk/Identity} directory in info format.
|
|
|
b32b45 |
|
|
|
b32b45 |
@end table
|
|
|
b32b45 |
|
|
|
b32b45 |
@subheading Author
|
|
|
b32b45 |
|
|
|
b32b45 |
Written by Alain Reguera Delgado.
|
|
|
b32b45 |
|
|
|
b32b45 |
@subheading Reporting bugs
|
|
|
b32b45 |
|
|
|
b32b45 |
Report bugs to @email{centos-artwork@@centos.org} mailing list.
|
|
|
b32b45 |
|
|
|
b32b45 |
@subheading Copyright
|
|
|
b32b45 |
|
|
|
b32b45 |
Copyright @copyright{} 2009, 2010, 2011 The CentOS Project.
|
|
|
b32b45 |
|
|
|
b32b45 |
This is free software. You may redistribute copies of it under the
|
|
|
b32b45 |
terms of the @ref{GNU General Public License}. There is NO WARRANTY,
|
|
|
b32b45 |
to the extent permitted by law.
|
|
|
b32b45 |
|
|
|
b32b45 |
@subheading See also
|
|
|
b32b45 |
|
|
|
b32b45 |
@itemize
|
|
|
b32b45 |
@item @ref{Directories trunk Scripts Functions}
|
|
|
b32b45 |
@item @ref{Directories trunk Scripts}
|
|
|
b32b45 |
@item @ref{Directories trunk}
|
|
|
b32b45 |
@end itemize
|