Blame Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/help.docbook

1c1364
<section id="scripts-bash-help">
e68d9f
541cb9
    <title>Standardizing Documentation Tasks</title>
e68d9f
e68d9f
    <para>
e68d9f
        The <function>help</function> functionality is the interface
e68d9f
        the <command>centos-art.sh</command> script provides to
ba86a3
        standardize frequent documentation tasks, based on specific
541cb9
        documentation formats, as described in 
541cb9
        linkend="manuals-formats"/>.
e68d9f
    </para>
e68d9f
1542c4
    <simplesect id="scripts-bash-help-syntax">
2b4826
    <title>Syntax</title>
2b4826
2b4826
    <screen>centos-art help [OPTIONS] [DOCENTRY]</screen>
89114c
d2638e
    <para>
ba86a3
        The <varname>DOCENTRY</varname> parameter specifies the
ba86a3
        documentation entry you want to process.  It can be provided
ba86a3
        one or more times in the form
ba86a3
        MANUAL:PART:CHAPTER:SECTION or
ba86a3
        MANUAL::CHAPTER:SECTION based on whether the
ba86a3
        manual documentation backend you are using supports
ba86a3
        structuring through parts or not. When
2b4826
        <varname>DOCENTRY</varname> parameter is not provided,
2b4826
        <quote>&TCAR; Repository File System</quote> documentation
2b4826
        manual is used as default value.
d2638e
    </para>
e68d9f
d2638e
    <para>
541cb9
        To determine the documentation format to use, when new
541cb9
        documentation manuals are created and no configuration file is
541cb9
        available, the <function>help</function> functionality request
541cb9
        you to enter one of the supported documentation formats and
541cb9
        then, uses it to create the documentation manual. Once the
541cb9
        documentation manual is created, the document configuration
541cb9
        file is available inside the manual directory structure and
541cb9
        used to retrive the document format information, instead.
541cb9
    </para>
1542c4
    </simplesect>
541cb9
1542c4
    <simplesect id="scripts-bash-help-options">
2b4826
    <title>Options</title>
541cb9
    <para>
d2638e
        The <function>help</function> functionality accepts the
d2638e
        following options:
d2638e
    </para>
e68d9f
d2638e
    <variablelist>
d2638e
    <varlistentry>
d2638e
    <term><option>--quiet</option></term>
d2638e
    <listitem>
d2638e
    <para>
d2638e
        Supress all output messages except error messages.  When this
89114c
        option is passed, all confirmation requests are supressed and
89114c
        a possitive answer is assumed for them, just as if the
89114c
        <option>--answer-yes</option> option would have been provided.
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
d2638e
    <term><option>--answer-yes</option></term>
d2638e
    <listitem>
d2638e
    <para>
d2638e
        Assume <emphasis>yes</emphasis> to all confirmation requests.
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
7f526e
    <term><option>--sync-changes</option></term>
d2638e
    <listitem>
d2638e
    <para>
7f526e
        Synchronizes available changes between the working copy and
7f526e
        the central repository.
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
ba86a3
    <term><option>--search="KEYWORD"</option></term>
d2638e
    <listitem>
d2638e
    <para>
ba86a3
        This option looks for <varname>KEYWORD</varname> inside the
ba86a3
        manual specified in the documentation entry and display
ba86a3
        related information you to read.
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
d2638e
    <term><option>--edit</option></term>
d2638e
    <listitem>
d2638e
    <para>
d2638e
        Edit documentation entry related to path specified by
ba86a3
        <varname>DOCENTRY</varname> parameter.
d2638e
    </para>
d2638e
    <para>
ba86a3
        The <varname>DOCENTRY</varname> parameter must point to any
89114c
        directory inside the working copy.  When more than one
ba86a3
        <varname>DOCENTRY</varname> are passed as non-option
d2638e
        arguments to the <command>centos-art.sh</command> script
d2638e
        command-line, they are queued for further edition.  The
d2638e
        edition itself takes place through your default text editor
d2638e
        (e.g., the one you specified in the <envar>EDITOR</envar>
d2638e
        environment variable) and the text editor opens one file at
d2638e
        time (i.e., the queue of files to edit is not loaded in the
d2638e
        text editor.).
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
d2638e
    <term><option>--read</option></term>
d2638e
    <listitem>
d2638e
    <para>
d2638e
        Read documentation entry specified by
ba86a3
        <varname>DOCENTRY</varname> path.  This option is used
541cb9
        internally by <command>centos-art.sh</command> script to refer
