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