Blame Manuals/RepoReference/en_US/Directories/trunk/Scripts.texinfo

b32b45
@subheading Goals
b32b45
b32b45
This section provides the automation work line. The automation work
b32b45
line exists to standardize content production in CentOS Artwork
b32b45
Repository.  There is no need to type several tasks, time after time,
b32b45
if they can be programmed into just one executable script.
b32b45
b32b45
In this section you'll find how to organize and extend the
b32b45
@command{centos-art.sh} script, a bash scripts specially designed to
b32b45
automate most frequent tasks in the repository (e.g., image rendition,
b32b45
documenting directory structures, translating content, etc.).  If you
b32b45
can't resist the idea of automating repeatable tasks, then take a look
b32b45
here.
b32b45
b32b45
@subheading Description
b32b45
b32b45
The best way to understand the @command{centos-art.sh} script is
b32b45
studying and improving its source code.  However, as start point, you
b32b45
may prefer to read an introductory resume before diving into the
b32b45
source code details. In this section we identify the different parts
b32b45
the @command{centos-art.sh} script is made of and how these parts
b32b45
interact one another.
b32b45
b32b45
@subsubheading Execution environments
b32b45
b32b45
The @command{centos-art.sh} script is basically made of four execution
b32b45
environments which are named @emph{script}, @emph{global},
b32b45
@emph{specific} and @emph{action}. These execution environments are
b32b45
nested one into another and provide different definition levels for
b32b45
variables and functions.  In this design, variables and functions
b32b45
defined in higher execution environments are available on lower
b32b45
execution environments, but variables and functions defined in lower
b32b45
execution environments are not available for higher execution
b32b45
enviroments.
b32b45
b32b45
@verbatim
b32b45
+----------------------------------------------------------------------+
b32b45
| [centos@host]$ centos-art function path/to/dir --option='value'      |
b32b45
+----------------------------------------------------------------------+
b32b45
| ~/bin/centos-art --> ~/artwork/trunk/Scripts/centos-art.sh           |
b32b45
+---v--------------------------------------------------------------v---+
b32b45
    | centos-art.sh                                                |
b32b45
    +---v------------------------------------------------------v---+
b32b45
    .   | cli $@                                               |   .
b32b45
    .   +---v----------------------------------------------v---+   .
b32b45
    .   .   | cli_getFunctions                             |   .   .
b32b45
    .   .   +---v--------------------------------------v---+   .   .
b32b45
    .   .   .   | function                             |   .   .   .
b32b45
    .   .   .   +---v------------------------------v---+   .   .   .
b32b45
    .   .   .   .   | function_getOptions          |   .   .   .   .
b32b45
    .   .   .   .   | function_doSomething         |   .   .   .   .
b32b45
    .   .   .   .   +------------------------------+   .   .   .   .
b32b45
    .   .   .   .                                      .   .   .   .
b32b45
    .   .   .   .   Execution environment (action)     .   .   .   .
b32b45
    .   .   .   ........................................   .   .   .
b32b45
    .   .   .                                              .   .   .
b32b45
    .   .   .   Execution environment (specific)           .   .   .
b32b45
    .   .   ................................................   .   .
b32b45
    .   .                                                      .   .
b32b45
    .   .   Execution environment (global)                     .   .
b32b45
    .   ........................................................   .
b32b45
    .                                                              .
b32b45
    .   Execution environment (script)                             .
b32b45
    ................................................................
