<refentry id="scripts-bash-help">
<refmeta>
<refentrytitle>help</refentrytitle>
<indexterm type="common-function">
<primary>Standardize constructions tasks inside &TCAR;</primary>
</indexterm>
</refmeta>
<refnamediv>
<refname>help</refname>
<refpurpose>Standardize documentation tasks inside &TCAR;.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>centos-art help</command>
<arg choice="opt">
<arg>--help</arg>
<arg>--quiet</arg>
<arg>--answer-yes</arg>
<arg>--sync-changes</arg>
<arg>--search="<replaceable>KEYWORD</replaceable>"</arg>
<arg>--edit</arg>
<arg>--read</arg>
<arg>--update</arg>
<arg>--copy</arg>
<arg>--delete</arg>
<arg>--rename</arg>
</arg>
<group choice="req">
<arg rep="repeat"><replaceable>MANUAL</replaceable>:<replaceable>PART</replaceable>:<replaceable>CHAPTER</replaceable>:<replaceable>SECTION</replaceable></arg>
<arg rep="repeat"><replaceable>LOCATION</replaceable></arg>
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsection id="scripts-bash-help-description">
<title>Description</title>
<para>
The <function>help</function> functionality exists to create
and maintain documentation manuals inside &TCAR;. The
documentation structure and format implemented by
<function>help</function> functionality are described in
<xref linkend="manuals-production-identifying-structure" />
and <xref linkend="manuals-format-texinfo" />, respectively.
</para>
<refsection id="scripts-bash-help-description-docentry">
<title>Documentation Entries</title>
<para>
The documentation entry identifies the specific file you want
to work with inside a documentation manual. The help
functionality recognizes documentation entries in the
following two formats:
</para>
<variablelist>
<varlistentry>
<term>Path style</term>
<listitem>
<para>
This format uses paths to represent the documentation entries
you want to work with. This format assumes you are using the
first path component as chapter and the rest of the path as
section identifier both inside <quote>tcar-fs</quote>
documentation manual as parent documentation structure. The
field related to the part sectioning structure in the
documentation entry (the second field) is assumed empty, as
well. For example, if you want to document the directory
<quote><filename
class="directory">trunk/Scripts/Bash/Functions/Help</filename></quote>,
then you can do it with the following command:
</para>
<cmdsynopsis>
<command>centos-art help --edit trunk/Scripts/Bash/Functions/Help</command>
</cmdsynopsis>
</listitem>
</varlistentry>
<varlistentry>
<term>Colon style</term>
<listitem>
<para>
This format uses colons to represent the documentation entries
you want to work with. In this format, the whole documentation
entry is divided in fields using colon as separator character.
Documentation entries written this way use each field to
specify manual, part, chapter and section identifiers (in this
order). The section identifier can use a path style or hyphen
style to separate
components. For example, if you want to document the directory
<quote><filename
class="directory">trunk/Scripts/Bash/Functions/Help</filename></quote>,
then you can do it with any of the following commands:
</para>
<cmdsynopsis>
<command>centos-art help --edit tcar-fs::trunk:Scripts/Bash/Functions/Help</command>
<command>centos-art help --edit tcar-fs::trunk:scripts-bash-functions-help</command>
</cmdsynopsis>
<para>
The documentation manual name specified in the first field of
a colon style documentation entry, must match the name the
name of the directory where the documentation manual is stored
in. By default documentation manuals are written in
trunk/Documentation/Models/Texinfo or
trunk/Documentation/Models/Docbook directories, based on
whether they are written in Texinfo or Docbook documentation
format.
</para>
<para>
The match relation between the manual name you provide in the
documentation entry and the related directory name inside
&TCAR; is case insensitive. The same is true for all other
documentation entry fields.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
From these documentation entry formats, the colon style
provides more flexibility than path style does. You can use
documentation entries written in colon style to create and
maintain different documentation manuals, including the
<quote>tcar-fs</quote> documentation manual. This is something
you cannot do with documentation entries written in path style
because they confine all documentation actions to
<quote>tcar-fs</quote> documentation manual.
</para>
</refsection>
<refsection id="scripts-bash-help-description-formats">
<title>Supported Documentation Formats</title>
<para>
The <function>help</function> functionality provides support
for the following documentation formats:
</para>
<itemizedlist>
<listitem>
<para>
Texinfo (See <xref linkend="manuals-format-texinfo"/>)
</para>
</listitem>
</itemizedlist>
</refsection>
<refsection id="scripts-bash-help-description-create">
<title>New Document Structures</title>
<para>
To create new documentation manuals inside &TCAR; use the
following command:
</para>
<cmdsynopsis>
<command>centos-art help --edit "<replaceable>manual-name</replaceable>"</command>
</cmdsynopsis>
<para>
The first time you execute this command, you will be prompted
to enter manual specific information like document format,
document title, document subtitle, document author, etc. Once
this information has been collected the
<function>help</function> functionality performs some
repository verifications and creates the manual source files
inside the manual's directory name you specified as
<replaceable>manual-name</replaceable>.
</para>
<para>
When you create new documentation manuals, take care of the
locale information you are currently using. This information
is generally set in the <envar>LANG</envar> environment
variable and is used by the <function>help</function>
functionality of <command>centos-art.sh</command> script to
define the language of new documentation manual and the
document template used to build it, as well.
</para>
<para>
Once the documentation structure has been created this way,
the recently created documentation manual is ready to receive
new chapters and sections.
</para>
</refsection>
<refsection id="scripts-bash-help-description-edit">
<title>Editing Document Structures</title>
<cmdsynopsis>
<command>centos-art help --edit "tcar-fs::trunk"</command>
</cmdsynopsis>
<para>
This command edits the <quote>trunk</quote> chapter
documentation entry. Here is where you can define the chapter
introduction. This very same procedure is used to create
<quote>branches</quote> and <quote>tags</quote> chapters, just
be sure to change the chapter field accordingly.
</para>
<para>
If the related manual or chapter itself don't exist in the
documentation structure, centos-art.sh script creates them in
their respective hierarchical order (i.e., the manual
structure first, and the chapter structure later).
</para>
<cmdsynopsis>
<command>centos-art help --edit "tcar-fs::trunk:Identity"</command>
</cmdsynopsis>
<para>
This command edits the <quote>trunk/Identity</quote>
documentation entry inside <quote>The CentOS Artwork
Repository File System</quote> documentation manual.
</para>
<para>
When you edit documentation for a directory which related
chapter doesn't exist, centos-art.sh script creates the
related chapter first and then proceed to create the related
documentaiton entry.
</para>
<para>
In order to document deeper directory levels, you need to
refer the directory you want to document by using a path-style
or a hyphen-style format as documentation entry. For example,
to edit the documentation related to the <quote><filename
class="directory">trunk/Identity/Models/Themes</filename></quote>
directory, you can use any of the following documentation
entries:
</para>
<itemizedlist>
<listitem>
<para>
<literal>tcar-fs::trunk:identity-models-themes</literal>
</para>
</listitem>
<listitem>
<para>
<literal>tcar-fs::trunk:Identity/Models/Themes</literal>
</para>
</listitem>
<listitem>
<para>
<literal>trunk/Identity/Models/Themes</literal>
</para>
</listitem>
</itemizedlist>
</refsection>
<refsection id="scripts-bash-help-description-copy">
<title>Copying Document Structure</title>
<para>
...
</para>
</refsection>
<refsection id="scripts-bash-help-description-delete">
<title>Deleting Document Structure</title>
<para>
...
</para>
</refsection>
<refsection id="scripts-bash-help-description-rename">
<title>Renaming Document Structure</title>
<para>
...
</para>
</refsection>
<refsection id="scripts-bash-help-description-update">
<title>Updating Document Structure</title>
<para>
...
</para>
</refsection>
</refsection>
<refsection id="scripts-bash-help-options">
<title>Options</title>
<para>
The <command>centos-art help</command> command accepts common
options described in <xref
linkend="scripts-bash-cli-commonoptions" /> and the following
specific options:
</para>
<variablelist>
<varlistentry>
<term><option>--answer-yes</option></term>
<listitem>
<para>
Assume <emphasis>yes</emphasis> to all confirmation requests.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--sync-changes</option></term>
<listitem>
<para>
Synchronizes available changes between the working copy and
the central repository.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--search="KEYWORD"</option></term>
<listitem>
<para>
This option looks for <varname>KEYWORD</varname> inside the
manual specified in the documentation entry and display
related information you to read.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--edit</option></term>
<listitem>
<para>
Edit documentation entry related to path specified by
<varname>DOCENTRY</varname> parameter.
</para>
<para>
The <varname>DOCENTRY</varname> parameter must point to any
directory inside the working copy. When more than one
<varname>DOCENTRY</varname> are passed as non-option
arguments to the <command>centos-art.sh</command> 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 <envar>EDITOR</envar>
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.).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--read</option></term>
<listitem>
<para>
Read documentation entry specified by
<varname>DOCENTRY</varname> path. This option is used
internally by <command>centos-art.sh</command> script to refer
documentation based on errors, so you can know more about them
and the causes that could have provoked them.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--update</option></term>
<listitem>
<para>
Update output files rexporting them from the specified backend
source files.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--copy</option></term>
<listitem>
<para>
Duplicate documentation entries inside the working copy.
</para>
<para>
When documentation entries are copied, it is required to pass
two non-option parameters in the command-line. The first
non-option parameter 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--delete</option></term>
<listitem>
<para>
Delete documentation entries specified by
<varname>DOCENTRY</varname> inside the working copy. It is
possible to delete more than one documentation entry by
specifying more <varname>DOCENTRY</varname> parameters in the
command-line.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--rename</option></term>
<listitem>
<para>
Rename documentation entries inside the working copy.
</para>
<para>
When documentation entries are renamed, it is required to pass
only two non-option parameters to the command-line. The first
non-option parameter 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.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
When documentation entries are removed (e.g., through
<option>--delete</option> or <option>--rename</option>
options), the <function>help</function> functionality takes
care of updating nodes, menus and cross refentrys related to
documentation entries in order to keep the manual structure in
a consistent state.
</para>
</refsection>
<refsection id="scripts-bash-help-examples">
<title>Examples</title>
<para>
None.
</para>
</refsection>
<refsection id="scripts-bash-help-bugs">
<title>Bugs</title>
<para>
...
</para>
</refsection>
<refsection id="scripts-bash-help-authors">
<title>Authors</title>
<para>
The following people have worked in this functionality:
</para>
<itemizedlist>
<listitem>
<para>
Alain Reguera Delgado <<ulink url="mailto:alain.reguera@gmail.com">alain.reguera@gmail.com</ulink>>, =COPYRIGHT_YEAR_LIST=
</para>
</listitem>
</itemizedlist>
</refsection>
<refsection id="scripts-bash-help-licence">
<title>License</title>
<para>
Copyright © =COPYRIGHT_YEAR_LIST= The CentOS Project
</para>
<para>
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
</para>
<para>
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more details.
</para>
<para>
You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
USA.
</para>
</refsection>
</refentry>