<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>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</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 structures inside &TCAR;. The

        documentation structure and documentation format implemented

        by this functionality is described in  

        linkend="manuals-production-identifying-structure" /> and

        <xref linkend="manuals-format-texinfo" />, respectively.

    </para>

    <refsection id="scripts-bash-help-description-docentry">

    <title>Documentation Entry Format</title>

    <para>

        ...

    </para>

    </refsection>

    <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-name</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-name</replaceable>.

    </para>

    <para>

        When you create new documentation manuals, take care of the

        locale information you are currently using. This information

        is generally set in the <envar>LANG</envar> environment

        variable and is used by the <function>help</function>

        functionality of <command>centos-art.sh</command> script to

        define the language of new documentation manual and the

        document template used to build it, as well.

    </para>

    <para>

        Once the documentation structure has been created this way,

        the recently created documentation manual is ready to receive

        new chapters and sections.

    </para>

    </refsection>

    <refsection id="scripts-bash-help-description-edit">

    <title>Editing Document Structures</title>

    <cmdsynopsis>

    <command>centos-art help --edit "tcar-fs::trunk"</command>

    </cmdsynopsis>

    <para>

        This command edits the <quote>trunk</quote> chapter

        documentation entry. Here is where you can define the chapter

        introduction. This very same procedure is used to create

        <quote>branches</quote> and <quote>tags</quote> chapters, just

        be sure to change the chapter field accordingly.

    </para>

    <para>

        If the related manual or chapter itself don't exist in the

        documentation structure, centos-art.sh script creates them in

        their respective hierarchical order (i.e., the manual

        structure first, and the chapter structure later).

    </para>

    <cmdsynopsis>

    <command>centos-art help --edit "tcar-fs::trunk:Identity"</command>

    </cmdsynopsis>

    <para>

        This command edits the <quote>trunk/Identity</quote>

        documentation entry inside <quote>The CentOS Artwork

        Repository File System</quote> documentation manual.

    </para>

    <para>

        When you edit documentation for a directory which related

        chapter doesn't exist, centos-art.sh script creates the

        related chapter first and then proceed to create the related

        documentaiton entry.

    </para>

    <para>

        In order to document deeper directory levels, you need to

        refer the directory you want to document by using a path-style

        or a hyphen-style format as documentation entry.  For example,

        to edit the documentation related to the <quote>

        class="directory">trunk/Identity/Models/Themes</filename></quote>

        directory, you can use any of the following documentation

        entries:

    </para>

    <itemizedlist>

    <listitem>

    <para>

        <literal>tcar-fs::trunk:identity-models-themes</literal>

    </para>

    </listitem>

    <listitem>

    <para>

        <literal>tcar-fs::trunk:Identity/Models/Themes</literal>

    </para>

    </listitem>

    <listitem>

    <para>

        <literal>trunk/Identity/Models/Themes</literal>

    </para>

    <note>

    <para>

        This last format assummes you are using the

        <quote>trunk</quote> chapter inside <quote>tcar-fs</quote>

        documentation manual as parent documentation structure. The

        field related to the part sectioning structure in the

        documentatin entry (second field) is assumed empty, as well.

    </para>

    </note>

    </listitem>

    </itemizedlist>

    </refsection>

    <refsection id="scripts-bash-help-description-copy">

    <title>Copying Document Structure</title>

    <para>

        ...

    </para>

    </refsection>

    <refsection id="scripts-bash-help-description-delete">

    <title>Deleting Document Structure</title>

    <para>

        ...

    </para>

    </refsection>

    <refsection id="scripts-bash-help-description-rename">

    <title>Renaming Document Structure</title>

    <para>

        ...

    </para>

    </refsection>

    <refsection id="scripts-bash-help-description-update">

    <title>Updating Document Structure</title>

    <para>

        ...

    </para>

    </refsection>

    </refsection>

    <refsection id="scripts-bash-help-options">

    <title>Options</title>

    <para>

        The <command>centos-art help</command> command accepts common

        options described in 

        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="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 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>

    <para>

        None.

    </para>

    </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 <<ulink url="mailto:alain.reguera@gmail.com">alain.reguera@gmail.com</ulink>>, =COPYRIGHT_YEAR_LIST=

    </para>

    </listitem>

    </itemizedlist>

    </refsection>

    <refsection id="scripts-bash-help-licence">

    <title>License</title>

    <para>

        Copyright © =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>