Blame Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/help.docbook

b65bb1
<refentry id="scripts-bash-help">
e68d9f
b65bb1
    <refmeta>
b65bb1
        <refentrytitle>help</refentrytitle>
b65bb1
        <indexterm type="common-function">
b65bb1
            <primary>Standardize constructions tasks inside &TCAR;</primary>
b65bb1
        </indexterm>
b65bb1
    </refmeta>
b65bb1
b65bb1
    <refnamediv>
b65bb1
        <refname>help</refname>
b65bb1
        <refpurpose>Standardize documentation tasks inside &TCAR;.</refpurpose>
b65bb1
    </refnamediv>
b65bb1
b65bb1
    <refsynopsisdiv>
b65bb1
    <cmdsynopsis>
16c0de
        <command>centos-art help</command> 
b65bb1
        <arg choice="opt">
df7939
            <arg>-h|--help</arg>
df7939
            <arg>-q|--quiet</arg>
b65bb1
            <arg>--answer-yes</arg>
b65bb1
            <arg>--sync-changes</arg>
55c005
            <arg>--format="<replaceable>KEYWORD</replaceable>"</arg>
b65bb1
            <arg>--search="<replaceable>KEYWORD</replaceable>"</arg>
b65bb1
            <arg>--edit</arg>
b65bb1
            <arg>--read</arg>
70d847
            <arg>--update-output</arg>
70d847
            <arg>--update-structure</arg>
b65bb1
            <arg>--copy</arg>
b65bb1
            <arg>--delete</arg>
b65bb1
            <arg>--rename</arg>
b65bb1
        </arg>
b65bb1
        <group choice="req">
b65bb1
        <arg rep="repeat"><replaceable>MANUAL</replaceable>:<replaceable>PART</replaceable>:<replaceable>CHAPTER</replaceable>:<replaceable>SECTION</replaceable></arg>
b65bb1
        <arg rep="repeat"><replaceable>LOCATION</replaceable></arg>
b65bb1
        </group>
b65bb1
    </cmdsynopsis>
b65bb1
b65bb1
    </refsynopsisdiv>
b65bb1
b65bb1
    <refsection id="scripts-bash-help-description">
b65bb1
    <title>Description</title>
e68d9f
e68d9f
    <para>
b65bb1
        The <function>help</function> functionality exists to create
70d847
        and maintain documentation manuals inside &TCAR;.
e68d9f
    </para>
e68d9f
b65bb1
    <refsection id="scripts-bash-help-description-docentry">
16c0de
    <title>Documentation Entries</title>
b65bb1
    <para>
16c0de
        The documentation entry identifies the specific file you want
16c0de
        to work with inside a documentation manual. The help
16c0de
        functionality recognizes documentation entries in the
55c005
        following formats:
16c0de
    </para>
16c0de
    <variablelist>
16c0de
    <varlistentry>
16c0de
    <term>Path style</term>
16c0de
    <listitem>
16c0de
    <para>
16c0de
        This format uses paths to represent the documentation entries
16c0de
        you want to work with.  This format assumes you are using the
16c0de
        first path component as chapter and the rest of the path as
16c0de
        section identifier both inside <quote>tcar-fs</quote>
16c0de
        documentation manual as parent documentation structure. The
16c0de
        field related to the part sectioning structure in the
16c0de
        documentation entry (the second field) is assumed empty, as
16c0de
        well. For example, if you want to document the directory
16c0de
        <quote>
16c0de
        class="directory">trunk/Scripts/Bash/Functions/Help</filename></quote>,
16c0de
        then you can do it with the following command:
16c0de
    </para>
16c0de
16c0de
    <cmdsynopsis>
16c0de
    <command>centos-art help --edit trunk/Scripts/Bash/Functions/Help</command>
16c0de
    </cmdsynopsis>
16c0de
    </listitem>
16c0de
    </varlistentry>
16c0de
16c0de
    <varlistentry>
16c0de
    <term>Colon style</term>
16c0de
    <listitem>
16c0de
    <para>
16c0de
        This format uses colons to represent the documentation entries
16c0de
        you want to work with. In this format, the whole documentation
16c0de
        entry is divided in fields using colon as separator character.
16c0de
        Documentation entries written this way use each field to
16c0de
        specify manual, part, chapter and section identifiers (in this
16c0de
        order). The section identifier can use a path style or hyphen
16c0de
        style to separate
