<sect1 id="scripts-bash-cliref">

    <title>Command-line Interface</title>

    <para>

        The <command>centos-art.sh</command> script follows a

        conventional GNU/Linux command-line interface where there

        might be options and non-option arguments in it. As convention

        to <command>centos-art.sh</command>, the first non-option

        argument passed through the command-line will be the name of

        the specific function you want to execute (e.g., 

        linkend="scripts-bash-render" />, 

        linkend="scripts-bash-locale" />, 

        linkend="scripts-bash-help" />, etc.).  This first argument

        will be immediately removed from the list of arguments passed

        to <command>centos-art.sh</command> script leaving just the

        remaining options and non-option arguments passed to it. From

        this point on, the <command>centos-art.sh</command> script

        uses the <command>getopt</command> command to retrieve option

        arguments and remove them from the list of arguments passed to

        <command>centos-art.sh</command> script.

    </para>

    <para>

        To better understand the <command>centos-art.sh</command>

        command-line interface, consider the command shown in 

        linkend="scripts-bash-cliref-example1" />.  This example

        shows the entire command as a list of space-separated

        arguments. Each argument passed in the command-line can be

        reached using positional variables as described in 

        linkend="scripts-bash-cliref-implementation-example1" />.

    </para>

    <example id="scripts-bash-cliref-example1">

    <title>The command-line interface</title>

    <screenshot>

    <screeninfo>The command-line interface</screeninfo>

    <mediaobject>

    <textobject>

<programlisting>

centos-art render Identity/Images/Themes --with-brands

