Blob Blame History Raw
<refentry id="scripts-bash-help">

    <refmeta>
        <refentrytitle>help</refentrytitle>
        <indexterm type="common-function">
            <primary>Standardize constructions tasks inside &TCAR;</primary>
        </indexterm>
    </refmeta>

    <refnamediv>
        <refname>help</refname>
        <refpurpose>Standardize documentation tasks inside &TCAR;.</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
    <cmdsynopsis>
        <command>centos-art help</command> 
        <arg choice="opt">
            <arg>--help</arg>
            <arg>--quiet</arg>
            <arg>--answer-yes</arg>
            <arg>--sync-changes</arg>
            <arg>--search="<replaceable>KEYWORD</replaceable>"</arg>
            <arg>--edit</arg>
            <arg>--read</arg>
            <arg>--update-output</arg>
            <arg>--update-structure</arg>
            <arg>--copy</arg>
            <arg>--delete</arg>
            <arg>--rename</arg>
        </arg>
        <group choice="req">
        <arg rep="repeat"><replaceable>MANUAL</replaceable>:<replaceable>PART</replaceable>:<replaceable>CHAPTER</replaceable>:<replaceable>SECTION</replaceable></arg>
        <arg rep="repeat"><replaceable>LOCATION</replaceable></arg>
        </group>
    </cmdsynopsis>

    </refsynopsisdiv>

    <refsection id="scripts-bash-help-description">
    <title>Description</title>

    <para>
        The <function>help</function> functionality exists to create
        and maintain documentation manuals inside &TCAR;.
    </para>

    <refsection id="scripts-bash-help-description-docentry">
    <title>Documentation Entries</title>
    <para>
        The documentation entry identifies the specific file you want
        to work with inside a documentation manual. The help
        functionality recognizes documentation entries in the
        following two formats:
    </para>
    <variablelist>
    <varlistentry>
    <term>Path style</term>
    <listitem>
    <para>
        This format uses paths to represent the documentation entries
        you want to work with.  This format assumes you are using the
        first path component as chapter and the rest of the path as
        section identifier both inside <quote>tcar-fs</quote>
        documentation manual as parent documentation structure. The
        field related to the part sectioning structure in the
        documentation entry (the second field) is assumed empty, as
        well. For example, if you want to document the directory
        <quote><filename
        class="directory">trunk/Scripts/Bash/Functions/Help</filename></quote>,
        then you can do it with the following command:
    </para>

    <cmdsynopsis>
    <command>centos-art help --edit trunk/Scripts/Bash/Functions/Help</command>
    </cmdsynopsis>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term>Colon style</term>
    <listitem>
    <para>
        This format uses colons to represent the documentation entries
        you want to work with. In this format, the whole documentation
        entry is divided in fields using colon as separator character.
        Documentation entries written this way use each field to
        specify manual, part, chapter and section identifiers (in this
        order). The section identifier can use a path style or hyphen
        style to separate
        components. For example, if you want to document the directory
        <quote><filename
        class="directory">trunk/Scripts/Bash/Functions/Help</filename></quote>,
        then you can do it with any of the following commands:
    </para>

    <cmdsynopsis>
    <command>centos-art help --edit tcar-fs::trunk:Scripts/Bash/Functions/Help</command>
    <command>centos-art help --edit tcar-fs::trunk:scripts-bash-functions-help</command>
    </cmdsynopsis>

    <para>
        The documentation manual name specified in the first field of
        a colon style documentation entry, must match the name the
        name of the directory where the documentation manual is stored
        in. By default documentation manuals are written in
        trunk/Documentation/Models/Texinfo or
        trunk/Documentation/Models/Docbook directories, based on
        whether they are written in Texinfo or Docbook documentation
        format. 
    </para>
    <para>
        The match relation between the manual name you provide in the
        documentation entry and the related directory name inside
        &TCAR; is case insensitive. The same is true for all other
        documentation entry fields.
    </para>

    </listitem>
    </varlistentry>
    </variablelist>

    <para>
        From these documentation entry formats, the colon style
        provides more flexibility than path style does. You can use
        documentation entries written in colon style to create and
        maintain different documentation manuals, including the
        <quote>tcar-fs</quote> documentation manual. This is something
        you cannot do with documentation entries written in path style
        because they confine all documentation actions to
        <quote>tcar-fs</quote> documentation manual.
    </para>
    </refsection>

    <refsection id="scripts-bash-help-description-formats">
    <title>Supported Documentation Formats</title>

    <para>
        The <function>help</function> functionality provides support
        for the following documentation formats:
    </para>

    <itemizedlist>
    <listitem>
    <para>
        Texinfo, as described in <xref linkend="manuals-format-texinfo"/>.
    </para>
    </listitem>
    </itemizedlist>

    </refsection>

    </refsection>

    <refsection id="scripts-bash-help-options">
    <title>Options</title>
    <para>
        The <command>centos-art help</command> command accepts common
        options described in <xref
        linkend="scripts-bash-cli-commonoptions" /> and the following
        specific options:
    </para>

    <variablelist>
    <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="<replaceable>KEYWORD</replaceable>"</option></term>
    <listitem>
    <para>
        This option looks for <replaceable>KEYWORD</replaceable>
        inside the documentation entry you provide and displays the
        related information for you to read.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--edit</option></term>
    <listitem>
    <para>
        Edit documentation entry.
    </para>
    <para>
        The documentation entry must point to any directory inside the
        working copy.  When more than one documentation entry is
        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.  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-output</option></term>
    <listitem>
    <para>
        Update output files rexporting them from the specified backend
        source files.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--update-structure</option></term>
    <listitem>
    <para>
        Update document structure (e.g., cross references, menus,
        nodes, etc.). This option should be used whenever a document
        structure changes (e.g., when documentation entries are added,
        copied, renamed, deleted, etc.). This option grantees the
        document integrity and should be run before the
        <option>--update-output</option> option.
    </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. It is possible to delete more
        than one documentation entry by specifying several
        documentation entries 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 refentrys related to
        documentation entries in order to keep the manual structure in
        a consistent state.
    </para>
    </refsection>

    <refsection id="scripts-bash-help-examples">
    <title>Examples</title>

    <refsection id="scripts-bash-help-description-create">
    <title>New Document Structures</title>
    <para>
        To create new documentation manuals inside &TCAR; use the
        following command: 
    </para>

    <cmdsynopsis>
    <command>centos-art help --edit "<replaceable>manual</replaceable>"</command>
    </cmdsynopsis>

    <para>
        The first time you execute this command, you will be prompted
        to enter manual specific information like document format,
        document title, document subtitle, document author, etc.  Once
        this information has been collected the
        <function>help</function> functionality performs some
        repository verifications and creates the manual source files
        inside the manual's directory name you specified as
        <replaceable>manual</replaceable>.
    </para>

    <para>
        Once the documentation structure has been created this way,
        the recently created documentation manual is ready to receive
        new sectioning levels (e.g., parts, chapters, sections, etc.).
    </para>
    </refsection>

    <refsection id="scripts-bash-help-description-edit">
    <title>Editing Document Structures</title>

    <para>
        To edit documentation entries, use the following command:
    </para>

    <cmdsynopsis>
    <command>centos-art help --edit "<replaceable>manual:part:chapter:section</replaceable>"</command>
    </cmdsynopsis>

    <para>
        ...
    </para>

    </refsection>

    <refsection id="scripts-bash-help-description-copy">
    <title>Copying Document Structure</title>
    <para>
        To copy one documentation entry, use the following command:
    </para>

    <cmdsynopsis>
    <command>centos-art help --copy "<replaceable>manual:part:chapter:section</replaceable>" "<replaceable>manual:part:chapter:section</replaceable>"</command>
    </cmdsynopsis>

    <para>
        ...
    </para>
    </refsection>

    <refsection id="scripts-bash-help-description-delete">
    <title>Deleting Document Structure</title>
    <para>
        To delete one documentation entry, use the following command:
    </para>
    <cmdsynopsis>
    <command>centos-art help --delete "<replaceable>manual:part:chapter:section</replaceable>"</command>
    </cmdsynopsis>
    <para>
        ...
    </para>
    </refsection>

    <refsection id="scripts-bash-help-description-rename">
    <title>Renaming Document Structure</title>
    <para>
        To rename one documentation entry, use the following command:
    </para>

    <cmdsynopsis>
    <command>centos-art help --copy "<replaceable>manual:part:chapter:section</replaceable>" "<replaceable>manual:part:chapter:section</replaceable>"</command>
    </cmdsynopsis>
    </refsection>

    <refsection id="scripts-bash-help-description-update">
    <title>Updating Document Structure</title>
    <para>
        To update the document structure of one manual, use the
        following command:
    </para>

    <cmdsynopsis>
    <command>centos-art help --update-structure "<replaceable>manual</replaceable>"</command>
    </cmdsynopsis>
    </refsection>
    </refsection>

    <refsection id="scripts-bash-help-bugs">
    <title>Bugs</title>
    <para>
        ...
    </para>
    </refsection>

    <refsection id="scripts-bash-help-authors">
    <title>Authors</title>
    <para>
        The following people have worked in this 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>
    </refsection>

    <refsection 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>
    </refsection>

</refentry>