16c0de
        components. For example, if you want to document the directory
16c0de
        <quote>
16c0de
        class="directory">trunk/Scripts/Bash/Functions/Help</filename></quote>,
16c0de
        then you can do it with any of the following commands:
16c0de
    </para>
16c0de
16c0de
    <cmdsynopsis>
16c0de
    <command>centos-art help --edit tcar-fs::trunk:Scripts/Bash/Functions/Help</command>
16c0de
    <command>centos-art help --edit tcar-fs::trunk:scripts-bash-functions-help</command>
16c0de
    </cmdsynopsis>
16c0de
16c0de
    <para>
16c0de
        The documentation manual name specified in the first field of
16c0de
        a colon style documentation entry, must match the name the
16c0de
        name of the directory where the documentation manual is stored
16c0de
        in. By default documentation manuals are written in
16c0de
        trunk/Documentation/Models/Texinfo or
16c0de
        trunk/Documentation/Models/Docbook directories, based on
16c0de
        whether they are written in Texinfo or Docbook documentation
16c0de
        format. 
16c0de
    </para>
16c0de
    <para>
16c0de
        The match relation between the manual name you provide in the
16c0de
        documentation entry and the related directory name inside
16c0de
        &TCAR; is case insensitive. The same is true for all other
16c0de
        documentation entry fields.
b65bb1
    </para>
16c0de
16c0de
    </listitem>
16c0de
    </varlistentry>
16c0de
    </variablelist>
16c0de
16c0de
    <para>
16c0de
        From these documentation entry formats, the colon style
16c0de
        provides more flexibility than path style does. You can use
16c0de
        documentation entries written in colon style to create and
16c0de
        maintain different documentation manuals, including the
16c0de
        <quote>tcar-fs</quote> documentation manual. This is something
16c0de
        you cannot do with documentation entries written in path style
16c0de
        because they confine all documentation actions to
16c0de
        <quote>tcar-fs</quote> documentation manual.
16c0de
    </para>
16c0de
    </refsection>
16c0de
b65bb1
    </refsection>
b65bb1
b65bb1
    <refsection id="scripts-bash-help-options">
b65bb1
    <title>Options</title>
b65bb1
    <para>
b65bb1
        The <command>centos-art help</command> command accepts common
b65bb1
        options described in 
b65bb1
        linkend="scripts-bash-cli-commonoptions" /> and the following
b65bb1
        specific options:
b65bb1
    </para>
b65bb1
b65bb1
    <variablelist>
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>
7f526e
    <term><option>--sync-changes</option></term>
d2638e
    <listitem>
d2638e
    <para>
7f526e
        Synchronizes available changes between the working copy and
7f526e
        the central repository.
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
55c005
    <term><option>--format="<replaceable>KEYWORD</replaceable>"</option></term>
55c005
    <listitem>
55c005
    <para>
55c005
        Specifies the format of documentation entry source file. This
55c005
        information is used as reference to build the absolute path of
55c005
        documentation entry, so you always have to provide it in order
55c005
        to reach the documentation entry you want to work with.
e03c3c
        Possible values for this option are shown in 
55c005
        linkend="scripts-bash-help-supportedformats" />. 
55c005
    </para>
55c005
    
55c005
    <title>Documentation formats</title>
55c005
    <tgroup cols="3" align="left">
55c005
    
55c005
        <row>
55c005
            <entry>Keyword</entry>
55c005
            <entry>Description</entry>
55c005
            <entry>Supported</entry>
55c005
        </row>
55c005
    
55c005
55c005
    
55c005
        <row>
55c005
            <entry><literal>texinfo</literal></entry>
55c005
            <entry><xref linkend="manuals-formats-texinfo"/></entry>
55c005
            <entry>Yes</entry>
55c005
        </row>
55c005
        <row>
55c005
            <entry><literal>docbook</literal></entry>
55c005
            <entry><xref linkend="manuals-formats-docbook"/></entry>
55c005
            <entry>No</entry>
55c005
        </row>
55c005
        <row>
55c005
            <entry><literal>latex</literal></entry>
55c005
            <entry><xref linkend="manuals-formats-latex"/></entry>
55c005
            <entry>No</entry>
55c005
        </row>
55c005
        <row>
55c005
            <entry><literal>linuxdoc</literal></entry>
55c005
            <entry>...</entry>
55c005
            <entry>No</entry>
55c005
        </row>
