| <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> |
| |
| <sect2 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> |
| </sect2> |
| |
| <sect2 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>--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>--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> |
| </sect2> |
| |
| <sect2 id="scripts-bash-help-description"> |
| <title>Description</title> |
| <para> |
| ... |
| </para> |
| </sect2> |
| |
| <sect2 id="script-bash-help-environment"> |
| <title>Environment</title> |
| <para> |
| ... |
| </para> |
| </sect2> |
| |
| <sect2 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 <<ulink url="mailto:alain.reguera@gmail.com">alain.reguera@gmail.com</ulink>> |
| </para> |
| </listitem> |
| </itemizedlist> |
| </sect2> |
| |
| <sect2 id="scripts-bash-help-licence"> |
| <title>License</title> |
| <para> |
| <screen>Copyright (C) 2009-2012 The CentOS Project |
| |
| 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. |
| |
| 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. |
| |
| 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.</screen> |
| </para> |
| </sect2> |
| |
| </sect1> |