Blame Manuals/TCAR-UG/Docbook/Scripts/Bash/help.docbook

e68d9f
<sect1 id="scripts-bash-help">
e68d9f
e68d9f
    <title>The <function>help</function> functionality</title>
e68d9f
e68d9f
    <para>
e68d9f
        The <function>help</function> functionality is the interface
e68d9f
        the <command>centos-art.sh</command> script provides to
e68d9f
        control frequent documentation tasks (e.g., reading, editing,
e68d9f
        update output files, etc.) requied by specific documentation
e68d9f
        backends.  Documentation backends supported by
e68d9f
        <function>help</function> functionality are described in 
933061
        linkend="doc"/>.
e68d9f
    </para>
e68d9f
e68d9f
    <simplesect>
e68d9f
e68d9f
    <title>Synopsis</title>
e68d9f
e68d9f
        <para>
e68d9f
            <userinput>centos-art help [OPTIONS] path/to/dir …</userinput>
e68d9f
        </para>
e68d9f
e68d9f
        <para>
e68d9f
            The <parameter>path/to/dir</parameter> parameter specifies
e68d9f
            the directory structure inside the working copy of The
e68d9f
            CentOS Artwork Repository you want to process the related
e68d9f
            documentation entry for. More than one directory structure
e68d9f
            can be passed as <parameter>path/to/dir</parameter>
e68d9f
            parameter.
e68d9f
        </para>
e68d9f
e68d9f
        <para>
e68d9f
            The <function>help</function> functionality accepts the
e68d9f
            following options:
e68d9f
e68d9f
            <variablelist>
e68d9f
e68d9f
            <varlistentry>
e68d9f
            <term><option>--quiet</option></term>
e68d9f
            <listitem>
e68d9f
            <para>
e68d9f
                Supress all output messages except error messages.
e68d9f
                When this option is passed, all confirmation requests
e68d9f
                are supressed as well and a possitive answer is
e68d9f
                assumed for them, just as if the
e68d9f
                <option>--answer-yes</option> option had been
e68d9f
                provided.
e68d9f
            </para>
e68d9f
            </listitem>
e68d9f
            </varlistentry>
e68d9f
e68d9f
            <varlistentry>
e68d9f
            <term><option>--answer-yes</option></term>
e68d9f
            <listitem>
e68d9f
            <para>
e68d9f
                Assume <emphasis>yes</emphasis> to all confirmation requests.
e68d9f
            </para>
e68d9f
            </listitem>
e68d9f
            </varlistentry>
e68d9f
e68d9f
            <varlistentry>
e68d9f
            <term><option>--dont-commit-changes</option></term>
e68d9f
            <listitem>
e68d9f
            <para>
e68d9f
                Supress all commit and update actions realized over
e68d9f
                files, before and after the action itself had took
e68d9f
                place over files in the working copy.
e68d9f
            </para>
e68d9f
            </listitem>
e68d9f
            </varlistentry>
e68d9f
e68d9f
            <varlistentry>
e68d9f
            <term><option>--backend="STRING"</option></term>
e68d9f
            <listitem>
e68d9f
            <para>
e68d9f
                Specify <replaceable>STRING</replaceable> as
e68d9f
                default documentation backend to use. Possible
e68d9f
                arguments to this options are:
e68d9f
                <literal>texinfo</literal>
e68d9f
                or <literal>docbook</literal>. If this option is not
e68d9f
                provided, <literal>texinfo</literal> is used as
e68d9f
                default documentation backend.
e68d9f
            </para>
e68d9f
            </listitem>
e68d9f
            </varlistentry>
e68d9f
e68d9f
            <varlistentry>
e68d9f
            <term><option>--search="STRING"</option></term>
e68d9f
            <listitem>
e68d9f
            <para>
e68d9f
                Go to node pointed by index entry <literal>STRING</literal>.
e68d9f
            </para>
e68d9f
            </listitem>
e68d9f
            </varlistentry>
e68d9f
e68d9f
            <varlistentry>
e68d9f
            <term><option>--edit</option></term>
e68d9f
            <listitem>
e68d9f
            <para>
e68d9f
                Edit documentation entry related to path specified by
e68d9f
                <parameter>path/to/dir</parameter> parameter.
e68d9f
            </para>
e68d9f
            <para>
e68d9f
                The <parameter>path/to/dir</parameter> parameter must
e68d9f
                point to any directory inside the repository.  When
e68d9f
                more than one <parameter>path/to/dir</parameter> are
e68d9f
                passed as non-option arguments to the
e68d9f
                <command>centos-art.sh</command> script command-line,
e68d9f
                they are queued for further edition.  The edition
e68d9f
                itself takes place through your default text editor
e68d9f
                (e.g., the one you specified in the
e68d9f
                <envar>EDITOR</envar> environment variable) and the
e68d9f
                text editor opens one file at time (i.e., the queue of
e68d9f
                files to edit is not loaded in the text editor.).
e68d9f
            </para>
e68d9f
            </listitem>
e68d9f
            </varlistentry>
e68d9f
e68d9f
            <varlistentry>
e68d9f
            <term><option>--read</option></term>
e68d9f
            <listitem>
e68d9f
            <para>
e68d9f
                Read documentation entry specified by
e68d9f
                <parameter>path/to/dir</parameter> path.  This option
e68d9f
                is used internally by <command>centos-art.sh</command>
e68d9f
                script to print out the reference you can follow to
e68d9f
                know more about an error message.