55c005
    
55c005
    
55c005
    </tgroup>
55c005
    
55c005
    </listitem>
55c005
    </varlistentry>
55c005
55c005
    <varlistentry>
70d847
    <term><option>--search="<replaceable>KEYWORD</replaceable>"</option></term>
d2638e
    <listitem>
d2638e
    <para>
55c005
        Looks for documentation entries that match the
55c005
        <replaceable>KEYWORD</replaceable> specified as value and
55c005
        display them one by one in the order they were found. The way
55c005
        each documentation entry is presented to you depends on the
55c005
        documentation format the related documentation manual was
55c005
        written on.
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
d2638e
    <term><option>--edit</option></term>
d2638e
    <listitem>
d2638e
    <para>
55c005
        Edit the documentation entry provided as argument.  The
55c005
        edition itself takes place through your default text editor
55c005
        (e.g., the one you specified in the <envar>EDITOR</envar>
55c005
        environment variable) one file at a time (i.e., the queue of
55c005
        files to edit is not loaded in the text editor.).
d2638e
    </para>
e03c3c
    <para>
e03c3c
        When parent components inside documentation entries doesn't
e03c3c
        exist (e.g., you try to create a section for a documentation
e03c3c
        manual that doesn't exist), the <function>help</function>
e03c3c
        functionality will create all documentation parent structures
e03c3c
        considering the documentation format constraints and the
e03c3c
        following document structure hierarchy order: documentation
e03c3c
        <quote>manual</quote> first, <quote>parts</quote> second,
e03c3c
        <quote>chapters</quote> third and <quote>sections</quote>
e03c3c
        lastly.
e03c3c
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
d2638e
    <term><option>--read</option></term>
d2638e
    <listitem>
d2638e
    <para>
55c005
        Read the documentation entry provided as argument.  This
55c005
        option is used internally by <command>centos-art.sh</command>
55c005
        script to refer documentation based on errors, so you can know
55c005
        more about them and the causes that could have provoked them.
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
70d847
    <term><option>--update-output</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>
70d847
    <term><option>--update-structure</option></term>
70d847
    <listitem>
70d847
    <para>
70d847
        Update document structure (e.g., cross references, menus,
73221e
        nodes, etc.) and should be passed with a section as
73221e
        documentation entry.
73221e
    </para>
73221e
    <para>
73221e
        This option should be used whenever a document structure
73221e
        changes (e.g., documentation entries are added, copied,
73221e
        renamed, deleted, etc.). This option grantees the document
73221e
        integrity and should be run before updating documentation
73221e
        manual final output files.
70d847
    </para>
70d847
    </listitem>
70d847
    </varlistentry>
70d847
70d847
    <varlistentry>
d2638e
    <term><option>--copy</option></term>
d2638e
    <listitem>
d2638e
    <para>
e03c3c
        Duplicate documentation entries inside the working copy using
e03c3c
        version control.
d2638e
    </para>
d2638e
    <para>
e03c3c
        When you duplicate documentation entries through this option,
e03c3c
        you should pass only two documentation entries in the command
e03c3c
        line.  The first one is considered the source location and
e03c3c
        should point to a file under version control inside the
e03c3c
        working copy. The second one is considered the target location
e03c3c
        and should point either to the same structural level the
e03c3c
        source points to or a direct parent level based on source
e03c3c
        location, as described below.
e03c3c
    </para>
e03c3c
e03c3c
    <variablelist>
e03c3c
    <varlistentry>
e03c3c
    <term>
73221e
        "<replaceable>manual:part:chapter:section1</replaceable>" "<replaceable>manual:part:chapter:section2</replaceable>"</term>
e03c3c
    <listitem>
e03c3c
    <para>
73221e
        Duplicates <replaceable>section1</replaceable> as
73221e
        <replaceable>section2</replaceable> inside the same
e03c3c
        <replaceable>chapter</replaceable>,
e03c3c
        <replaceable>part</replaceable> and
e03c3c
        <replaceable>manual</replaceable>.
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
e03c3c
    <term>
73221e
        "<replaceable>manual:part:chapter1:</replaceable>" "<replaceable>manual:part:chapter2:</replaceable>"</term>
e03c3c
    <listitem>
e03c3c
    <para>
73221e
        Duplicates <replaceable>chapter1</replaceable> as
73221e
        <replaceable>chapter2</replaceable> inside the same
e03c3c
        <replaceable>part</replaceable> and
e03c3c
        <replaceable>manual</replaceable>.
e03c3c
    </para>
e03c3c
    </listitem>
e03c3c
    </varlistentry>
e03c3c
e03c3c
    <varlistentry>
e03c3c
    <term>
73221e
        "<replaceable>manual:part1::</replaceable>" "<replaceable>manual:part2::</replaceable>"</term>
e03c3c
    <listitem>
e03c3c
    <para>
73221e
        Duplicates <replaceable>part1</replaceable> as
73221e
        <replaceable>part2</replaceable> inside the same
e03c3c
        <replaceable>manual</replaceable>.
e03c3c
    </para>
e03c3c
    </listitem>
e03c3c
    </varlistentry>
e03c3c
e03c3c
    <varlistentry>
e03c3c
    <term>
73221e
        "<replaceable>manual1:::</replaceable>" "<replaceable>manual2:::</replaceable>"</term>
e03c3c
    <listitem>
e03c3c
    <para>
73221e
        Duplicates <replaceable>manual1</replaceable> as
73221e
        <replaceable>manual2</replaceable> inside 
e03c3c
        class="directory">trunk/Documentation/Models/${FLAG_FORMAT}/</filename>
e03c3c
        directory, where ${FLAG_FORMAT} is the name of the format
e03c3c
        passed as option with the first letter in uppercase and the
e03c3c
        rest in lowercase.
e03c3c
    </para>
e03c3c
    </listitem>
e03c3c
    </varlistentry>
e03c3c
    </variablelist>
e03c3c
    
e03c3c
    <para>
e03c3c
        When you copy documentation entries through this option, all
e03c3c
        structuring sections inside the one copied will be also
e03c3c
        copied. For example, if you copy a documentation manual that
e03c3c
        is made of parts, chapters and sections, the duplicated manual
e03c3c
        will contain all those parts, chapters and sections, as well.
e03c3c
        The same is true for lower sectioning structures. Thus, you
6449af
        can be more specific in the documentation entry by reducing
6449af
        the amount of content to duplicate.
6449af
    </para>
6449af
6449af
    <para>
6449af
        When you copy documentation entries through this option, you
e11434
        do it using documentation entries in the same structural level
e11434
        only. This option doesn't support copying documentation
e11434
        entries from differnet structural levels. For example, you
e11434
        cannot copy one section to a chapter different from that the
bc6d1b
        source section you specified belongs to. The same applies to
bc6d1b
        chapters, and parts.
e03c3c
    </para>
73221e
73221e
    <para>
73221e
        When you copy documentation entries through this option, the
73221e
        source documentation entry you specify must not contain
73221e
        pending changes.  Otherwise, the target section won't be
73221e
        created and the script will immediatly stop its execution with
73221e
        a <quote>The source location has pending changes.</quote>
73221e
        error message.
73221e
    </para>
73221e
e03c3c
    </listitem>
e03c3c
    </varlistentry>
e03c3c
e03c3c
    <varlistentry>
d2638e
    <term><option>--delete</option></term>
d2638e
    <listitem>
d2638e
    <para>
70d847
        Delete documentation entries. It is possible to delete more
70d847
        than one documentation entry by specifying several
70d847
        documentation entries in the command line.
d2638e
    </para>
73221e
    <para>
73221e
        When you delete documentation entries, you can pass any number
73221e
        of documentation entries as argument. The documentation
73221e
        entries you provide will be processed one by one.
73221e
    </para>
73221e
    <para>
73221e
        When you delete a documentation entry from a documentation
73221e
        manual, all cross references pointing to the deleted
73221e
        documentation entry will be transformed into something
73221e
        different to point out the fact that the related documentation
73221e
        entry has been removed from the documentation manual and
73221e
        restored back if you create the deleted section again. The
73221e
        purpose of this is to keep the documentation manual structure
73221e
        in a consistent state.
73221e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
e68d9f
d2638e
    <varlistentry>
d2638e
    <term><option>--rename</option></term>
d2638e
    <listitem>
d2638e
    <para>
73221e
        Rename documentation entries inside the working copy. This
73221e
        option copies the source documentation entry to its target
73221e
        location, removes the source documentation entry, and restores
73221e
        removed cross references renaming them to point the specified
73221e
        target documentation entry.
d2638e
    </para>
d2638e
    <para>
73221e
        When you rename documentation entries, 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
73221e
        target location must point to a directory under version
73221e
        control inside the working copy.
d2638e
    </para>
d2638e
    </listitem>
d2638e
    </varlistentry>
d2638e
    </variablelist>
e68d9f
b65bb1
    </refsection>
2b4826
b65bb1
    <refsection id="scripts-bash-help-examples">
b65bb1
    <title>Examples</title>
70d847
a3f3a7
    <para>
a3f3a7
        This section describes, using examples, the procedure you
a3f3a7
        should follow to manage documentation manuals through
a3f3a7
        <function>help</function> functionality inside &TCAR;. To
a3f3a7
        better understand the procedure to follow, it describes  a
a3f3a7
        hypothetical documentation scenario and the related commands
a3f3a7
        and outputs you may go through in order to complete specific
a3f3a7
        documentation tasks successfully.
a3f3a7
    </para>
a3f3a7
70d847
    <refsection id="scripts-bash-help-description-create">
55c005
    <title>Creating Document Structures</title>
70d847
    <para>
a3f3a7
        To create new documentation manuals inside &TCAR; you need to
73221e
        provide both <option>--edit</option> and
73221e
        <option>--format</option> options as well as a documentation
a3f3a7
        entry in the form <quote><literal>manual:::</literal></quote>
a3f3a7
        to the <function>help</function> functionality.
a3f3a7
    </para>
a3f3a7
a3f3a7
    <para>
a3f3a7
        For example, consider a scenario where you need to create a
afdf95
        documentation manual in texinfo format to describe different
a3f3a7
        maintenance tasks you need to realized in order to keep your
a3f3a7
        pets happy. We'll name such manual <quote>My Zoo</quote>. It
a3f3a7
        will use chapters to organize each different kind of pets you
a3f3a7
        have.  Inside chapters, sections will have the pet's name as
a3f3a7
        their own name to describe each pet's requirements, schedules,
a3f3a7
        and so on.  To create such documentation manual, run the
a3f3a7
        following command:
70d847
    </para>
70d847
70d847
    <cmdsynopsis>
a3f3a7
    <command>centos-art help --edit --format="texinfo" "myzoo:::"</command>
70d847
    </cmdsynopsis>
70d847
70d847
    <para>
afdf95
        In case such documentation manual doesn't exist in the
afdf95
        
afdf95
        class="directory">trunk/Docuementation/Models/Texinfo/</filename>
afdf95
        directory, this command will produce the following output:
70d847
    </para>
70d847
afdf95
<programlisting>
afdf95
The following documentation manual doesn't exist:
73221e
--> trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo.texinfo
afdf95
Do you want to create it now? [yes/no]: yes
afdf95
Enter manual's title: My Zoo
73221e
Enter manual's subtitle: Reference
73221e
Enter manual's abstract: This manual describes my zoo maintenance tasks.
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo.conf
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo-index.texinfo
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo-menu.texinfo
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo-nodes.texinfo
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo.texinfo
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/Licenses/chapter-menu.texinfo
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/Licenses/chapter-nodes.texinfo
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/Licenses/chapter.texinfo
73221e
Updating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo.texinfo
73221e
Creating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.info.bz2
73221e
Creating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xhtml.tar.bz2
73221e
Creating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xml
73221e
Creating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.docbook
73221e
Creating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.pdf
73221e
Creating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.txt.bz2
afdf95
</programlisting>
a3f3a7
70d847
    <para>
70d847
        Once the documentation structure has been created this way,
70d847
        the recently created documentation manual is ready to receive
70d847
        new sectioning levels (e.g., parts, chapters, sections, etc.).
afdf95
        For example, to create a new chapter named
a3f3a7
        <quote>Turtles</quote> inside <quote>My Zoo</quote>
afdf95
        documentation manual, run the following command:
70d847
    </para>
afdf95
afdf95
    <cmdsynopsis>
a3f3a7
    <command>centos-art help --edit --format="texinfo" "myzoo::turtles:"</command>
afdf95
    </cmdsynopsis>
afdf95
afdf95
<programlisting>
afdf95
The following documentation chapter doesn't exist:
73221e
--> trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles
afdf95
Do you want to create it now? [yes/no]: yes
afdf95
Enter chapter's title: Turtles
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/chapter-menu.texinfo
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/chapter-nodes.texinfo
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/chapter.texinfo
73221e
Updating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo-menu.texinfo
73221e
Updating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/myzoo-nodes.texinfo
73221e
Updating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/chapter.texinfo
73221e
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.info.bz2
73221e
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xhtml.tar.bz2
73221e
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xml
73221e
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.docbook
73221e
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.pdf
73221e
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.txt.bz2
afdf95
</programlisting>
afdf95
70d847
    <para>
beca32
        Once chapters have been created it is possible to create
a3f3a7
        sections inside them.  For example, if you want to create a
a3f3a7
        section for describing the life of a turtle named Longneck,
a3f3a7
        run the following command:
70d847
    </para>
70d847
70d847
    <cmdsynopsis>
a3f3a7
    <command>centos-art help --edit --format="texinfo" "myzoo::turtles:longneck"</command>
70d847
    </cmdsynopsis>
70d847
beca32
<programlisting>
beca32
The following documentation section doesn't exist:
73221e
--> trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/longneck.texinfo
beca32
Do you want to create it now? [yes/no]: yes
73221e
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/longneck.texinfo
73221e
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.info.bz2
73221e
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xhtml.tar.bz2
73221e
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xml
73221e
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.docbook
73221e
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.pdf
73221e
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.txt.bz2
beca32
</programlisting>
beca32
beca32
    </refsection>
beca32
beca32
    <refsection id="scripts-bash-help-description-edit">
beca32
    <title>Editing Document Structures</title>
70d847
    <para>
beca32
        To edit documentation entries you can follow the same
a3f3a7
        procedure described above. Just keep in mind the following
a3f3a7
        rules:
a3f3a7
    </para>
a3f3a7
    
a3f3a7
    <itemizedlist>
a3f3a7
    <listitem>
a3f3a7
    <para>
a3f3a7
        When the entry you want to edit already exist it will be
a3f3a7
        edited.
70d847
    </para>
a3f3a7
    </listitem>
a3f3a7
a3f3a7
    <listitem>
a3f3a7
    <para>
a3f3a7
     When the entry you want to edit doesn't exist it will be created
a3f3a7
     first and edited later.
a3f3a7
    </para>
a3f3a7
    </listitem>
a3f3a7
a3f3a7
    </itemizedlist>
a3f3a7
70d847
    </refsection>
70d847
70d847
    <refsection id="scripts-bash-help-description-copy">
55c005
    <title>Copying Document Structures</title>
70d847
    <para>
a3f3a7
        Consider a new turtle named Slowfeet has arrived to your home
a3f3a7
        and you want to duplicate Longneck's section for it (they both
a3f3a7
        are turtles and have similar requirements, squedules, etc.).
