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">
b65bb1
            <arg>--help</arg>
b65bb1
            <arg>--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,
70d847
        nodes, etc.). This option should be used whenever a document
70d847
        structure changes (e.g., when documentation entries are added,
70d847
        copied, renamed, deleted, etc.). This option grantees the
70d847
        document integrity and should be run before the
70d847
        <option>--update-output</option> option.
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>
e03c3c
        "<replaceable>manual:part:chapter:section-1</replaceable>" "<replaceable>manual:part:chapter:section-2</replaceable>"</term>
e03c3c
    <listitem>
e03c3c
    <para>
e03c3c
        Duplicates <replaceable>section-1</replaceable> as
e03c3c
        <replaceable>section-2</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>
e03c3c
        "<replaceable>manual:part:chapter-1:</replaceable>" "<replaceable>manual:part:chapter-2:</replaceable>"</term>
e03c3c
    <listitem>
e03c3c
    <para>
e03c3c
        Duplicates <replaceable>chapter-1</replaceable> as
e03c3c
        <replaceable>chapter-2</replaceable> inside the same
e03c3c
        <replaceable>part</replaceable> and
e03c3c
        <replaceable>manual</replaceable>.
e03c3c
    </para>
e03c3c
    </listitem>
e03c3c
    </varlistentry>
e03c3c
e03c3c
    <varlistentry>
e03c3c
    <term>
e03c3c
        "<replaceable>manual:part-1::</replaceable>" "<replaceable>manual:part-2::</replaceable>"</term>
e03c3c
    <listitem>
e03c3c
    <para>
e03c3c
        Duplicates <replaceable>part-1</replaceable> as
e03c3c
        <replaceable>part-2</replaceable> inside the same
e03c3c
        <replaceable>manual</replaceable>.
e03c3c
    </para>
e03c3c
    </listitem>
e03c3c
    </varlistentry>
e03c3c
e03c3c
    <varlistentry>
e03c3c
    <term>
e03c3c
        "<replaceable>manual-1:::</replaceable>" "<replaceable>manual-2:::</replaceable>"</term>
e03c3c
    <listitem>
e03c3c
    <para>
e03c3c
        Duplicates <replaceable>manual-1</replaceable> as
e03c3c
        <replaceable>manual-2</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
e03c3c
        can be more specific in the documentation entry to reduce the
e03c3c
        amount of content to duplicate.
e03c3c
    </para>
e03c3c
            
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>
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
b65bb1
        care of updating nodes, menus and cross refentrys related to
d2638e
        documentation entries in order to keep the manual structure in
89114c
        a consistent state.
d2638e
    </para>
b65bb1
    </refsection>
2b4826
b65bb1
    <refsection id="scripts-bash-help-examples">
b65bb1
    <title>Examples</title>
70d847
70d847
    <refsection id="scripts-bash-help-description-create">
55c005
    <title>Creating Document Structures</title>
70d847
    <para>
70d847
        To create new documentation manuals inside &TCAR; use the
70d847
        following command: 
70d847
    </para>
70d847
70d847
    <cmdsynopsis>
e03c3c
    <command>centos-art help --edit --format="texinfo" "<replaceable>manual:::</replaceable>"</command>
70d847
    </cmdsynopsis>
70d847
70d847
    <para>
70d847
        The first time you execute this command, you will be prompted
70d847
        to enter manual specific information like document format,
70d847
        document title, document subtitle, document author, etc.  Once
70d847
        this information has been collected the
70d847
        <function>help</function> functionality performs some
70d847
        repository verifications and creates the manual source files
70d847
        inside the manual's directory name you specified as
e03c3c
        <replaceable>manual:::</replaceable>.
70d847
    </para>
70d847
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.).
70d847
    </para>
70d847
    </refsection>
70d847
70d847
    <refsection id="scripts-bash-help-description-edit">
70d847
    <title>Editing Document Structures</title>
70d847
70d847
    <para>
70d847
        To edit documentation entries, use the following command:
70d847
    </para>
70d847
70d847
    <cmdsynopsis>
e03c3c
    <command>centos-art help --edit --format="texinfo" "<replaceable>manual:part:chapter:section</replaceable>"</command>
70d847
    </cmdsynopsis>
70d847
70d847
    <para>
70d847
        ...
70d847
    </para>
70d847
70d847
    </refsection>
70d847
70d847
    <refsection id="scripts-bash-help-description-copy">
55c005
    <title>Copying Document Structures</title>
70d847
    <para>
70d847
        To copy one documentation entry, use the following command:
70d847
    </para>
70d847
70d847
    <cmdsynopsis>
e03c3c
    <command>centos-art help --copy --format="texinfo" "<replaceable>manual:part:chapter:section</replaceable>" "<replaceable>manual:part:chapter:section</replaceable>"</command>
70d847
    </cmdsynopsis>
70d847
70d847
    <para>
70d847
        ...
70d847
    </para>
70d847
    </refsection>
70d847
70d847
    <refsection id="scripts-bash-help-description-delete">
55c005
    <title>Deleting Document Structures</title>
70d847
    <para>
70d847
        To delete one documentation entry, use the following command:
70d847
    </para>
70d847
    <cmdsynopsis>
e03c3c
    <command>centos-art help --delete --format="texinfo" "<replaceable>manual:part:chapter:section</replaceable>"</command>
70d847
    </cmdsynopsis>
70d847
    <para>
70d847
        ...
70d847
    </para>
70d847
    </refsection>
70d847
70d847
    <refsection id="scripts-bash-help-description-rename">
55c005
    <title>Renaming Document Structures</title>
2b4826
    <para>
70d847
        To rename one documentation entry, use the following command:
2b4826
    </para>
70d847
70d847
    <cmdsynopsis>
e03c3c
    <command>centos-art help --copy --format="texinfo" "<replaceable>manual:part:chapter:section</replaceable>" "<replaceable>manual:part:chapter:section</replaceable>"</command>
70d847
    </cmdsynopsis>
55c005
55c005
    <para>
55c005
        ...
55c005
    </para>
70d847
    </refsection>
70d847
55c005
    <refsection id="scripts-bash-help-description-updatestructure">
55c005
    <title>Updating Document Structures</title>
70d847
    <para>
70d847
        To update the document structure of one manual, use the
70d847
        following command:
70d847
    </para>
70d847
70d847
    <cmdsynopsis>
e03c3c
    <command>centos-art help --update-structure --format="texinfo" "<replaceable>manual:part:chapter:section</replaceable>"</command>
55c005
    </cmdsynopsis>
55c005
55c005
    <para>
55c005
        ...
55c005
    </para>
55c005
    </refsection>
55c005
55c005
    <refsection id="scripts-bash-help-description-updateoutput">
55c005
    <title>Updating Document Final Outputs</title>
55c005
    <para>
55c005
        To update the document final outputs of one manual, use the
55c005
        following command:
55c005
    </para>
55c005
55c005
    <cmdsynopsis>
e03c3c
    <command>centos-art help --update-output --format="texinfo" "<replaceable>manual:::</replaceable>"</command>
70d847
    </cmdsynopsis>
55c005
55c005
    <para>
55c005
        ...
55c005
    </para>
70d847
    </refsection>
b65bb1
    </refsection>
2b4826
b65bb1
    <refsection id="scripts-bash-help-bugs">
b65bb1
    <title>Bugs</title>
2b4826
    <para>
2b4826
        ...
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>