<sect1 id="scripts-bash-help">

    <title>Standardizing Documentation Tasks</title>

    <para>

        The <function>help</function> functionality is the interface

        the <command>centos-art.sh</command> script provides to

        standardize frequent documentation tasks, based on specific

        documentation formats, as described in 

        linkend="manuals-formats"/>.

    </para>

    <para>

        <command>centos-art help [OPTIONS] [DOCENTRY]</command>

    </para>

    <para>

        The <varname>DOCENTRY</varname> parameter specifies the

        documentation entry you want to process.  It can be provided

        one or more times in the form

        MANUAL:PART:CHAPTER:SECTION or

        MANUAL::CHAPTER:SECTION based on whether the

        manual documentation backend you are using supports

        structuring through parts or not. When

        <varname>DOCENTRY</varname> parameter is not provided, the

        <quote>Repository File System</quote> documentation manual is

        used as default value.

    </para>

    <para>

        To determine the documentation format to use, when new

        documentation manuals are created and no configuration file is

        available, the <function>help</function> functionality request

        you to enter one of the supported documentation formats and

        then, uses it to create the documentation manual. Once the

        documentation manual is created, the document configuration

        file is available inside the manual directory structure and

        used to retrive the document format information, instead.

    </para>

    <para>

        The <function>help</function> functionality accepts the

        following options:

    </para>

    <variablelist>

    <varlistentry>

    <term><option>--quiet</option></term>

    <listitem>

    <para>

        Supress all output messages except error messages.  When this

        option is passed, all confirmation requests are supressed and

        a possitive answer is assumed for them, just as if the

        <option>--answer-yes</option> option would have been provided.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--answer-yes</option></term>

    <listitem>

    <para>

        Assume <emphasis>yes</emphasis> to all confirmation requests.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--dont-commit-changes</option></term>

    <listitem>

    <para>

        Supress all commit and update actions realized over files,

        before and after the action itself had took place over files

        in the working copy.

    </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 references related to

        documentation entries in order to keep the manual structure in

        a consistent state.

    </para>

</sect1>