Blame Manuals/Tcar-ug/Scripts/Bash/help.docbook

e68d9f
<sect1 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
2b4826
    <sect2 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>
2b4826
    </sect2>
541cb9
2b4826
    <sect2 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>
d2638e
    <term><option>--dont-commit-changes</option></term>
d2638e
    <listitem>
d2638e
    <para>
d2638e
        Supress all commit and update actions realized over files,
d2638e
        before and after the action itself had took place over files
d2638e
        in the working copy.
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
d2638e
        care of updating nodes, menus and cross references related to
d2638e
        documentation entries in order to keep the manual structure in
89114c
        a consistent state.
d2638e
    </para>
2b4826
    </sect2>
2b4826
2b4826
    <sect2 id="scripts-bash-help-description">
2b4826
    <title>Description</title>
2b4826
    <para>
2b4826
        ...
2b4826
    </para>
2b4826
    </sect2>
2b4826
2b4826
    <sect2 id="script-bash-help-environment">
2b4826
    <title>Environment</title>
2b4826
    <para>
2b4826
        ...
2b4826
    </para>
2b4826
    </sect2>
2b4826
2b4826
    <sect2 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>
2b4826
        Alain Reguera Delgado <<ulink url="mailto:alain.reguera@gmail.com">alain.reguera@gmail.com</ulink>>
2b4826
    </para>
2b4826
    </listitem>
2b4826
    </itemizedlist>
2b4826
    </sect2>
2b4826
2b4826
    <sect2 id="scripts-bash-help-licence">
2b4826
    <title>License</title>
2b4826
    <para>
2b4826
<screen>Copyright (C) 2009-2012 The CentOS Project
2b4826
 
2b4826
This program is free software; you can redistribute it and/or modify
2b4826
it under the terms of the GNU General Public License as published by
2b4826
the Free Software Foundation; either version 2 of the License, or (at
2b4826
your option) any later version.
2b4826
 
2b4826
This program is distributed in the hope that it will be useful, but
2b4826
WITHOUT ANY WARRANTY; without even the implied warranty of
2b4826
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
2b4826
General Public License for more details.
2b4826
 
2b4826
You should have received a copy of the GNU General Public License
2b4826
along with this program; if not, write to the Free Software
2b4826
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.</screen>
2b4826
    </para>
2b4826
    </sect2>
e68d9f
e68d9f
</sect1>