</programlisting>

    </textobject>

    </mediaobject>

    </screenshot>

    </example>

    <sect2 id="scripts-bash-cliref-options">

    <title>Option Arguments</title>

    <para>

        As convention inside the <command>centos-art.sh</command>, all

        specific function environments should provide support for the

        following option arguments:

    </para>

    <variablelist>

    <varlistentry>

    <term><option>-h</option> | <option>--help</option></term>

    <listitem>

    <para>

        This option makes <command>centos-art.sh</command> to shows

        information about the specific function environment (e.g., how

        to execute it, available options, etc.) set as first

        non-option argument. For example, if you provide the

        <command>centos-art render --help</command>, the

        <command>centos-art.sh</command> script will display to you

        the information related to 

        /> functionality.

    </para>

    <para>

        This information is retrieved from <quote>The CentOS Artwork

        Repository File System (tcar-fs)</quote> documentation manual.

        This manual is written in Texinfo format and provides a quick

        way for you to read and browse documentation related to each

        directory inside &TCAR; as you work with it from a text

        terminal.

    </para>

        Enhancement

        ===========

        At some point, documentation written in Texinfo format will be

        replaced by Docbook format and profiling will be used to reach

        documentation model files which will be also transformed

        automatically based on the output required. In the case of

        centos-art.sh help functionality, man pages will be used as

        default output format.

    -->

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>-q</option> | <option>--quiet</option></term>

    <listitem>

    <para>

        This option makes the <command>centos-art.sh</command> script

        to suppress messages sent to standard output. This option

        doesn't suppress error messages, nor questions related to

        script execution.

    </para>

    </listitem>

    </varlistentry>

    </variablelist>

    <para>

        The specific option arguments used by function environments

        are described individually, as part of each function

        environment documentation.  To know more about the specific

        options used by function environments, see 

        linkend="scripts-bash-cliref-specificfuncs" /> and 

        linkend="scripts-bash-cliref-commonfuncs" />.

    </para>

    <title>Specific functions environment</title>

    <tgroup cols="2" align="left">

        <row>

            <entry>Name</entry>

            <entry>Description</entry>

        </row>

        <row>

            <entry><xref linkend="scripts-bash-prepare" /></entry>

            <entry>Standardize configuration tasks inside &TCAR;</entry>

        </row>

        <row>

            <entry><xref linkend="scripts-bash-render" /></entry>

            <entry>Standardize rendition tasks inside &TCAR;</entry>

        </row>

        <row>

            <entry><xref linkend="scripts-bash-locale" /></entry>

            <entry>Standardize localization tasks inside &TCAR;</entry>

        </row>

        <row>

            <entry><xref linkend="scripts-bash-help" /></entry>

            <entry>Standardize documentation tasks inside &TCAR;</entry>

        </row>

        <row>

            <entry><xref linkend="scripts-bash-pack" /></entry>

            <entry>Standardize packing tasks inside &TCAR;</entry>

        </row>

        <row>

            <entry><xref linkend="scripts-bash-tuneup" /></entry>

            <entry>Standardize maintainance tasks inside &TCAR;</entry>

        </row>

        <row>

            <entry><xref linkend="scripts-bash-vcs" /></entry>

            <entry>Standardize version control tasks inside &TCAR;</entry>

        </row>

    </tgroup>

    <title>Common functions environment</title>

    <tgroup cols="2" align="left">

        <row>

            <entry>Name</entry>

            <entry>Description</entry>

        </row>

        <row>

            <entry>

                <literal>cli_checkFiles</literal>

            </entry>

            <entry>

                Standardize conditional expressions applied to files

                (including links and directories) inside the

                <command>centos-art.sh</command> script.

            </entry>

        </row>

        <row>

            <entry>cli_checkRepoDirSource</entry>

            <entry>

                Standardize directories' path construction inside the

                working copy, using absolute paths.

            </entry>

        </row>

        <row>

            <entry>cli_expandTMarkers</entry>   

            <entry>

                Standardize translation markers construction and their

                related expansion.

            </entry>

        </row>

        <row>

            <entry>cli_exportFunctions</entry>

            <entry>

                Standardize the way specific functionalities are

                exported to <command>centos-art.sh</command> script

                environment.

            </entry>

        </row>

        <row>

            <entry>cli_getConfigLines</entry>

            <entry>

                Standardize the way configuration lines are retrieved

                form configuration files.

            </entry>

        </row>

        <row>

            <entry>cli_getConfigSectionNames</entry>

            <entry>

                Standardize the way section names are retrieved from

                configuration files.

            </entry>

        </row>

        <row>

            <entry>cli_getConfigValue</entry>

            <entry>

                Standardize the way configuration values are retrieved

                from configuration files. 

            </entry>

        </row>

        <row>

            <entry>cli_getFilesList</entry>

            <entry>

                Standardize the way list of files are built inside

                <command>centos-art.sh</command> script.

            </entry>

        </row>

        <row>

            <entry>cli_getPathComponent</entry>

            <entry>

                Standardize the way directory structures are organized

                inside the working copy of &TCAR;.

            </entry>

        </row>

        <row>

            <entry>cli_getRepoName</entry>

            <entry>

                Standardize files and directories name convection

                inside the working copy of &TCAR;.

            </entry>

        </row>

        <row>

            <entry>cli_getTemporalFile</entry>

            <entry>

                Standardize temporal files creation.

            </entry>

        </row>

        <row>

            <entry>cli_parseArgumentsReDef</entry>

            <entry>

                Initiate/reset and sanitize positional parameters

                passed to this function and creates the list of

                arguments that <command>getopt</command> will process.

            </entry>

        </row>

        <row>

            <entry>cli_parseArguments</entry>

            <entry>

                Redefine the <varname>ARGUMENTS</varname> global

                variable using <command>getopt</command> output.

            </entry>

        </row>

        <row>

            <entry>cli_printCopyrightInfo</entry>

            <entry>

                Standardize the copyright information printed on

                content produced by <command>centos-art.sh</command>

                script.

            </entry>

        </row>

        <row>

            <entry>cli_printMailingList</entry>

            <entry>

                Standardize the way mailing list addresses are printed

                on content produced by

                <command>centos-art.sh</command> script.

            </entry>

        </row>

        <row>

            <entry>cli_printMessage</entry>

            <entry>

                Standardize the way messages are printed by

                <command>centos-art.sh</command> script.

            </entry>

        </row>

        <row>

            <entry>cli_printUrl</entry>

            <entry>

                Standardize the way URLs are printed by

                <command>centos-art.sh</command> script. 

            </entry>

        </row>

        <row>

            <entry>cli_runFnEnvironment</entry>

            <entry>

                Standardize the way <command>centos-art.sh</command>

                script is called to itself. 

            </entry>

        </row>

        <row>

            <entry>cli</entry>

            <entry>

                Initiates the <command>centos-art.sh</command> script

                command-line interface.

            </entry>

        </row>

        <row>

            <entry>cli_synchronizeRepoChanges</entry>

            <entry>

                Standardize the way changes are synchronized between

                the working copy and the central repository. 

            </entry>

        </row>

        <row>

            <entry>cli_terminateScriptExecution</entry>

            <entry>

                Standardize the actions that must be realized just

                before leaving the script execution (e.g., cleaning

                temporal files).

            </entry>

        </row>

        <row>

            <entry>cli_unsetFunctions</entry>

            <entry>

                Unset functionalities from

                <command>centos-art.sh</command> script execution

                environment.

            </entry>

        </row>

    </tgroup>

    </sect2>

    <sect2>

    <title>Non-Option Arguments</title>

    <para>

        Once option arguments have been removed from the list of

        arguments passed to <command>centos-art.sh</command>

        command-line, non-option arguments are processed then.

        Non-option arguments will always be paths pointing to

        directories inside your working copy of &TCAR; or

        documentation entries pointing to specific sections in a

        documentation manual. Paths provided in the command-line can

        be absolute or relative considering the root directory of the

        working copy as start point.  For example, both the absolute

        path <quote>

        class="directory">${HOME}/Projects/CentOS/artwork/Identity/Themes/</filename></quote>

        and the relative path <quote>

        class="directory">Identity/Themes</filename></quote> point to

        the same location. Documentation entries, on the other hand,

        exist to specify the files inside the <quote>

        class="directory">Documentation/Models/</filename></quote>

        directory structure you want to work with, based on specific

        documentation manual components (e.g., manual name, part,

        chapter or section). To know more about documentation entries,

        see the <xref linkend="scripts-bash-help"/> functionality

        reference.

    </para>

    </sect2>

    <sect2 id="scripts-bash-cliref-implementation">

        <title>Implementation</title>

        <para>

            The command-line interface of

            <command>centos-art.sh</command> script is implemented

            individually for each specific function environments it is

            made of. Each specific function environment inside the

            <command>centos-art.sh</command> has its own command-line

            definition and can differ in options when they are

            compared one another. The command-line differences between

            specific function environments exist as consequence of the

            purpose they were designed for (e.g., different purposes,

            different options and arguments).  Nevertheless, all

            specific function environments use the same base

            construction to implement their unique command-line

            interfaces (see 

            linkend="scripts-bash-cliref-implementation-example1" />).

        </para>

        <para>

            The specific function environments the

            <command>centos-art.sh</command> script is made of use the

            <quote><filename>Scripts/Bash/Functions/<replaceable>Fname</replaceable>/<replaceable>fname</replaceable>_getOptions.sh</filename></quote>

            file to store the

            <function><replaceable>fname</replaceable>_getOptions</function>

            function definition. This function definition is where you

            set the relation between actions to be executed and

            arguments passed to <command>centos-art.sh</command>

            script.  

        </para>

        <para>

            Basically, when you decide to create new function

            environments for the <command>centos-art.sh</command>

            script, you need to consider whether they will use

            arguments from the command-line or not. When the function

            environment doesn't need arguments (e.g., it exists to

            redefine values related to variables only) there is not

            need to consider a parsing feature for it.  However, when

            you need to interact with a specific function through the

            command-line, you should use the

            <function><replaceable>fname</replaceable>_getOptions</function>

            function related to your

            <function><replaceable>fname</replaceable></function>

            function environment to define the way such interaction

            will take place.  This way you can control the possible

            arguments your function environment will be able to

            interpret from the command-line. 

        </para>

    <example id="scripts-bash-cliref-implementation-example1">

    <title>The command-line implementation</title>

    <screenshot>

    <screeninfo>The command-line implementation</screeninfo>

    <mediaobject>

    <textobject>