a3f3a7
        To copy documentation entries you use the
a3f3a7
        <option>--copy</option> option with two documentation entries,
a3f3a7
        where the first one is the source location and the second one
73221e
        the target location.  To do this, run the following command:
70d847
    </para>
70d847
70d847
    <cmdsynopsis>
a3f3a7
    <command>centos-art help --copy --format="texinfo" "myzoo::turtles:longneck" "myzoo::turtles:slowfeet"</command>
70d847
    </cmdsynopsis>
70d847
a3f3a7
<programlisting>
a3f3a7
Creating        trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/slowfeet.texinfo
a3f3a7
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.info.bz2
a3f3a7
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xhtml.tar.bz2
a3f3a7
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.xml
a3f3a7
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.docbook
a3f3a7
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.pdf
a3f3a7
Updating        trunk/Documentation/Manuals/Texinfo/Myzoo/en_US/myzoo.txt.bz2
a3f3a7
</programlisting>
a3f3a7
70d847
    </refsection>
70d847
73221e
    <refsection id="scripts-bash-help-description-rename">
73221e
    <title>Renaming Document Structures</title>
70d847
    <para>
73221e
        Consider you've created the section of Longneck turtle using
73221e
        the following documentation entry format
73221e
        <quote>myzoo::turtles:longnek</quote>, but you didn't notice