541cb9
        documentation based on errors, so you can know more about them
541cb9
        and the causes that could have provoked them.
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
d2638e
    <term><option>--update</option></term>
d2638e
    <listitem>
d2638e
    <para>
d2638e
        Update output files rexporting them from the specified backend
d2638e
        source files.
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
d2638e
    <term><option>--copy</option></term>
d2638e
    <listitem>
d2638e
    <para>
89114c
        Duplicate documentation entries inside the working copy.
d2638e
    </para>
d2638e
    <para>
d2638e
        When documentation entries are copied, it is required to pass
d2638e
        two non-option parameters in the command-line.  The first
d2638e
        non-option parameter is considered the source location and the
d2638e
        second one the target location.  Both source location and
d2638e
        target location must point to a directory under the working
d2638e
        copy.
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
d2638e
    <term><option>--delete</option></term>
d2638e
    <listitem>
d2638e
    <para>
d2638e
        Delete documentation entries specified by
ba86a3
        <varname>DOCENTRY</varname> inside the working copy. It is
89114c
        possible to delete more than one documentation entry by
ba86a3
        specifying more <varname>DOCENTRY</varname> parameters in the
89114c
        command-line.
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
d2638e
    <term><option>--rename</option></term>
d2638e
    <listitem>
d2638e
    <para>
d2638e
        Rename documentation entries inside the working copy.  
d2638e
    </para>
d2638e
    <para>
d2638e
        When documentation entries are renamed, it is required to pass
d2638e
        only two non-option parameters to the command-line. The first
d2638e
        non-option parameter is considered the source location and the
d2638e
        second one the target location.  Both source location and
d2638e
        target location must point to a directory under the working
d2638e
        copy.
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
d2638e
    </variablelist>
e68d9f
d2638e
    <para>
d2638e
        When documentation entries are removed (e.g., through
d2638e
        <option>--delete</option> or <option>--rename</option>
d2638e
        options), the <function>help</function> functionality takes
1c1364
        care of updating nodes, menus and cross sections related to
d2638e
        documentation entries in order to keep the manual structure in
89114c
        a consistent state.
d2638e
    </para>
1542c4
    </simplesect>
2b4826
1542c4
    <simplesect id="scripts-bash-help-description">
2b4826
    <title>Description</title>
2b4826
    <para>
2b4826
        ...
2b4826
    </para>
1542c4
    </simplesect>
2b4826
1542c4
    <simplesect id="script-bash-help-environment">
1542c4
    <title>Function Specific Environment</title>
2b4826
    <para>
2b4826
        ...
2b4826
    </para>
1542c4
    </simplesect>
2b4826
1542c4
    <simplesect id="scripts-bash-help-authors">
2b4826
    <title>Authors</title>
2b4826
    <para>
2b4826
        The following people have worked in the
2b4826
        <function>help</function> functionality:
2b4826
    </para>
2b4826
    <itemizedlist>
2b4826
    <listitem>
2b4826
    <para>
1542c4
        Alain Reguera Delgado <<ulink url="mailto:alain.reguera@gmail.com">alain.reguera@gmail.com</ulink>>, =COPYRIGHT_YEAR_LIST=
2b4826
    </para>
2b4826
    </listitem>
2b4826
    </itemizedlist>
1542c4
    </simplesect>
2b4826
1542c4
    <simplesect id="scripts-bash-help-licence">
2b4826
    <title>License</title>
1542c4
2b4826
    <para>
1542c4
        Copyright © =COPYRIGHT_YEAR_LIST= The CentOS Project
1542c4
    </para>
2b4826
 
1542c4
    <para>
1542c4
        This program is free software; you can redistribute it and/or
1542c4
        modify it under the terms of the GNU General Public License as
1542c4
        published by the Free Software Foundation; either version 2 of
1542c4
        the License, or (at your option) any later version.
1542c4
    </para>
2b4826
 
1542c4
    <para>
1542c4
        This program is distributed in the hope that it will be
1542c4
        useful, but WITHOUT ANY WARRANTY; without even the implied
1542c4
        warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
1542c4
        PURPOSE.  See the GNU General Public License for more details.
1542c4
    </para>
2b4826
 
1542c4
    <para>
1542c4
        You should have received a copy of the GNU General Public
1542c4
        License along with this program; if not, write to the Free
1542c4
        Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
1542c4
        USA.
2b4826
    </para>
1542c4
    </simplesect>
e68d9f
1c1364
</section>