<programlisting>

function <replaceable>fname</replaceable>_getOptions {

    # Define short options we want to support.

    local ARGSS="h,q"

    # Define long options we want to support.

    local ARGSL="help,quiet"

    # Redefine ARGUMENTS using getopt(1) command parser.

    cli_parseArguments

    # Redefine positional parameters using ARGUMENTS variable.

    eval set -- "$ARGUMENTS"

    # Look for options passed through command-line.

    while true; do

        case "$1" in

            -h | --help )

                cli_runFnEnvironment help --read --format="texinfo" "tcar-fs::scripts:bash-functions-<replaceable>fname</replaceable>"

                shift 1

                exit

                ;;

            -q | --quiet )

                FLAG_QUIET="true"

                shift 1

                ;;

            -- )

                # Remove the `--' argument from the list of arguments

                # in order for processing non-option arguments

                # correctly. At this point all option arguments have

                # been processed already but the `--' argument still

                # remains to mark ending of option arguments and

                # beginning of non-option arguments. The `--' argument

                # needs to be removed here in order to avoid

                # centos-art.sh script to process it as a path inside

                # the repository, which obviously is not.

                shift 1

                break

                ;;

        esac

    done

    # Redefine ARGUMENTS variable using current positional parameters. 

    cli_parseArgumentsReDef "$@"

}

</programlisting>

</textobject>

</mediaobject>

</screenshot>

</example>

        <para>

            Using the base structure described in 

            linkend="scripts-bash-cliref-implementation-example1"/>, you can

            create new options so your specific function environment

            can express its usefulness.  For example, if you want your

            specific function environment to print a greeting on the

            screen when the <option>--hello</option> option is passed

            through its command-line, you can modify the base

            structure shown above with the following:

        </para>

<programlisting>

...

    # Define long options we want to support.

    local ARGSL="help,quiet,hello"

...

            --hello )

                cli_printMessage "`gettext "Hello World!"`"

                shift 1

                ;;

...

</programlisting>

    <para>

        In case you want to provide an option value in the form

        <option>--hello="World"</option>, you can do it as described

        below:

    </para>

<programlisting>

...

    # Define long options we want to support.

    local ARGSL="help,quiet,hello:"

...

            --hello )

                cli_printMessage "`gettext "Hello"` ${2}"

                shift 2

                ;;

...

</programlisting>

    <para>

        In this last case, the option value is required. So, if you

        provide the <option>--hello</option> option but do not provide

        a value for it, an error will be triggered and the script will

        finish its execution. To make an option value not-required,

        you need to use two colons instead of one when you define the

        options, see the following lines: 

    </para>

<programlisting>

...

    # Define long options we want to support.

    local ARGSL="help,quiet,hello::"

...

            --hello )

                cli_printMessage "`gettext "Hello"` ${2}"

                shift 2

                ;;

...

</programlisting>

    <para>

        To know more about the features provided by

        <command>getopt</command> command, read its man page (e.g.,

        typing the <command>man getopt</command> command in your

        terminal). This information will also help you to understand

        how to improve the command-line interfaces you create for

        the function environments of <command>centos-art.sh</command>

        script.

    </para>

    </sect2>

</sect1>