73221e
        the typo in it. You've made cross references to the misspelled
73221e
        section in a few pages inside the <quote>My Zoo</quote>
73221e
        documentation manual and some time later you realize the
73221e
        section name has a spelling problem.  To fix such a problem
73221e
        you can rename the misspelled section with the correct one
73221e
        running the following command:
70d847
    </para>
73221e
70d847
    <cmdsynopsis>
73221e
    <command>centos-art help --rename --format="texinfo" "myzoo::turtles:longnek" "myzoo::turtles:longneck"</command>
70d847
    </cmdsynopsis>
73221e
73221e
<programlisting>
73221e
Creating        trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/longneck.texinfo
73221e
Deleting        trunk/Documentation/Models/Texinfo/MyZoo/en_US/Turtles/longnek.texinfo
73221e
Updating        trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.info.bz2
73221e
Updating        trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xhtml.tar.bz2
73221e
Updating        trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xml
73221e
Updating        trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.docbook
73221e
Updating        trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.pdf
73221e
Updating        trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.txt.bz2
73221e
</programlisting>
73221e
70d847
    <para>
70d847
        ...
70d847
    </para>
70d847
    </refsection>
70d847
73221e
    <refsection id="scripts-bash-help-description-delete">
73221e
    <title>Deleting Document Structures</title>
