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

905b18
<section id="scripts-bash-cliref">
905b18
905b18
    <title>Command-line Reference</title>
905b18
905b18
    <para>
905b18
        The <command>centos-art.sh</command> script follows a
905b18
        conventional command-line interface where there might be
905b18
        options and non-option arguments in it. As convention, the
905b18
        first non-option argument passed to
905b18
        <command>centos-art.sh</command> script will be the name of
905b18
        the specific function you want to execute (e.g.,
905b18
        <function>render</function>, <function>locale</function>,
905b18
        <function>help</function>, etc.).  This first argument will be
905b18
        immediately removed from the list of arguments passed to
905b18
        <command>centos-art.sh</command> script to leave just the
905b18
        remaining options and non-option arguments passed to it.  At
905b18
        this point, the <command>centos-art.sh</command> script uses
905b18
        the <command>getopt</command> command to retrieve option
905b18
        arguments and remove them from the list of arguments passed to
905b18
        <command>centos-art.sh</command> script.
905b18
    </para>
905b18
905b18
    <para>
905b18
        Once option arguments have been removed from list of arguments
905b18
        passed to <command>centos-art.sh</command> script, non option
905b18
        arguments are processed then.  Non-option arguments will
905b18
        always be paths pointing directories inside your working copy
905b18
        of &TCAR;. These paths can be absolute paths or relative paths
905b18
        considering the working copy root directory as section. For
905b18
        example, both the absolute path 
905b18
        class="directory">/home/al/Projects/CentOS/artwork/trunk/Identity/Themes/</filename>
905b18
        and the relative path 
905b18
        class="directory">trunk/Identity/Themes</filename> point to
905b18
        the same location.
905b18
    </para>
905b18
905b18
    <section id="scripts-bash-cliref-cli">
905b18
    <title>The Command-line Interface</title>
905b18
905b18
    <para>
905b18
        To better understand the <command>centos-art.sh</command>
905b18
        command-line interface, let's consider the real command shown
905b18
        in <xref linkend="scripts-bash-cliref-cli-example1" /> as
905b18
        section.  This command shows the entire command as a list of
905b18
        space-separated arguments. The value of each argument can be
905b18
        reached using special variable names based on the number of
905b18
        arguments passed to the command-line.
905b18
    </para>
905b18
905b18
    <example id="scripts-bash-cliref-cli-example1">
905b18
    <title>The command-line interface</title>
905b18
    <screenshot>
905b18
    <screeninfo>The command-line interface</screeninfo>
905b18
    <mediaobject>
905b18
    <textobject>
905b18
<programlisting>
905b18
   ${0}  | |${1}| |          ${2}            | |    ${3}   |
905b18
---------|-|----|-|--------------------------|-|-----------|
905b18
centos-art render trunk/Identity/Images/Themes --with-brands
905b18
---------|-|----|-|--------------------------|-|-----------|
905b18
</programlisting>
905b18
    </textobject>
905b18
    </mediaobject>
905b18
    </screenshot>
905b18
    </example>
905b18
905b18
    <para>
905b18
        In <xref linkend="scripts-bash-cliref-cli-example1" />, the
905b18
        relation between special variables and arguments has the
905b18
        following meaning:
905b18
    </para>
905b18
905b18
    <variablelist>
905b18
    <varlistentry>
905b18
    <term><varname>${0}</varname></term>
905b18
    <listitem>
905b18
    <para>
905b18
        This variable contains the absolute path to the command
905b18
        executed. In case your home directory be 
905b18
        class="directory">/home/john</filename> the value of this
905b18
        argument will be expanded to
905b18
        <filename>/home/john/bin/centos-art</filename> which is a
905b18
        symbolic link to the
905b18
        <filename>${TCAR_WORKDIR}/trunk/Scripts/Bash/centos-art.sh</filename>
905b18
        file.
905b18
    </para>
905b18
    </listitem>
