<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>--format="<replaceable>KEYWORD</replaceable>"</arg>
<arg>--search="<replaceable>KEYWORD</replaceable>"</arg>
<arg>--edit</arg>
<arg>--read</arg>
<arg>--update-output</arg>
<arg>--update-structure</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;.
</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 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>
<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>--format="<replaceable>KEYWORD</replaceable>"</option></term>
<listitem>
<para>
Specifies the format of documentation entry source file. This
information is used as reference to build the absolute path of
documentation entry, so you always have to provide it in order
to reach the documentation entry you want to work with.
Possible values for this option are shown in <xref
linkend="scripts-bash-help-supportedformats" />.
</para>
<table id="scripts-bash-help-supportedformats">
<title>Documentation formats</title>
<tgroup cols="3" align="left">
<thead>
<row>
<entry>Keyword</entry>
<entry>Description</entry>
<entry>Supported</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>texinfo</literal></entry>
<entry><xref linkend="manuals-formats-texinfo"/></entry>
<entry>Yes</entry>
</row>
<row>
<entry><literal>docbook</literal></entry>
<entry><xref linkend="manuals-formats-docbook"/></entry>
<entry>No</entry>
</row>
<row>
<entry><literal>latex</literal></entry>
<entry><xref linkend="manuals-formats-latex"/></entry>
<entry>No</entry>
</row>
<row>
<entry><literal>linuxdoc</literal></entry>
<entry>...</entry>
<entry>No</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--search="<replaceable>KEYWORD</replaceable>"</option></term>
<listitem>
<para>
Looks for documentation entries that match the
<replaceable>KEYWORD</replaceable> specified as value and
display them one by one in the order they were found. The way
each documentation entry is presented to you depends on the
documentation format the related documentation manual was
written on.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--edit</option></term>
<listitem>
<para>
Edit the documentation entry provided as argument. The
edition itself takes place through your default text editor
(e.g., the one you specified in the <envar>EDITOR</envar>
environment variable) one file at a time (i.e., the queue of
files to edit is not loaded in the text editor.).
</para>
<para>
When parent components inside documentation entries doesn't
exist (e.g., you try to create a section for a documentation
manual that doesn't exist), the <function>help</function>
functionality will create all documentation parent structures
considering the documentation format constraints and the
following document structure hierarchy order: documentation
<quote>manual</quote> first, <quote>parts</quote> second,
<quote>chapters</quote> third and <quote>sections</quote>
lastly.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--read</option></term>
<listitem>
<para>
Read the documentation entry provided as argument. 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-output</option></term>
<listitem>
<para>
Update output files rexporting them from the specified backend
source files.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--update-structure</option></term>
<listitem>
<para>
Update document structure (e.g., cross references, menus,
nodes, etc.). This option should be used whenever a document
structure changes (e.g., when documentation entries are added,
copied, renamed, deleted, etc.). This option grantees the
document integrity and should be run before the
<option>--update-output</option> option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--copy</option></term>
<listitem>
<para>
Duplicate documentation entries inside the working copy using
version control.
</para>
<para>
When you duplicate documentation entries through this option,
you should pass only two documentation entries in the command
line. The first one is considered the source location and
should point to a file under version control inside the
working copy. The second one is considered the target location
and should point either to the same structural level the
source points to or a direct parent level based on source
location, as described below.
</para>
<variablelist>
<varlistentry>
<term>
"<replaceable>manual:part:chapter:section-1</replaceable>" "<replaceable>manual:part:chapter:section-2</replaceable>"</term>
<listitem>
<para>
Duplicates <replaceable>section-1</replaceable> as
<replaceable>section-2</replaceable> inside the same
<replaceable>chapter</replaceable>,
<replaceable>part</replaceable> and
<replaceable>manual</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
"<replaceable>manual:part:chapter-1:</replaceable>" "<replaceable>manual:part:chapter-2:</replaceable>"</term>
<listitem>
<para>
Duplicates <replaceable>chapter-1</replaceable> as
<replaceable>chapter-2</replaceable> inside the same
<replaceable>part</replaceable> and
<replaceable>manual</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
"<replaceable>manual:part-1::</replaceable>" "<replaceable>manual:part-2::</replaceable>"</term>
<listitem>
<para>
Duplicates <replaceable>part-1</replaceable> as
<replaceable>part-2</replaceable> inside the same
<replaceable>manual</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
"<replaceable>manual-1:::</replaceable>" "<replaceable>manual-2:::</replaceable>"</term>
<listitem>
<para>
Duplicates <replaceable>manual-1</replaceable> as
<replaceable>manual-2</replaceable> inside <filename
class="directory">trunk/Documentation/Models/${FLAG_FORMAT}/</filename>
directory, where ${FLAG_FORMAT} is the name of the format
passed as option with the first letter in uppercase and the
rest in lowercase.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
When you copy documentation entries through this option, all
structuring sections inside the one copied will be also
copied. For example, if you copy a documentation manual that
is made of parts, chapters and sections, the duplicated manual
will contain all those parts, chapters and sections, as well.
The same is true for lower sectioning structures. Thus, you
can be more specific in the documentation entry by reducing
the amount of content to duplicate.
</para>
<para>
When you copy documentation entries through this option, you
do it using documentation entries in the same structural level
only. This option doesn't support copying documentation
entries from differnet structural levels. For example, you
cannot copy one section to a chapter different from that the
source section belongs to. The same applies to chapters, and
parts.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--delete</option></term>
<listitem>
<para>
Delete documentation entries. It is possible to delete more
than one documentation entry by specifying several
documentation entries 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>
This section describes, using examples, the procedure you
should follow to manage documentation manuals through
<function>help</function> functionality inside &TCAR;. To
better understand the procedure to follow, it describes a
hypothetical documentation scenario and the related commands
and outputs you may go through in order to complete specific
documentation tasks successfully.
</para>
<refsection id="scripts-bash-help-description-create">
<title>Creating Document Structures</title>
<para>
To create new documentation manuals inside &TCAR; you need to
provide the <option>--edit</option> option and a documentation
entry in the form <quote><literal>manual:::</literal></quote>
to the <function>help</function> functionality.
</para>
<para>
For example, consider a scenario where you need to create a
documentation manual in texinfo format to describe different
maintenance tasks you need to realized in order to keep your
pets happy. We'll name such manual <quote>My Zoo</quote>. It
will use chapters to organize each different kind of pets you
have. Inside chapters, sections will have the pet's name as
their own name to describe each pet's requirements, schedules,
and so on. To create such documentation manual, run the
following command:
</para>
<cmdsynopsis>
<command>centos-art help --edit --format="texinfo" "myzoo:::"</command>
</cmdsynopsis>
<para>
In case such documentation manual doesn't exist in the
<filename
class="directory">trunk/Docuementation/Models/Texinfo/</filename>
directory, this command will produce the following output:
</para>
<programlisting>
The following documentation manual doesn't exist:
--> trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo.texinfo
Do you want to create it now? [yes/no]: yes
Enter manual's title: My Zoo
Enter manual's subtitle: Maintenance reference
Enter manual's abstract: This manual relates pets' maintenance tasks.
Creating trunk/Documentation/Models/Texinfo/MyZoo
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo.conf
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo-index.texinfo
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo-menu.texinfo
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo-nodes.texinfo
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo.texinfo
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Licenses/chapter-menu.texinfo
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Licenses/chapter-nodes.texinfo
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Licenses/chapter.texinfo
Updating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo.texinfo
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.info.bz2
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xhtml.tar.bz2
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xml
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.docbook
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.pdf
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.txt.bz2
</programlisting>
<para>
Once the documentation structure has been created this way,
the recently created documentation manual is ready to receive
new sectioning levels (e.g., parts, chapters, sections, etc.).
For example, to create a new chapter named
<quote>Turtles</quote> inside <quote>My Zoo</quote>
documentation manual, run the following command:
</para>
<cmdsynopsis>
<command>centos-art help --edit --format="texinfo" "myzoo::turtles:"</command>
</cmdsynopsis>
<programlisting>
The following documentation chapter doesn't exist:
--> trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles
Do you want to create it now? [yes/no]: yes
Enter chapter's title: Turtles
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/chapter-menu.texinfo
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/chapter-nodes.texinfo
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/chapter.texinfo
Updating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo-menu.texinfo
Updating trunk/Documentation/Models/Texinfo/MyZoo/en_US/myzoo-nodes.texinfo
Updating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/chapter.texinfo
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.info.bz2
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xhtml.tar.bz2
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xml
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.docbook
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.pdf
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.txt.bz2
</programlisting>
<para>
Once chapters have been created it is possible to create
sections inside them. For example, if you want to create a
section for describing the life of a turtle named Longneck,
run the following command:
</para>
<cmdsynopsis>
<command>centos-art help --edit --format="texinfo" "myzoo::turtles:longneck"</command>
</cmdsynopsis>
<programlisting>
The following documentation section doesn't exist:
--> trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/longneck.texinfo
Do you want to create it now? [yes/no]: yes
Creating trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/longneck.texinfo
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.info.bz2
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xhtml.tar.bz2
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xml
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.docbook
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.pdf
Updating trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.txt.bz2
</programlisting>
</refsection>
<refsection id="scripts-bash-help-description-edit">
<title>Editing Document Structures</title>
<para>
To edit documentation entries you can follow the same
procedure described above. Just keep in mind the following
rules:
</para>
<itemizedlist>
<listitem>
<para>
When the entry you want to edit already exist it will be
edited.
</para>
</listitem>
<listitem>
<para>
When the entry you want to edit doesn't exist it will be created
first and edited later.
</para>
</listitem>
</itemizedlist>
</refsection>
<refsection id="scripts-bash-help-description-copy">
<title>Copying Document Structures</title>
<para>
Consider a new turtle named Slowfeet has arrived to your home
and you want to duplicate Longneck's section for it (they both
are turtles and have similar requirements, squedules, etc.).
To copy documentation entries you use the
<option>--copy</option> option with two documentation entries,
where the first one is the source location and the second one
the target location. This need can be covered with the
following command:
</para>
<cmdsynopsis>
<command>centos-art help --copy --format="texinfo" "myzoo::turtles:longneck" "myzoo::turtles:slowfeet"</command>
</cmdsynopsis>
<programlisting>
------------------------------------------------------------------
Creating trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/slowfeet.texinfo
Updating trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/slowfeet.texinfo
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.info.bz2
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xhtml.tar.bz2
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xml
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.docbook
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.pdf
Updating trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.txt.bz2
</programlisting>
<warning>
<para>
In order to copy documentation entries successfully, the
source documentation entry must not contain any pending
change. Otherwise, the section won't be created and the script
will immediatly stop its execution with a <quote>The source
location has pending changes.</quote> error message.
</para>
</warning>
</refsection>
<refsection id="scripts-bash-help-description-delete">
<title>Deleting Document Structures</title>
<para>
To delete one documentation entry, use the following command:
</para>
<cmdsynopsis>
<command>centos-art help --delete --format="texinfo" "<replaceable>manual:part:chapter:section</replaceable>"</command>
</cmdsynopsis>
<para>
...
</para>
</refsection>
<refsection id="scripts-bash-help-description-rename">
<title>Renaming Document Structures</title>
<para>
To rename one documentation entry, use the following command:
</para>
<cmdsynopsis>
<command>centos-art help --copy --format="texinfo" "<replaceable>manual:part:chapter:section</replaceable>" "<replaceable>manual:part:chapter:section</replaceable>"</command>
</cmdsynopsis>
<para>
...
</para>
</refsection>
<refsection id="scripts-bash-help-description-updatestructure">
<title>Updating Document Structures</title>
<para>
To update the document structure of one manual, use the
following command:
</para>
<cmdsynopsis>
<command>centos-art help --update-structure --format="texinfo" "<replaceable>manual:part:chapter:section</replaceable>"</command>
</cmdsynopsis>
<para>
...
</para>
</refsection>
<refsection id="scripts-bash-help-description-updateoutput">
<title>Updating Document Final Outputs</title>
<para>
To update the document final outputs of one manual, use the
following command:
</para>
<cmdsynopsis>
<command>centos-art help --update-output --format="texinfo" "<replaceable>manual:::</replaceable>"</command>
</cmdsynopsis>
<para>
...
</para>
</refsection>
</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>