2b4826
    <para>
73221e
        Consider you gift the turtle named Longneck to a friend and
73221e
        you want to delete its section from the <quote>My Zoo</quote>
73221e
        documentation manual. To do so, run the following command:
2b4826
    </para>
70d847
    <cmdsynopsis>
73221e
    <command>centos-art help --delete --format="texinfo" "myzoo::turtles:longneck"</command>
70d847
    </cmdsynopsis>
73221e
<programlisting>
73221e
Deleting        trunk/Documentation/Models/Texinfo/Myzoo/en_US/Turtles/longneck.texinfo
73221e
Updating        trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.info.bz2
73221e
Updating        trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xhtml.tar.bz2
73221e
Updating        trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.xml
73221e
Updating        trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.docbook
73221e
Updating        trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.pdf
73221e
Updating        trunk/Documentation/Manuals/Texinfo/MyZoo/en_US/myzoo.txt.bz2
73221e
</programlisting>
55c005
70d847
    </refsection>
70d847
b65bb1
    </refsection>
2b4826
b65bb1
    <refsection id="scripts-bash-help-bugs">
b65bb1
    <title>Bugs</title>
2b4826
    <para>
bc6d1b
        To report bugs related to this function, please create a new
98cbf2
        ticket 
98cbf2
        url="https://projects.centos.org/trac/artwork/newticket?summary=Error%20Standardizing%20Documentation%20Tasks&component=Scripts">here</ulink>
