<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., <xref
linkend="scripts-bash-render" />, <xref
linkend="scripts-bash-locale" />, <xref
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 <xref
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 <xref
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 <xref linkend="scripts-bash-render"
/> 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 <xref
linkend="scripts-bash-cliref-specificfuncs" /> and <xref
linkend="scripts-bash-cliref-commonfuncs" />.
</para>
<table id="scripts-bash-cliref-specificfuncs">
<title>Specific functions environment</title>
<tgroup cols="2" align="left">
<thead>
<row>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<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>
</tbody>
</tgroup>
</table>
<table id="scripts-bash-cliref-commonfuncs">
<title>Common functions environment</title>
<tgroup cols="2" align="left">
<thead>
<row>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<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>
</tbody>
</tgroup>
</table>
</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><filename
class="directory">${HOME}/Projects/CentOS/artwork/Identity/Themes/</filename></quote>
and the relative path <quote><filename
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><filename
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 <xref
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 <xref
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>