905b18
    </varlistentry>
905b18
905b18
    <varlistentry>
905b18
    <term><varname>${1}</varname></term>
905b18
    <listitem>
905b18
    <para>
905b18
        This variable contains the first non-option argument we use to
905b18
        determine the specific function environment we want to execute
905b18
        (e.g., <function>render</function> in this case). The position
905b18
        of this information in the command-line is relevant to
905b18
        <command>centos-art.sh</command> script and must not be
905b18
        changed. Possible values to this variable are specified in
905b18
        <xref linkend="scripts-bash-cli-specificfuncs" />.
905b18
    </para>
905b18
905b18
    </listitem>
905b18
    </varlistentry>
905b18
905b18
    <varlistentry>
905b18
    <term><varname>${2}</varname></term>
905b18
    <listitem>
905b18
    <para>
905b18
        This variable contains a non-option argument referring a path
905b18
        information inside the working copy of &TCAR;. The specific
905b18
        path information you provide in this variable must be
905b18
        recognized by specific function environment provided in
905b18
        <varname>${1}</varname> variable. The position of path
905b18
        information in the command-line is not relevant to
905b18
        <command>centos-art.sh</command> script and can be changed
905b18
        whenever it doesn't be interpreted as value to
905b18
        <varname>${1}</varname> variable.
905b18
    </para>
905b18
    </listitem>
905b18
    </varlistentry>
905b18
905b18
    <varlistentry>
905b18
    <term><varname>${3}</varname></term>
905b18
    <listitem>
905b18
    <para>
905b18
        This variable contains an option argument. The specific option
905b18
        information you provide in this variable must be recognized by
905b18
        specific function environment provided in
905b18
        <varname>${1}</varname> variable. The position of options in
905b18
        the command-line is not relevant to
905b18
        <command>centos-art.sh</command> script and can be changed
905b18
        whenever it doesn't be interpreted as value to
905b18
        <varname>${1}</varname> variable.
905b18
    </para>
905b18
    </listitem>
905b18
    </varlistentry>
905b18
905b18
    </variablelist>
905b18
    </section>
905b18
905b18
    <section id="scripts-bash-cli-commonoptions">
905b18
    <title>Common Options</title>
905b18
905b18
    <para>
905b18
        As convention, all function specific environments should
905b18
        provide support for the following common options: 
905b18
    </para>
905b18
905b18
    <variablelist>
905b18
    <varlistentry>
905b18
    <term><option>-h</option> | <option>--help</option></term>
905b18
    <listitem>
905b18
    <para>
905b18
        This option makes <command>centos-art.sh</command> script to
905b18
        shows information about the specific function environment
905b18
        (e.g., how to execute it, available options, etc.) set as
905b18
        first non-option argument. For example, if you provide the
905b18
        <command>centos-art render --help</command>, the
905b18
        <command>centos-art.sh</command> script will display to you
905b18
        the information related to the 
905b18
        class="directory">trunk/Scripts/Bash/Functions/Render</filename>
905b18
        directory.
905b18
    </para>
905b18
    <para>
905b18
        This information is retrived from <quote>The CentOS Artwork
905b18
        Repository File System (tcar-fs)</quote> documentation manual.
905b18
        This manual is written in Texinfo format and provides a quick
905b18
        way for you to read and browse documentation related to each
905b18
        directory inside &TCAR; as you work with it from a text
905b18
        terminal.
905b18
    </para>
905b18
    </listitem>
905b18
    </varlistentry>
905b18
905b18
    <varlistentry>
905b18
    <term><option>-q</option> | <option>--quiet</option></term>
905b18
    <listitem>
905b18
    <para>
905b18
        This option makes the <command>centos-art.sh</command> script
905b18
        to suppress messages sent to standard output. This option
905b18
        doesn't suppress error messages, nor questions related to
905b18
        script execution.
905b18
    </para>