98cbf2
        refering the specific problems you found in it. For example,
98cbf2
        it would be useful if you copy and paste any error output from
98cbf2
        <command>centos-art.sh</command> script.
2b4826
    </para>
b65bb1
    </refsection>
2b4826
b65bb1
    <refsection id="scripts-bash-help-authors">
2b4826
    <title>Authors</title>
2b4826
    <para>
b65bb1
        The following people have worked in this functionality:
2b4826
    </para>
2b4826
    <itemizedlist>
2b4826
    <listitem>
2b4826
    <para>
1542c4
        Alain Reguera Delgado <<ulink url="mailto:alain.reguera@gmail.com">alain.reguera@gmail.com</ulink>>, =COPYRIGHT_YEAR_LIST=
2b4826
    </para>
2b4826
    </listitem>
2b4826
    </itemizedlist>
b65bb1
    </refsection>
2b4826
b65bb1
    <refsection id="scripts-bash-help-licence">
2b4826
    <title>License</title>
1542c4
2b4826
    <para>
1542c4
        Copyright © =COPYRIGHT_YEAR_LIST= The CentOS Project
1542c4
    </para>
2b4826
 
1542c4
    <para>
1542c4
        This program is free software; you can redistribute it and/or
1542c4
        modify it under the terms of the GNU General Public License as
1542c4
        published by the Free Software Foundation; either version 2 of
1542c4
        the License, or (at your option) any later version.
1542c4
    </para>
2b4826
 
1542c4
    <para>
1542c4
        This program is distributed in the hope that it will be
1542c4
        useful, but WITHOUT ANY WARRANTY; without even the implied
1542c4
        warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
1542c4
        PURPOSE.  See the GNU General Public License for more details.
1542c4
    </para>
2b4826
 
1542c4
    <para>
1542c4
        You should have received a copy of the GNU General Public
1542c4
        License along with this program; if not, write to the Free
1542c4
        Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
1542c4
        USA.
2b4826
    </para>
b65bb1
    </refsection>
e68d9f
b65bb1
</refentry>