Blob Blame History Raw
<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 <xref
        linkend="manuals-formats"/>.
    </para>

    <simplesect id="scripts-bash-help-syntax">
    <title>Syntax</title>

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

    <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,
        <quote>&TCAR; 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>
    </simplesect>

    <simplesect id="scripts-bash-help-options">
    <title>Options</title>
    <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>--sync-changes</option></term>
    <listitem>
    <para>
        Synchronizes available changes between the working copy and
        the central repository.
    </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>
    </simplesect>

    <simplesect id="scripts-bash-help-description">
    <title>Description</title>
    <para>
        ...
    </para>
    </simplesect>

    <simplesect id="script-bash-help-environment">
    <title>Function Specific Environment</title>
    <para>
        ...
    </para>
    </simplesect>

    <simplesect id="scripts-bash-help-authors">
    <title>Authors</title>
    <para>
        The following people have worked in the
        <function>help</function> functionality:
    </para>
    <itemizedlist>
    <listitem>
    <para>
        Alain Reguera Delgado &lt;<ulink url="mailto:alain.reguera@gmail.com">alain.reguera@gmail.com</ulink>&gt;, =COPYRIGHT_YEAR_LIST=
    </para>
    </listitem>
    </itemizedlist>
    </simplesect>

    <simplesect id="scripts-bash-help-licence">
    <title>License</title>

    <para>
        Copyright &copy; =COPYRIGHT_YEAR_LIST= The CentOS Project
    </para>
 
    <para>
        This program is free software; you can redistribute it and/or
        modify it under the terms of the GNU General Public License as
        published by the Free Software Foundation; either version 2 of
        the License, or (at your option) any later version.
    </para>
 
    <para>
        This program is distributed in the hope that it will be
        useful, but WITHOUT ANY WARRANTY; without even the implied
        warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
        PURPOSE.  See the GNU General Public License for more details.
    </para>
 
    <para>
        You should have received a copy of the GNU General Public
        License along with this program; if not, write to the Free
        Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
        USA.
    </para>
    </simplesect>

</sect1>