b32b45
@end verbatim
b32b45
b32b45
The script execution environment exists to provide script definitions
b32b45
that can't be set anywhere else inside the script. Example of such
b32b45
definitions include initialization of internationalization through
b32b45
@command{gettext} program, script personal information and
b32b45
initialization of global functionalities.
b32b45
b32b45
The global execution environment exists to provide definitions that
b32b45
can't be set anywhere else inside the script. Example of such
b32b45
definitions include initialization of functionalities (e.g.,
b32b45
@code{cli_printMessage}, @code{cli_getCurrentLocale},
b32b45
@code{cli_checkFiles}, etc.) and variables (e.g., @var{FUNCNAM},
b32b45
@var{FUNCDIR}, @var{FUNCDIRNAM}, @var{ARGUMENTS}, etc.) that can be
b32b45
both used on specific and action execution environments, only.
b32b45
b32b45
The specific execution environment exists to provide definitions that
b32b45
can't be set anywhere else inside the script. Example of such
b32b45
definitions include initialization of specifc functionalities (e.g.,
b32b45
@code{render}, @code{help}, @code{locale}, etc.) and specific
b32b45
variables (@var{ACTIONNAM}, @var{ACTIONVAL}, etc.) that can be used on
b32b45
action execution environment only.
b32b45
b32b45
The action execution environment exists to perform the script actions
b32b45
themselves. It is here where we perform content rendition, content
b32b45
documentation, content localization and whatever action you plan for
b32b45
the @command{centos-art.sh} script to perform. For example, if you
b32b45
passed the @code{render} value as first argument to
b32b45
@command{centos-art.sh} command-line, the script performs the content
b32b45
rendition action through the @code{render} function which is defined
b32b45
in the @file{render.sh} file under
b32b45
@file{trunk/Scripts/Functions/Render} directory. Is there, inside
b32b45
@code{render} functionality were the action execution environment
b32b45
takes place exactly.
b32b45
b32b45
@subsubheading Command-line interface
b32b45
b32b45
When the @command{centos-art} command is executed in a bash terminal,
b32b45
the bash interpreter uses the @env{PATH} environment variable to find
b32b45
where such command is. In order to run the @command{centos-art}, it
b32b45
must exist either as a link to an executable file or an executable
b32b45
file by its own, in any of the paths provided by @env{PATH}
b32b45
environment variable.  Otherwise, the bash interpreter will print an
b32b45
error message and prompt you back to type a valid command.
b32b45
b32b45
By default, after installing The CentOS Distribution, there is no
b32b45
@command{centos-art} command available in the @env{PATH} environment
b32b45
variable for you to execute.  The @command{centos-art} command is made
b32b45
available in your workstation as result of executing the
b32b45
@code{prepare} functionality of @command{centos-art.sh} script
b32b45
(@pxref{Directories trunk Scripts Functions Prepare}) which requires
b32b45
you had previously downloaded a working copy of CentOS Artwork
b32b45
Repository in your workstation.
b32b45
b32b45
When the @command{centos-art} is executed, the first positional
b32b45
parameter passed is required and represents the name of the function
b32b45
you want to perform (e.g., @code{render} for content rendition,
b32b45
@code{locale} for content localization, etc.).  Beyond the first
b32b45
positional parameter you can provide either option or non-option
b32b45
parameters in no specific order. There are also, option parameters
b32b45
with arguments and without arguments. Frequently, non-option paramters
b32b45
are used to specify the path location inside the repository where the
b32b45
function will be performed in (e.g., the directory structure do you
b32b45
want to produce content for) and option parameters to specify how such
b32b45
functionality is performed (e.g., do you want to go quietly?  do you
b32b45
want to do filtering?  etc.).
b32b45
b32b45
@verbatim
b32b45
    A         B         C              D           E
b32b45
---------- ------- ----------- ---------------- -------
b32b45
centos-art funcnam path/to/dir --filter='regex' --quiet
b32b45
---------- ------- ----------- ---------------- -------
b32b45
b32b45
    A = The centos-art.sh script command-line.
b32b45
    B = The centos-art.sh function name.
b32b45
    C = Non-option parameter.
b32b45
    D = Option parameter (with argument).
b32b45
    E = Option parameter (without argument).
b32b45
@end verbatim
b32b45
b32b45
@subsubheading Parsing command-line options
b32b45
b32b45
The action of parsing options is performed through @command{getopt}
b32b45
and results particularly interesting. @command{getopt} breaks up
b32b45
(parse) options in command lines and checks for legal options using
b32b45
the GNU @code{getopt} routines to do this. One important consideration
b32b45
on @command{centos-art.sh} script design is that positional parameters
b32b45
are retrived in the @code{cli} function but parsed on each specific
b32b45
function, individually. There isn't a big parsing definition to cover
b32b45
all specific functions, but one parsing definitions for each specific
b32b45
functions.
b32b45
b32b45
@subheading Usage
b32b45
b32b45
@itemize
b32b45
@item @xref{Directories trunk Scripts Functions}.
b32b45
@end itemize
b32b45
b32b45
@subheading See also
b32b45
b32b45
@itemize
b32b45
@item @ref{Directories trunk}
b32b45
@end itemize