e68d9f
            </para>
e68d9f
            </listitem>
e68d9f
            </varlistentry>
e68d9f
e68d9f
            <varlistentry>
e68d9f
            <term><option>--update</option></term>
e68d9f
            <listitem>
e68d9f
            <para>
e68d9f
                Update output files rexporting them from the specified
e68d9f
                backend source files.
e68d9f
            </para>
e68d9f
            </listitem>
e68d9f
            </varlistentry>
e68d9f
e68d9f
            <varlistentry>
e68d9f
            <term><option>--copy</option></term>
e68d9f
            <listitem>
e68d9f
            <para>
e68d9f
                Duplicate documentation entries inside the working
e68d9f
                copy of the repository.
e68d9f
            </para>
e68d9f
            <para>
e68d9f
                When documentation entries are copied, it is required
e68d9f
                to pass two non-option parameters in the command-line.
e68d9f
                The first non-option parameter is considered the
e68d9f
                source location and the second one the target
e68d9f
                location.  Both source location and target location
e68d9f
                must point to a directory under the working copy.
e68d9f
            </para>
e68d9f
            </listitem>
e68d9f
            </varlistentry>
e68d9f
e68d9f
            <varlistentry>
e68d9f
            <term><option>--delete</option></term>
e68d9f
            <listitem>
e68d9f
            <para>
e68d9f
                Delete documentation entries specified by
e68d9f
                <parameter>path/to/dir</parameter> inside the working
e68d9f
                copy. It is possible to delete more than one
e68d9f
                documentation entry by specifying more
e68d9f
                <parameter>path/to/dir</parameter> parameters in the
e68d9f
                command-line.
e68d9f
            </para>
e68d9f
            </listitem>
e68d9f
            </varlistentry>
e68d9f
e68d9f
            <varlistentry>
e68d9f
            <term><option>--rename</option></term>
e68d9f
            <listitem>
e68d9f
            <para>
e68d9f
                Rename documentation entries inside the working copy.
e68d9f
            </para>
e68d9f
            <para>
e68d9f
                When documentation entries are renamed, it is required
e68d9f
                to pass only two non-option parameters to the
e68d9f
                command-line. The first non-option parameter is
e68d9f
                considered the source location and the second one the
e68d9f
                target location.  Both source location and target
e68d9f
                location must point to a directory under the working
e68d9f
                copy.
e68d9f
            </para>
e68d9f
            </listitem>
e68d9f
            </varlistentry>
e68d9f
e68d9f
            </variablelist>
e68d9f
        </para>
e68d9f
e68d9f
        <para>
e68d9f
            When documentation entries are removed (e.g., through
e68d9f
            <option>--delete</option> or <option>--rename</option>
e68d9f
            options), the <function>help</function> functionality
e68d9f
            takes care of updating nodes, menus and cross references
e68d9f
            related to documentation entries in order to keep the
e68d9f
            manual structure in a correct state.
e68d9f
        </para>
e68d9f
e68d9f
    </simplesect>
e68d9f
e68d9f
    <simplesect>
e68d9f
e68d9f
    <title>Examples</title>
e68d9f
e68d9f
    <para>
e68d9f
        <variablelist> 
e68d9f
        <varlistentry>
e68d9f
        <term><userinput>centos-art help --edit trunk/Identity</userinput></term>
e68d9f
        <listitem>
e68d9f
        <para>
e68d9f
            This command edits the documentation entry related to
e68d9f
            <filename class="directory">trunk/Identity</filename>
e68d9f
            directory inside the repository working copy.
e68d9f
        </para>
e68d9f
        </listitem>
e68d9f
        </varlistentry>
e68d9f
e68d9f
        <varlistentry>
e68d9f
        <term><userinput>centos-art help --read trunk/Identity</userinput></term>
e68d9f
        <listitem>
e68d9f
        <para>
e68d9f
            This command reads the documentation entry related to
e68d9f
            <filename class="directory">trunk/Identity</filename>
e68d9f
            directory inside the repository working copy.
e68d9f
        </para>
e68d9f
        </listitem>
e68d9f
        </varlistentry>
e68d9f
e68d9f
        </variablelist> 
e68d9f
    </para>
e68d9f
    </simplesect>
e68d9f
e68d9f
    <simplesect>
e68d9f
e68d9f
        <title>Author</title>
e68d9f
e68d9f
        <para>
e68d9f
            Written by Alain Reguera Delgado.
e68d9f
        </para>
e68d9f
e68d9f
    </simplesect>
e68d9f
e68d9f
    <simplesect>
e68d9f
        <title>Reporting bugs</title>
e68d9f
        <para>
e68d9f
            Report bugs to 
e68d9f
            url="mailto:centos-artwork@centos.org">centos-artwork@centos.org</ulink>
e68d9f
            mailing list.
e68d9f
        </para>
e68d9f
    </simplesect>
e68d9f
e68d9f
    <simplesect>
e68d9f
        <title>Copyright</title>
e68d9f
        <para>
e68d9f
            Copyright © 2009, 2010, 2011 The CentOS Artwork SIG.
e68d9f
        </para>
e68d9f
        <para>
e68d9f
            This  is free software.  You may redistribute copies of it
e68d9f
            under the terms of the <xref linkend="licenses-gpl"/>.
e68d9f
            There is NO WARRANTY, to the extent permitted by law.
e68d9f
        </para>
e68d9f
    </simplesect>
e68d9f
e68d9f
</sect1>