905b18
    </listitem>
905b18
    </varlistentry>
905b18
905b18
    </variablelist>
905b18
    </section>
905b18
905b18
    <section id="scripts-bash-cli-specificoptions">
905b18
    <title>Specific Options</title>
905b18
905b18
    <para>
905b18
        The specific options used by specific and common function
905b18
        environments are described in their respective sections. See
905b18
        <xref linkend="scripts-bash-cli-specificfuncs" /> and 
905b18
        linkend="scripts-bash-cli-commonfuncs" /> to know which these
905b18
        sections are.
905b18
    </para>
905b18
905b18
    
905b18
    <title>Specific Function Environments</title>
905b18
    <tgroup cols="2" align="left">
905b18
    
905b18
        <row>
905b18
            <entry>Name</entry>
905b18
            <entry>Description</entry>
905b18
        </row>
905b18
    
905b18
905b18
    
905b18
        <row>
905b18
            <entry><literal>prepare</literal></entry>
905b18
            <entry><xref linkend="scripts-bash-prepare" /></entry>
905b18
        </row>
905b18
        <row>
905b18
            <entry><literal>render</literal></entry>
905b18
            <entry><xref linkend="scripts-bash-render" /></entry>
905b18
        </row>
905b18
        <row>
905b18
            <entry><literal>locale</literal></entry>
905b18
            <entry><xref linkend="scripts-bash-locale" /></entry>
905b18
        </row>
905b18
        <row>
905b18
            <entry><literal>help</literal></entry>
905b18
            <entry><xref linkend="scripts-bash-help" /></entry>
905b18
        </row>
905b18
        <row>
905b18
            <entry><literal>pack</literal></entry>
905b18
            <entry><xref linkend="scripts-bash-pack" /></entry>
905b18
        </row>
905b18
        <row>
905b18
            <entry><literal>tuneup</literal></entry>
905b18
            <entry><xref linkend="scripts-bash-tuneup" /></entry>
905b18
        </row>
905b18
        <row>
905b18
            <entry><literal>svn</literal></entry>
905b18
            <entry><xref linkend="scripts-bash-svn" /></entry>
905b18
        </row>
905b18
    
905b18
    
905b18
    </tgroup>
905b18
    
905b18
905b18
    
905b18
    <title>Common Function Environments</title>
905b18
    <tgroup cols="2" align="left">
905b18
    
905b18
        <row>
905b18
            <entry>Name</entry>
905b18
            <entry>Description</entry>
905b18
        </row>
905b18
    
905b18
905b18
    
905b18
        <row>
905b18
            <entry><literal>cli_checkFiles</literal></entry>
905b18
            <entry><xref linkend="scripts-bash-cli_checkFiles" /></entry>
905b18
        </row>
905b18
    
905b18
    
905b18
    </tgroup>
905b18
    
905b18
905b18
    </section>
905b18
905b18
    <section id="scripts-bash-cliref-implementation">
905b18
905b18
        <title>Implementation</title>
905b18
905b18
        <para>
905b18
            When a new function is created to
905b18
            <command>centos-art.sh</command> script, it is necessary
905b18
            to consider whether it will use arguments or not. When the
905b18
            function doesn't need arguments (e.g., it exists to
905b18
            redefine values related to global variables only) there is
905b18
            no need to consider a parsing feature for it.  However,
905b18
            when the function does use arguments it is very important
905b18
            to parse them appropriately (e.g., by using a parsing feature like
905b18
            that provided by <command>getopt</command> command).
905b18
        </para>
905b18
905b18
        <para>
905b18
            In this section will describe how to parse arguments (both
905b18
            option and non-option) inside the
905b18
            <command>centos-art.sh</command> script.  This information
905b18
            must be used as section whenever you need to create a
905b18
            new function for <command>centos-art.sh</command> script.
905b18
        </para>
905b18
905b18
    </section>
905b18
905b18
</section>