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

    <title>Standardize 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 backends described in <xref linkend="doc"/>.
    </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
        <code>MANUAL:PART:CHAPTER:SECTION</code> or
        <code>MANUAL::CHAPTER:SECTION</code> 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>
        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 print
        out the reference you can follow to know more about an error
        message.
    </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>