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

    <title><function>help</function> &mdash; Standardize Documentation
    Tasks</title>

    <para>
        The <function>help</function> functionality is the interface
        the <command>centos-art.sh</command> script provides to
        control frequent documentation tasks (e.g., reading, editing,
        update output files, etc.) requied by specific documentation
        backends.  Documentation backends supported by
        <function>help</function> functionality are described in <xref
        linkend="doc"/>.
    </para>

    <screen>centos-art help [OPTIONS] [DIRECTORY]</screen>

    <para>
        The <varname>DIRECTORY</varname> parameter specifies the
        directory path, inside the working copy of &TCAR;, where the
        files you want to process the related documentation entry for.
        This paramter can be provided more than once in order to
        process more than one directory path in a single command
        execution or not provided at all.  When this parameter is not
        provided, the current directory path where the command was
        called from is used 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>--backend="NAME"</option></term>
    <listitem>
    <para>
        The <varname>NAME</varname> argument in this option specifies
        what backend to use when processing documentation. Possible
        arguments to this options are: <literal>texinfo</literal> or
        <literal>docbook</literal>. If this option is not provided,
        <literal>texinfo</literal> is used as default documentation
        backend.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--search="ID"</option></term>
    <listitem>
    <para>
        Go to node pointed by <varname>ID</varname> argument. When
        texinfo backend is used, this arguments refers the node you
        want to read documentation for. When docbook backend is used,
        this argument refers the section id you want to read
        documentation for.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--edit</option></term>
    <listitem>
    <para>
        Edit documentation entry related to path specified by
        <varname>DIRECTORY</varname> parameter.
    </para>
    <para>
        The <varname>DIRECTORY</varname> parameter must point to any
        directory inside the working copy.  When more than one
        <varname>DIRECTORY</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>DIRECTORY</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>DIRECTORY</varname> inside the working copy. It is
        possible to delete more than one documentation entry by
        specifying more <varname>DIRECTORY</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>