<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>

        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>

        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 

        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 

        linkend="scripts-bash-help-supportedformats" />. 

    </para>

    <title>Documentation formats</title>

    <tgroup cols="3" align="left">

        <row>

            <entry>Keyword</entry>

            <entry>Description</entry>

            <entry>Supported</entry>

        </row>

        <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>

    </tgroup>

    </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 

        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>

    <refsection id="scripts-bash-help-description-create">

    <title>Creating Document Structures</title>

    <para>

        To create new documentation manuals inside &TCAR; you use the

        <option>--edit</option>. This option edits existent manuals or

        creates new ones. For example, consider you need to create a

        documentation manual in texinfo format to describe different

        kind of animals.  This manual will be named <quote>My

        Zoo</quote>, use one chapter for each animal you want to

        describe and sections to cover the description itself. To

        create such documentation manual, run the following command:

    </para>

    <cmdsynopsis>

    <command>centos-art help --edit --format="texinfo" "my-zoo:::"</command>

    </cmdsynopsis>

    <para>

        In case such documentation manual doesn't exist in the

        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/My-zoo/en_US/my-zoo.texinfo

Do you want to create it now? [yes/no]: yes

------------------------------------------------------------------

Enter manual's title: My Zoo

Enter manual's subtitle: Puppet reference

Enter manual's abstract: This manual describes each puppet at home.

------------------------------------------------------------------

</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" "my-zoo::turtles:"</command>

    </cmdsynopsis>

<programlisting>

The following documentation chapter doesn't exist:

--> trunk/Documentation/Models/Texinfo/My-zoo/en_US/Turtles

Do you want to create it now? [yes/no]: yes

------------------------------------------------------------------

Enter chapter's title: Turtles

Creating        trunk/Documentation/Models/Texinfo/My-zoo/en_US/Turtles

Creating        trunk/Documentation/Models/Texinfo/My-zoo/en_US/Turtles/chapter-menu.texinfo

Creating        trunk/Documentation/Models/Texinfo/My-zoo/en_US/Turtles/chapter-nodes.texinfo

Creating        trunk/Documentation/Models/Texinfo/My-zoo/en_US/Turtles/chapter.texinfo

Updating        trunk/Documentation/Models/Texinfo/My-zoo/en_US/my-zoo-menu.texinfo

Updating        trunk/Documentation/Models/Texinfo/My-zoo/en_US/my-zoo-nodes.texinfo

Updating        trunk/Documentation/Models/Texinfo/My-zoo/en_US/Turtles/chapter.texinfo

Updating        trunk/Documentation/Manuals/Texinfo/My-zoo/en_US/my-zoo.info.bz2

Updating        trunk/Documentation/Manuals/Texinfo/My-zoo/en_US/my-zoo.xhtml.tar.bz2

Updating        trunk/Documentation/Manuals/Texinfo/My-zoo/en_US/my-zoo.xml

Updating        trunk/Documentation/Manuals/Texinfo/My-zoo/en_US/my-zoo.docbook

Updating        trunk/Documentation/Manuals/Texinfo/My-zoo/en_US/my-zoo.pdf

Updating        trunk/Documentation/Manuals/Texinfo/My-zoo/en_US/my-zoo.txt.bz2

</programlisting>

    </refsection>

    <refsection id="scripts-bash-help-description-edit">

    <title>Editing Document Structures</title>

    <para>

        To edit documentation entries, use the following command:

    </para>

    <cmdsynopsis>

    <command>centos-art help --edit --format="texinfo" "<replaceable>manual:part:chapter:section</replaceable>"</command>

    </cmdsynopsis>

    <para>

        ...

    </para>

    </refsection>

    <refsection id="scripts-bash-help-description-copy">

    <title>Copying Document Structures</title>

    <para>

        To copy 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-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>