Blame Manuals/Repository/trunk/Scripts/Bash/Functions.texi

4c79b5
@subsection Goals
4c79b5
6c4982
The @file{trunk/Scripts/Bash/Functions} directory exists to organize
6c4982
@file{centos-art.sh} specific functionalities.
4c79b5
4c79b5
@subsection Description
4c79b5
6c4982
The specific functions of @file{centos-art.sh} script are designed
6c4982
with ``Software Toolbox'' philosophy (@pxref{Toolbox
6c4982
introduction,,,coreutils.info}) in mind: each program ``should do one
6c4982
thing well''.  Inside @file{centos-art.sh} script, each specific
6c4982
functionality is considered a program that should do one thing well.
6c4982
Of course, if you find that they still don't do it, feel free to
6c4982
improve them in order for them to do so.
6c4982
6c4982
The specific functions of @file{centos-art.sh} script are organized
6c4982
inside specific directories under @file{trunk/Scripts/Bash/Functions}
6c4982
location. Each specific function directory should be named as the
6c4982
function it represents, with the first letter in uppercase. For
41f1ec
example, if the function name is @code{render}, the specific function
6c4982
directory for it would be @samp{trunk/Scripts/Bash/Functions/Render}.
6c4982
6c4982
To better understand how specific functions of @file{centos-art.sh}
6c4982
script are designed, lets create one function which only goal is to
6c4982
output different kind of greetings to your screen.
6c4982
2bb528
When we create specific functions for @file{centos-art.sh} script it
2bb528
is crucial to know what these functions will do exactly and if there
2bb528
is any function that already does what we intend to do. If there is no
6c4982
one, it is good time to create them then. Otherwise, if
6c4982
functionalities already available don't do what you exactly expect,
6c4982
contact their authors and work together to improve them.
6c4982
6c4982
@quotation
be6bef
@strong{Tip} Join CentOS developers mailing list
2bb528
@email{centos-art@@centos.org} to share your ideas.
6c4982
@end quotation
6c4982
915635
It is also worth to know what global functions and variables do we
915635
have available inside @file{centos-art.sh} script, so advantage can be
915635
taken from them. Global variables are defined inside global function
915635
scripts. Global functions scripts are stored immediatly under
915635
@file{trunk/Scripts/Bash/Functions} directory, in files begining with
2bb528
@samp{cli} prefix.
6c4982
2bb528
OK, let's begin with our functionality example.
6c4982
be6bef
What function name do we use? Well, lets use @code{greet}. Note that
2bb528
@samp{hello} word is not a verb; but an expression, a kind of
2bb528
greeting, an interjection specifically. In contrast, @samp{greet} is a
2bb528
verb and describes what we do when we say @samp{Hello!}, @samp{Hi!},
2bb528
and similar expressions.
be6bef
6c4982
So far, we've gathered the following function information:
6c4982
6c4982
@verbatim
6c4982
Name: greet
6c4982
Path: trunk/Scripts/Bash/Functions/Greet
6c4982
File: trunk/Scripts/Bash/Functions/Greet/greet.sh
6c4982
@end verbatim
6c4982
41f1ec
The @file{greet.sh} function script is the first file
41f1ec
@file{centos-art.sh} script loads when the @samp{greet} functionality
41f1ec
is called using commands like @samp{centos-art greet --hello='World'}.
be6bef
The @file{greet.sh} function script contains the @code{greet} function
41f1ec
definition. 
41f1ec
2bb528
Inside @file{centos-art.sh} script, as convenction, each function
2bb528
script has one top commentary, followed by one blank line, and then
2bb528
one function defintion below it only.
6c4982
915635
Inside @file{centos-art.sh} script functions, top commentaries have
915635
the following components: the functionality description, one-line for
915635
copyright note with your personal information,  the license under
915635
which the function source code is released ---the @file{centos-art.sh}
6a9758
script is released as GPL, so do all its functions---, the @code{$Id$}
6a9758
keyword of Subversion is later expanded by @command{svn propset}
915635
command.
41f1ec
2bb528
In our @code{greet} function example, top commentary for
2bb528
@file{greet.sh} function script would look like the following:
6c4982
6c4982
@verbatim
6c4982
#!/bin/bash
6c4982
#
6c4982
# greet.sh -- This function outputs different kind of greetings to
6c4982
# your screen. Use this function to understand how centos-art.sh
6c4982
# script specific functionalities work.
6c4982
#
be6bef
# Copyright (C) YEAR YOURFULLNAME
6c4982
#
6c4982
# This program is free software; you can redistribute it and/or modify
6c4982
# it under the terms of the GNU General Public License as published by
6c4982
# the Free Software Foundation; either version 2 of the License, or
6c4982
# (at your option) any later version.
6c4982
# 
6c4982
# This program is distributed in the hope that it will be useful, but
6c4982
# WITHOUT ANY WARRANTY; without even the implied warranty of
6c4982
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
6c4982
# General Public License for more details.
6c4982
#
6c4982
# You should have received a copy of the GNU General Public License
6c4982
# along with this program; if not, write to the Free Software
6c4982
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
6c4982
# USA.
6c4982
# 
6c4982
# ----------------------------------------------------------------------
be6bef
# $Id$
6c4982
# ----------------------------------------------------------------------
6c4982
@end verbatim
6c4982
2bb528
After top commentary, separated by one blank line, the @code{greet}
2bb528
function definition would look like the following:
6c4982
6c4982
@verbatim
6c4982
function greet {
6c4982
6c4982
    # Define global variables.
6c4982
6c4982
    # Define command-line interface.
6c4982
    greet_getActions
6c4982
6c4982
}
6c4982
@end verbatim
6c4982
41f1ec
The first definition inside @code{greet} function, are global
41f1ec
variables that will be available along @code{greet} function execution
41f1ec
environment. This time we didn't use global variable definitions for
41f1ec
@code{greet} function execution environment, so we left that section
41f1ec
empty.
6c4982
41f1ec
Later, we call @code{greet_getActions} function to define the
583d5d
command-line interface of @code{greet} functionality. The command-line
583d5d
interface of @code{greet} functionality defines what and how actions
583d5d
are performed, based on arguments combination passed to
2bb528
@file{centos-art.sh} script.
6c4982
6c4982
@verbatim
6c4982
function greet_getActions {
6c4982
06717d
    case "$ACTIONNAM" in
6c4982
6c4982
        --hello )
6c4982
            greet_doHello
6c4982
            ;;
6c4982
6c4982
        --bye )
6c4982
            greet_doBye
6c4982
            ;;
6c4982
6c4982
        * )
6c4982
            cli_printMessage "`gettext "The option provided is not valid."`"
6c4982
            cli_printMessage "$(caller)" 'AsToKnowMoreLine'
6c4982
6c4982
    esac
6c4982
6c4982
}
6c4982
@end verbatim
6c4982
06717d
The @var{ACTIONNAM} global variable is defined in @file{cli.sh}
41f1ec
function script and contains the value passed before the equal sign
41f1ec
(i.e., @samp{=}) in the second command-line argument of
41f1ec
@file{centos-art.sh} script. For example, if the second command-line
06717d
argument is @option{--hello='World'}, the value of @var{ACTIONNAM}
41f1ec
variable would be @samp{--hello}.  Using this configuration let us
e1a26a
deside which action to perform based on the action name passed to
41f1ec
@file{centos-art.sh} script as second argument. 
41f1ec
2bb528
The @code{greet} function definition makes available two valid
2bb528
greetings through @option{--hello} and @option{--bye} options.  If no
2bb528
one of them is provided as second command-line argument, the @samp{*}
2bb528
case is evaluated instead. 
41f1ec
f7b7e3
The @samp{*} case and its two lines further on should always be
f7b7e3
present in @file{_getActions.sh} function scripts, no matter what
f7b7e3
specific functionality you are creating. This convenction helps the
583d5d
user to find out documentation about current functionality in use,
583d5d
when no valid action is provided.
41f1ec
41f1ec
The @code{greet_doHello} and @code{greet_doBye} function definitions
41f1ec
are the core of @code{greet} specific functionality.  In such function
41f1ec
definitions we set what our @code{greet} function really does: to
41f1ec
output different kinds of greetings.
6c4982
6c4982
@verbatim
6c4982
function greet_doHello {
6c4982
06717d
    cli_printMessage "`gettext "Hello"` $ACTIONVAL"
6c4982
6c4982
}
6c4982
@end verbatim
6c4982
be6bef
The @code{greet_doHello} function definition is stored in
be6bef
@file{greet_doHello.sh} function script. 
be6bef
6c4982
@verbatim
6c4982
function greet_doBye {
6c4982
06717d
    cli_printMessage "`gettext "Goodbye"` $ACTIONVAL"
6c4982
6c4982
}
6c4982
@end verbatim
6c4982
be6bef
The @code{greet_doBye} function definition is stored in the
be6bef
@file{greet_doBye.sh} function script. 
be6bef
be6bef
Both @file{greet_doHello.sh} and @file{greet_doBye.sh} function
6a9758
scripts are stored inside @code{greet} function directory path (i.e.
be6bef
@file{trunk/Scripts/Bash/Functions/Greet}).
be6bef
06717d
The @var{ACTIONVAL} global variable is defined in @file{cli.sh}
41f1ec
function script and contains the value passed after the equal sign
41f1ec
(i.e., @samp{=}) in the second command-line argument of
41f1ec
@file{centos-art.sh} script. For example, if the second command-line
06717d
argument is @option{--hello='World'}, the value of @var{ACTIONVAL}
41f1ec
variable would be @samp{World} without quotes.
6c4982
be6bef
Let's see how @code{greet} specific functionality files are organzied
6a9758
under @code{greet} function directory. To see file organization we use
6a9758
the @command{tree} command:
6c4982
6c4982
@verbatim
6c4982
trunk/Scripts/Bash/Functions/Greet
6c4982
|-- greet_doBye.sh
6c4982
|-- greet_doHello.sh
6c4982
|-- greet_getActions.sh
6c4982
`-- greet.sh
6c4982
@end verbatim
6c4982
2bb528
To try the @code{greet} specific functionality we've just created,
2bb528
pass the function name (i.e., @samp{greet}) as first argument to
2bb528
@file{centos-art.sh} script, and any of the valid options as second
2bb528
argument. Some examples are illustrated below:
6c4982
6c4982
@verbatim
6c4982
[centos@projects ~]$ centos-art greet --hello='World'
6c4982
Hello World
6c4982
[centos@projects ~]$ centos-art greet --bye='World'
6c4982
Goodbye World
6c4982
[centos@projects ~]$ 
6c4982
@end verbatim
6c4982
41f1ec
The word @samp{World} in the examples above can be anything. In fact,
41f1ec
change it to have a little fun.
be6bef
be6bef
Now that we have a specific function that works as we expect, it is
583d5d
time to document it.  To document @code{greet} specific functionality,
831389
we use its directory path and the @code{manual} functionality
035049
(@pxref{trunk Scripts Bash Functions Manual}) of @file{centos-art.sh}
831389
script, just as the following command illustrates: 
be6bef
be6bef
@verbatim
f7b7e3
centos-art manual --edit=trunk/Scripts/Bash/Functions/Greet
be6bef
@end verbatim
be6bef
583d5d
To have a well documented function helps user to understand how your
583d5d
function really works, and how it should be used.  When no valid
583d5d
action is passed to a function, the @file{centos-art.sh} script uses
af2893
the function documentation entry as vehicle to communicate which the
583d5d
valid functions are. When no documentation entry exists for a
c1fd2e
function, the @file{centos-art.sh} script informs that no
c1fd2e
documentation entry exists for such function and requests user to
c1fd2e
create it right at that time.
583d5d
41f1ec
Now that we have documented our function, it is time to translate its
41f1ec
output messages to different languages. To translate specific
41f1ec
functionality output messages to different languages we use the
41f1ec
@code{locale} functionality (@pxref{trunk Scripts Bash Functions
41f1ec
Locale}) of @file{centos-art.sh} script, just as the following command
41f1ec
illustrates:
41f1ec
41f1ec
@verbatim
41f1ec
centos-art locale --edit
41f1ec
@end verbatim
41f1ec
41f1ec
@quotation
41f1ec
@strong{Warning} To translate output messages in different languages,
41f1ec
your system locale information ---as in @env{LANG} environment
41f1ec
variable--- must be set to that locale you want to produce translated
41f1ec
messages for. For example, if you want to produce translated messages
41f1ec
for Spanish language, your system locale information must be set to
583d5d
@samp{es_ES.UTF-8}, or similar, first.
41f1ec
@end quotation
41f1ec
be6bef
Well, it seems that our example is rather complete by now. 
6c4982
41f1ec
In @code{greet} function example we've described so far, we only use
41f1ec
@command{cli_printMessage} global function in action specific function
583d5d
definitions in order to print messages, but more interesting things
583d5d
can be achieved inside action specific function definitions.  For
583d5d
example, if you pass a directory path as action value in second
583d5d
argument, you could retrive a list of files from therein, and process
2bb528
them. If the list of files turns too long or you just want to control
2bb528
which files to process, you could add the third argument in the form
2bb528
@option{--filter='regex'} and reduce the amount of files to process
2bb528
using a regular expression pattern.
6c4982
2bb528
The @code{greet} function described in this section may serve you as
2bb528
an introduction to understand how specific functionalities work inside
2bb528
@file{centos-art.sh} script. With some of luck this introduction will
2bb528
also serve you as motivation to create your own @file{centos-art.sh}
2bb528
script specific functionalities.
6c4982
be6bef
By the way, the @code{greet} functionality doesn't exist inside
41f1ec
@file{centos-art.sh} script yet. Would you like to create it?
6c4982
6c4982
@subsection Usage
6c4982
6c4982
@subsubsection Global variables
6c4982
6c4982
The following global variables of @file{centos-art.sh} script, are
6c4982
available for you to use inside specific functions:
6c4982
be6bef
@defvar TEXTDOMAIN
6c4982
Default domain used to retrieve translated messages. This value is set
2bb528
in @file{initFunctions.sh} and shouldn't be changed.
be6bef
@end defvar
6c4982
be6bef
@defvar TEXTDOMAINDIR
6c4982
Default directory used to retrieve translated messages. This value is
2bb528
set in @file{initFunctions.sh} and shouldn't be changed.
be6bef
@end defvar
6c4982
06717d
@defvar FUNCNAM
e1a26a
Define function name.
e1a26a
e1a26a
Function names associate sets of actions. There is one set of actions
e1a26a
for each unique function name inside @file{centos-art.sh} script.
e1a26a
e1a26a
Dunction names are passed as first argument in @file{centos-art.sh}
2bb528
command-line interface. For example, in the command @samp{centos-art
2bb528
render --entry=path/to/dir --filter=regex}, the @var{ACTION} passed to
2bb528
@file{centos-art.sh} script is @option{render}.
e1a26a
e1a26a
When first argument is not provided, the @file{centos-art.sh} script
e1a26a
immediatly ends its execution.
be6bef
@end defvar
6c4982
6414c4
@defvar FUNCDIR
6414c4
@end defvar
6414c4
6414c4
@defvar FUNCDIRNAME
6414c4
@end defvar
6414c4
6414c4
@defvar FUNCSCRIPT
6414c4
@end defvar
6414c4
6414c4
@defvar FUNCCONFIG
6414c4
@end defvar
6414c4
06717d
@defvar ACTIONNAM
e1a26a
Define action name.
e1a26a
e1a26a
Each action name identifies an specific action to perform, inside an
e1a26a
specific function.
e1a26a
e1a26a
Action name names aare passed as second argument in
e1a26a
@file{centos-art.sh} command-line interface. For example, in the
e1a26a
command @samp{centos-art render --entry=path/to/dir --filter=regex},
e1a26a
the @var{ACTIONNAM} passed to @file{centos-art.sh} script is
e1a26a
@option{--entry}.
e1a26a
e1a26a
When second argument is not provided, the @file{centos-art.sh} script
e1a26a
immediatly ends its execution.
be6bef
@end defvar
6c4982
06717d
@defvar ACTIONVAL
e1a26a
Define action value.
e1a26a
e1a26a
Action values are associated to just one action name. Action values
6414c4
contain the working copy entry over which its associated action will be
6414c4
performed in.  Working copy entries can be files or directories inside
6414c4
the working copy.
be6bef
@end defvar
6c4982
be6bef
@defvar REGEX
e1a26a
Define regular expression used as pattern to build the list of files
e1a26a
to process.
2bb528
e1a26a
By default, @var{REGEX} variable is set to @code{.+} to match all
e1a26a
files.
2bb528
e1a26a
Functions that need to build a list of files to process use the option
e1a26a
@option{--filter} to redefine @var{REGEX} variable default value, and
e1a26a
so, control the amount of files to process.
be6bef
@end defvar
6c4982
97552b
@defvar ARGUMENTS 
97552b
Define optional arguments. 
97552b
008ee0
Optional arguments, inside @file{centos-art.sh} script, are considered
008ee0
as all command-line arguments passed to @file{centos-art.sh} script,
008ee0
from third argument position on. For example, in the command
008ee0
@samp{centos-art render --entry=path/to/dir --filter=regex} , the
008ee0
optional arguments are from @samp{--filter=regex} argument on.
008ee0
008ee0
Optional arguments are parsed using @command{getopt} command through
008ee0
the following base construction: 
008ee0
008ee0
@verbatim
008ee0
# Define short options we want to support.
008ee0
local ARGSS=""
008ee0
008ee0
# Define long options we want to support.
008ee0
local ARGSL="filter:,to:"
008ee0
008ee0
# Parse arguments using getopt(1) command parser.
008ee0
cli_doParseArguments
008ee0
008ee0
# Reset positional parameters using output from (getopt) argument
008ee0
# parser.
008ee0
eval set -- "$ARGUMENTS"
008ee0
008ee0
# Define action to take for each option passed.
008ee0
while true; do
008ee0
    case "$1" in
008ee0
        --filter )
008ee0
            REGEX="$2" 
008ee0
            shift 2
008ee0
            ;;
008ee0
        --to )
008ee0
            TARGET="$2" 
008ee0
            shift 2
008ee0
            ;;
008ee0
        * )
008ee0
            break
008ee0
    esac
008ee0
done
008ee0
@end verbatim
008ee0
008ee0
Optional arguments provide support to command options inside
008ee0
@file{centos-art.sh} script. For instance, consider the Subversion
008ee0
(@command{svn}) command, where there are many options (e.g.,
008ee0
@option{copy}, @option{delete}, @option{move}, etc), and inside each
008ee0
option there are several modifiers (e.g., @samp{--revision},
008ee0
@samp{--message}, @samp{--username}, etc.) that can be combined one
008ee0
another in their short or long variants. 
008ee0
008ee0
The @var{ARGUMENTS} variable is used to store arguments passed from
008ee0
command-line for later use inside @file{centos-art.sh} script. Storing
008ee0
arguments is specially useful when we want to run a command with some
008ee0
specific options from them. Consider the following command:
008ee0
008ee0
@verbatim
008ee0
centos-art path --copy=SOURCE --to=TARGET --message="The commit message goes here." --username='johndoe'
008ee0
@end verbatim
008ee0
008ee0
In the above command, the @option{--message}, and @option{--username}
008ee0
options are specific to @command{svn copy} command. In such cases,
008ee0
options are not interpreted by @file{centos-art.sh} script itself.
008ee0
Instead, the @file{centos-art.sh} script uses @command{getopt} to
8c6b8a
retrive them and store them in the @var{ARGUMENTS} variable for later
008ee0
use, as described in the following command:
008ee0
008ee0
@verbatim
008ee0
# Build subversion command to duplicate locations inside the
008ee0
# workstation.
008ee0
eval svn copy $SOURCE $TARGET --quiet $ARGUMENTS
008ee0
@end verbatim
008ee0
008ee0
When @command{getopt} parses @var{ARGUMENTS}, we may use short options
008ee0
(e.g., @option{-m}) or long options (e.g., @option{--message}). When
008ee0
we use short options, arguments are separated by one space from the
008ee0
option (e.g., @option{-m 'This is a commit message.'}).  When we use
008ee0
long options arguments are separated by an equal sign (@samp{=})
008ee0
(e.g., @option{--message='This is a commit message'}).
008ee0
008ee0
In order for @command{getopt} to parse @var{ARGUMENTS} correctly, it
008ee0
is required to provide the short and long definition of options that
008ee0
will be passed or at least supported by the command performing the
008ee0
final action the function script exists for.
008ee0
008ee0
As convenction, inside @file{centos-art.sh} script, short option
008ee0
definitions are set in the @var{ARGSS} variable; and long option
008ee0
definitions are set in the @var{ARGSL} variable.
008ee0
008ee0
When you define short and long options, it may be needed to define
008ee0
which of these option arguments are required and which not. To define
008ee0
an option argument as required, you need to set one colon @samp{:}
008ee0
after the option definition (e.g., @option{-o m: -l message:}).  On
008ee0
the other hand, to define an option argument as not required, you need
008ee0
to set two colons @samp{::} after the option definition (e.g.,
008ee0
@option{-o m:: -l message::}).
97552b
@end defvar
97552b
be6bef
@defvar EDITOR 
2bb528
Default text editor. 
2bb528
2bb528
The @file{centos-art.sh} script uses default text @env{EDITOR} to edit
2bb528
pre-commit subversion messages, translation files, configuration
2bb528
files, script files, and similar text-based files.
2bb528
2bb528
If @env{EDITOR} environment variable is not set, @file{centos-art.sh}
2bb528
script uses @file{/usr/bin/vim} as default text editor. Otherwise, the
2bb528
following values are recognized by @file{centos-art.sh} script:
6c4982
4c79b5
@itemize
2bb528
@item @file{/usr/bin/vim}
2bb528
@item @file{/usr/bin/emacs}
2bb528
@item @file{/usr/bin/nano}
4c79b5
@end itemize
2bb528
2bb528
If no one of these values is set in @env{EDITOR} environment variable,
2bb528
@file{centos-art.sh} uses @file{/usr/bin/vim} text editor by default. 
be6bef
@end defvar
6c4982
200d3f
@subsubsection Global functions
6c4982
58112f
Function scripts stored directly under
b864c5
@file{trunk/Scripts/Bash/Functions/} directory are used to define
58112f
global functions.  Global functions can be used inside action specific
b864c5
functionalities and or even be reused inside themselves. This section
f7b7e3
provides introductory information to global functions you can use
f7b7e3
inside @file{centos-art.sh} script.
6c4982
200d3f
@defun cli_checkActionArguments
79adfc
Validate action value (@var{ACTIONVAL}) variable.
79adfc
58112f
The action value variable can take one of the following values:
58112f
58112f
@enumerate
58112f
@item Path to one directory inside the local working copy,
58112f
@item Path to one file inside the local working copy,
58112f
@end enumerate
58112f
58112f
If another value different from that specified above is passed to
58112f
action value variable, the @file{centos-art.sh} script prints an error
6414c4
message and ends script execution.
200d3f
@end defun
200d3f
200d3f
@defun cli_checkFiles FILE [TYPE]
200d3f
Verify file existence.
200d3f
200d3f
@code{cli_checkFiles} receives a @var{FILE} absolute path and performs
200d3f
file verification as specified in @var{TYPE}.  When @var{TYPE} is not
200d3f
specified, @code{cli_checkFiles} verifies @var{FILE} existence, no
200d3f
matter what kind of file it be.  If @var{TYPE} is specified, use one
200d3f
of the following values:
200d3f
200d3f
@table @option
200d3f
@item d
200d3f
@itemx directory
200d3f
Ends script execution if @var{FILE} is not a directory.
200d3f
200d3f
When you verify directories with cli_checkFiles, if directory doesn't
200d3f
exist, @file{centos-art.sh} script asks you for confirmation in order
200d3f
to create that directory. If you answer positively,
200d3f
@file{centos-art.sh} script creates that directory and continues
200d3f
script flows normally. Otherwise, if you answer negatively,
200d3f
@file{centos-art.sh} ends script execution with an error and
200d3f
documentation message.
200d3f
200d3f
@item f
200d3f
@item regular-file
200d3f
Ends script execution if @var{FILE} is not a regular file.
200d3f
@item h
200d3f
@itemx symbolic-link
200d3f
Ends script execution if @var{FILE} is not a symbolic link.
200d3f
@item x
200d3f
@itemx execution
200d3f
Ends script execution if @var{FILE} is not executable.
200d3f
@item fh
200d3f
Ends script execution if @var{FILE} is neither a regular file nor a
200d3f
symbolic link.
200d3f
@item fd
200d3f
Ends script execution if @var{FILE} is neither a regular file nor a
200d3f
directory.
2569a8
@item isInWorkingCopy
2569a8
Ends script execution if @var{FILE} is not inside the working copy.
200d3f
@end table
200d3f
200d3f
As default behaviour, if @var{FILE} passes all verifications,
200d3f
@file{centos-art.sh} script continues with its normal flow. 
200d3f
@end defun
200d3f
97552b
@defun cli_commitRepoChanges [LOCATION]
06717d
06717d
Syncronize changes between repository and working copy.
06048d
06048d
The @code{cli_commitRepoChanges} function brings changes from the
f7b7e3
central repository down to the working copy---using @command{svn
f7b7e3
update}---, checks the working copy changes---using @command{svn
f7b7e3
status} command---, prints status report---using both @command{svn
f7b7e3
update} and @command{svn status} commands output, and finally, commits
f7b7e3
recent changes from the working copy up to the repository---using
e1a26a
@command{svn commit} command---.
06048d
f7b7e3
Previous to commit the working copy changes up to the central
f7b7e3
repository, the @code{cli_commitRepoChanges} function asks you to
f7b7e3
verify changes---using @command{svn diff} command---, and later,
f7b7e3
another confirmation question is shown to be sure you really want to
f7b7e3
commit changes up to central repository.
f7b7e3
f7b7e3
If @var{LOCATION} argument is not specified, the value of
f7b7e3
@var{ACTIONVAL} variable is used as reference instead.
06717d
06717d
@float Figure, trunk/Scripts/Bash/Functions/cli_commitRepoChanges
06717d
@verbatim
06717d
----------------------------------------------------------------------
06717d
--> Bringing changes from the repository into the working copy
06717d
--> Checking changes in the working copy
06717d
----------------------------------------------------------------------
06717d
Added           0 file from the repository.
06717d
Deleted         0 file from the repository.
06717d
Updated         0 file from the repository.
06717d
Conflicted      0 file from the repository.
06717d
Merged          0 file from the repository.
06717d
Modified        4 files from the working copy.
06717d
Unversioned     0 file from the working copy.
06717d
Deleted         0 file from the working copy.
06717d
Added           0 file from the working copy.
06717d
----------------------------------------------------------------------
06717d
@end verbatim
06717d
@caption{The @code{cli_commitRepoChanges} function output.}
06717d
@end float
06048d
06717d
Call the @code{cli_commitRepoChanges} function before or/and after
f7b7e3
calling functions that modify files or directories inside the working
f7b7e3
copy as you may need to.  
be6bef
@end defun
be6bef
200d3f
@defun cli_doParseArguments
58112f
Redefine arguments (@var{ARGUMENTS}) global variable using
79adfc
@command{getopt} command output. For more information about how to use
79adfc
@code{cli_doParseArguments} function, see @var{ARGUMENTS} variable
79adfc
description above.
200d3f
@end defun
be6bef
68917e
@defun cli_doParseArgumentsReDef $@@
79adfc
Initialize/reset arguments (@var{ARGUMENTS}) global variable using
79adfc
positional parameters variable (@var{$@@}) as reference.
79adfc
68917e
When we work inside function definitions, positional parameters are
68917e
reset to the last function definition positional parameters.  If you
68917e
need to redefine positional parameters from one specific function, you
68917e
need to call @code{cli_doParseArgumentsReDef} with the positional
68917e
parameters variable (@var{$@@}), set as first argument, to that
68917e
specific function you want to redefine positional parameters at.
200d3f
@end defun
2bb528
68917e
@defun cli_getArguments
96baa8
96baa8
Initialize function name (@var{FUNCNAM}), action name
96baa8
(@var{ACTIONNAM}), and action value (@var{ACTIONVAL}) global
96baa8
variables, using positional parameters passed in @var{$@@} variable.
96baa8
0d7dfc
The @code{cli_getArguments} function is called from @code{cli.sh}
6a9758
function script, using @code{cli} function positional parameters
0d7dfc
(i.e., the positional parameters passed as arguments in the
58112f
command-line) as first function argument. 
96baa8
58112f
Once command-line positional parameters are accesible to
58112f
@file{centos-art.sh} script execution evironment,
0d7dfc
@code{cli_getArguments} uses regular expression to retrive
96baa8
action variables from first and second argument. The first argument
58112f
defines the value used as function name (@var{FUNCNAM}), and the
58112f
second argument defines both values used as action name
58112f
(@var{ACTIONNAM}) and action value (@var{ACTIONVAL}), respectively.
96baa8
96baa8
The first argument is a word in lower case. This word specifies the
96baa8
name of the functionality you want to use (e.g., @samp{render} to
58112f
render images, @samp{manual} to work on documentation, and so on.)
96baa8
96baa8
The second argument has a long option style (e.g.,
96baa8
@samp{--option=value}). The @samp{--option} represents the action name
58112f
(@var{ACTIONNAM}), and the characters inbetween the equal sign
58112f
(@samp{=}) and the first space character, are considered as the action
96baa8
value (@var{ACTIONVAL}). In order to provide action values with space
58112f
characters inbetween you need to enclose action value with quotes like
58112f
in @samp{--option='This is long value with spaces inbetween'}.
58112f
Generally, action values are used to specify paths over which the
58112f
action name acts on.
96baa8
96baa8
Once action related variables (i.e., @var{FUNCNAM}, @var{ACTIONNAM},
96baa8
and @var{ACTIONVAL}) are defined and validated,
0d7dfc
@code{cli_getArguments} shifts the positional arguments to remove the
0d7dfc
first two arguments passed (i.e., those used to retrive action related
0d7dfc
variables) and redefine the arguments (@var{ARGUMENTS}) global
0d7dfc
variable with the new positional parameters information.
200d3f
@end defun
2bb528
0d7dfc
@defun cli_getFunctions
630254
Initialize funtionalities supported by @file{centos-art.sh} script.
630254
630254
Functionalities supported by @file{centos-art.sh} script are organized
630254
in functionality directories under
630254
@file{trunk/Scripts/Bash/Functions/} directory. Each functionality
630254
directory stores function scripts to the functionality such directory
630254
was created for. Function scripts contain function definitions.
630254
Function definitions contain several commands focused on achieving one
a69d1a
specific task only (i.e., the one such functionality was created for).
630254
a69d1a
In order for @file{centos-art.sh} script to recognize a functionality,
a69d1a
such functionality needs to be stored under
630254
@file{trunk/Scripts/Bash/Functions/} in a directory written
630254
capitalized (i.e., the whole name is written in lowercase except the
630254
first character which is in uppercase). The directory where one
630254
specific functionality is stored is known as the @samp{functionality
630254
directory}. 
630254
630254
Inside each functionality directory, the functionalty itself is
630254
implemented through function scripts. Function scripts are organized
a69d1a
in files independently one another and written in @samp{camelCase}
a69d1a
format with the function name as prefix.  Separation between prefix
a69d1a
and description is done using underscore (@samp{_}) character.
630254
630254
In order for @file{centos-art.sh} script to load functionalities
630254
correctly, function definition inside function scripts should be set
630254
using the @samp{function} reserved word, just as in the following
630254
example:
630254
630254
@verbatim
630254
function prefix_doSomething {
630254
630254
    # Do something here...
630254
630254
}
630254
@end verbatim
630254
a69d1a
The above function definition is just a convenction we use, in order
a69d1a
to make identification of function names easier read and automate by
a69d1a
@file{centos-art.sh} script initialization commands, once
a69d1a
@file{centos-art.sh} script determines which functionality directory
a69d1a
to use.  Specifically, in order to initialize and export functions,
a69d1a
@file{centos-art.sh} script executes all function scripts inside the
a69d1a
functionality directory, and later @command{grep} on them using a
a69d1a
regular expression pattern, where the @samp{function} reserved word is
a69d1a
used as reference to retrive the function names and export them to
a69d1a
@file{centos-art.sh} script execution environment, and so, make
a69d1a
function definitions ---from function scripts inside the functionality
a69d1a
directory--- available for further calls.
a69d1a
a69d1a
If the functionality specified in the command-line first argument
a69d1a
doesn't have a functionality directory, @file{centos-art.sh} script
a69d1a
considers the functionality provided in the command-line as invalid
a69d1a
functionality and immediatly stops script execution with an error
a69d1a
message.
a69d1a
a69d1a
In order to keep visual consistency among function scripts, please
a69d1a
consider using the following function script design model as template
a69d1a
for your own function scripts:
630254
630254
@verbatim
630254
#!/bin/bash
630254
#
630254
# prefix_doSomething.sh -- This function illustrates function scripts
630254
# design model you can use to create your own function scripts inside
630254
# centos-art.sh script.
630254
#
630254
# Copyright (C) YEAR YOURFULLNAME
630254
#
630254
# This program is free software; you can redistribute it and/or modify
630254
# it under the terms of the GNU General Public License as published by
630254
# the Free Software Foundation; either version 2 of the License, or
630254
# (at your option) any later version.
630254
# 
630254
# This program is distributed in the hope that it will be useful, but
630254
# WITHOUT ANY WARRANTY; without even the implied warranty of
630254
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
630254
# General Public License for more details.
630254
#
630254
# You should have received a copy of the GNU General Public License
630254
# along with this program; if not, write to the Free Software
630254
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
630254
# USA.
630254
# 
630254
# ----------------------------------------------------------------------
630254
# $Id$
630254
# ----------------------------------------------------------------------
630254
630254
function prefix_doSomething {
630254
630254
    # Do something here...
630254
630254
}
630254
@end verbatim
be6bef
@end defun
be6bef
be6bef
@defun cli_getCountryCodes [FILTER]
f7b7e3
Output country codes supported by @file{centos-art.sh} script. 
2bb528
2bb528
The @code{cli_getCountryCodes} function outputs a list with country
2bb528
codes as defined in ISO3166 standard. When @var{FILTER} is provided,
41f1ec
@code{cli_getCountryCodes} outputs country codes that match
be6bef
@var{FILTER} regular expression pattern.
be6bef
@end defun
be6bef
2bb528
@defun cli_getCountryName [FILTER]
f7b7e3
Outputs country name supported by @file{centos-art.sh} script.
2bb528
2bb528
The @code{cli_getCountryName} function reads one language locale code
2bb528
in the format LL_CC and outputs the name of its related country as in
2bb528
ISO3166. If filter is specified, @code{cli_getCountryName} returns the
2bb528
country name that matches the locale code specified in @var{FILTER},
2bb528
exactly.
be6bef
@end defun
6c4982
 
be6bef
@defun cli_getCurrentLocale
2bb528
Output current locale used by @file{centos-art.sh} script. 
2bb528
2bb528
The @code{cli_getCurrentLocale} function uses @env{LANG} environment
41f1ec
variable to build a locale pattern that is later applied to
41f1ec
@code{cli_getLocales} function output in order to return the current
41f1ec
locale that @file{centos-art.sh} script works with. 
41f1ec
41f1ec
The current locale information, returned by
41f1ec
@code{cli_getCurrentLocale}, is output from more specific to less
41f1ec
specific. For example, if @samp{en_GB} locale exists in
41f1ec
@code{cli_getLocales} function output, the @samp{en_GB} locale would
41f1ec
take precedence before @samp{en} locale.
41f1ec
41f1ec
Locale precedence selection is quite important in order to define the
41f1ec
locale type we use for message translations. For example, if
f7b7e3
@samp{en_GB} is used, we are also saying that the common language
f7b7e3
specification for English language (i.e., @samp{en}) is no longer
f7b7e3
used. Instead, we are using English non-common country-specific
f7b7e3
language specifications like @samp{en_AU}, @samp{en_BW}, @samp{en_GB},
41f1ec
@samp{en_US}, etc., for message translations.  
41f1ec
41f1ec
Use @code{cli_getCurrentLocale} function to know what current locale
41f1ec
information to use inside @file{centos-art.sh} script.
be6bef
@end defun
be6bef
a69d1a
@defun cli_getFilesList [LOCATION]
a69d1a
Output list of files to process.
a69d1a
a69d1a
The @code{cli_getFilesList} function uses @var{LOCATION} variable as
a69d1a
source location to build a list of files just as specified by regular
dc206c
expression (@var{REGEX}) global variable. Essentially, what the
dc206c
@code{cli_getFilesList} function does is using @command{find} command
dc206c
to look for files in the location (@var{LOCATION}) just as posix-egrep
dc206c
regular expression (@var{REGEX}) specifies. 
a69d1a
a69d1a
If @var{LOCATION} is not specified when @code{cli_getFilesList}
a69d1a
function is called, the action value (@var{ACTIONVAL}) global variable
dc206c
is used as location value instead.
a69d1a
a69d1a
By default, if the regular expression (@var{REGEX}) global variable is
dc206c
not redefined after its first definition in the @code{cli} function,
dc206c
all files that match default regular expression value (i.e.,
dc206c
@samp{.+}) will be added to the list of files to process. Otherwise,
dc206c
if you redefine the regular expression global variable after its first
dc206c
definition in the @code{cli} function and before calling
68005b
@code{cli_getFilesList} function, the last value you specifed is used
dc206c
instead.
dc206c
dc206c
When you need to customize the regular expression (@var{REGEX}) global
dc206c
variable value inside a function, do not redefine the global variable
dc206c
(at least you be absolutly convinced you need to).  Instead, set the
dc206c
regular expression global variable as @samp{local} to the function you
dc206c
need a customized regular expression value for.  If we don't redefine
dc206c
the regular expression global variable as local to the function, or
dc206c
use another name for the regular expression variable (which is not
dc206c
very convenient in order to keep the amount of names to remember low),
dc206c
you may experiment undesired concantenation issues that make your
dc206c
regular expression to be something different from that you expect them
68005b
to be, specially if the function where you are doing the variable
dc206c
redefinition is called several times during the same script execution.
68005b
68005b
As result, the @code{cli_getFilesList} re-defines the value of
68005b
@var{FILES} variable with the list of files the @command{find} command
68005b
returned. As example, consider the following construction:
68005b
68005b
@verbatim
68005b
function prefix_doSomething {
68005b
68005b
    # Initialize the list of files to process.
68005b
    local FILES=''
68005b
68005b
    # Initialize location.
68005b
    local LOCATION=/home/centos/artwork/trunk/Identity/Themes/Models/Default
68005b
68005b
    # Re-define regular expression to match scalable vector graphic
68005b
    # files only. Note how we use the global value of REGEX to build a
68005b
    # new local REGEX value here.
68005b
    local REGEX="${REGEX}.*\.(svgz|svg)"
68005b
68005b
    # Redefine list of files to process.
68005b
    cli_getFilesList $LOCATION
68005b
68005b
    # Process list of files.
68005b
    for FILE in $FILES;do
68005b
        cli_printMessages "$FILE" 'AsResponseLine'
68005b
        # Do something else here on...
68005b
    done
68005b
68005b
}
68005b
@end verbatim
68005b
200d3f
@end defun
200d3f
be6bef
@defun cli_getLangCodes [FILTER]
f7b7e3
Outputs language codes supported by @file{centos-art.sh} script.
2bb528
be6bef
@code{cli_getLangCodes} function outputs a list of language codes as
be6bef
defined in ISO639 standard. When @var{FILTER} is provided,
be6bef
@code{cli_getLangCodes} outputs language codes that match @var{FILTER}
be6bef
regular expression pattern.
be6bef
@end defun
be6bef
41f1ec
@defun cli_getLangName [FILTER]
f7b7e3
Outputs language names supported by @file{centos-art.sh} script.
2bb528
41f1ec
@code{cli_getLangName} function reads one language locale code in the
2bb528
format LL_CC and outputs the language related name as in ISO639. If
2bb528
filter is specified, @code{cli_getLangName} returns the language name
2bb528
that matches the locale code specified in @var{FILTER}, exactly.
be6bef
@end defun
be6bef
be6bef
@defun cli_getLocales
2bb528
Output locale codes supported by @file{centos-art.sh} script.
41f1ec
41f1ec
Occasionally, you use @code{cli_getLocales} function to add locale
41f1ec
information in non-common country-specific language (@samp{LL_CC})
41f1ec
format for those languages (e.g., @samp{bn_IN}, @samp{pt_BR}, etc.)
41f1ec
which locale differences cannot be solved using common language
41f1ec
specifications (@samp{LL}) into one unique common locale specification
41f1ec
(e.g., @samp{bn}, @samp{pt}, etc.).  
be6bef
@end defun
be6bef
41f1ec
@defun cli_getRepoName NAME TYPE
2bb528
Sanitate file names.
2bb528
2bb528
Inside @file{centos-art.sh} script, specific functionalities rely both
2bb528
in @code{cli_getRepoName} and repository file system organization to
2bb528
achieve their goals.  Consider @code{cli_getRepoName} function as
2bb528
central place to manage file name convenctions for other functions
2bb528
inside @file{centos-art.sh} script.
41f1ec
41f1ec
@quotation
915635
@strong{Important} @code{cli_getRepoName} function doesn't verify file
41f1ec
or directory existence, for that purpose use @code{cli_checkFiles}
41f1ec
function instead.
41f1ec
@end quotation
41f1ec
41f1ec
The @var{NAME} variable contains the file name or directory name you
41f1ec
want to sanitate.
41f1ec
f7b7e3
The @var{TYPE} variable specifies what type of sanitation you want to
f7b7e3
perform on @var{NAME}. The @var{TYPE} can be one of the following
f7b7e3
values:
f7b7e3
41f1ec
@table @option
41f1ec
@item d
41f1ec
@itemx directory
41f1ec
Sanitate directory @var{NAME}s.
41f1ec
@item f
41f1ec
@item regular-file
41f1ec
Sanitate regular file @var{NAME}s.
41f1ec
@end table
41f1ec
41f1ec
Use @code{cli_getRepoName} function to sanitate file names and
41f1ec
directory names before their utilization. 
41f1ec
41f1ec
Use @code{cli_getRepoName} when you need to change file name
2bb528
convenctions inside @file{centos-art.sh} script. 
2bb528
200d3f
When we change file name convenctions inside @code{cli_getRepoName}
200d3f
what we are really changing is the way functions interpret repository
200d3f
file system organization. Notice that when we change a file name
200d3f
(e.g., a function name), it is necessary to update all files where
0d7dfc
such file name is placed on. This may require a massive substitution
0d7dfc
inside the repository, each time we change name convenctions in the
0d7dfc
repository (@pxref{trunk Scripts Bash Functions Path}, for more
0d7dfc
information).
200d3f
@end defun
41f1ec
92c139
@defun cli_getRepoStatus [LOCATION]
92c139
Request repository status.
92c139
0d7dfc
This function requests the status of a @var{LOCATION} inside the
0d7dfc
working copy using the @command{svn status} command and returns the
0d7dfc
first character in the output line, just as described in @command{svn
0d7dfc
help status}. If @var{LOCATION} is not a regular file or a directory,
0d7dfc
inside the working copy, the @file{centos-art.sh} script prints a
0d7dfc
message and ends its execution.
92c139
92c139
Use this function to perform verifications based a repository
92c139
@var{LOCATION} status.
be6bef
@end defun
be6bef
915635
@defun cli_getTemporalFile @var{NAME}
915635
Output absolute path to temporal file @var{NAME}.
915635
1edfab
The @code{cli_getTemporalFile} function uses @file{/tmp} directory as
1edfab
source location to store temporal files, the @file{centos-art.sh}
1edfab
script name, and a random identification string to let you run more
1edfab
than one @file{centos-art.sh} script simultaneously on the same user
1edfab
session.  For example, due the following temporal file defintion:
915635
915635
@verbatim
915635
cli_getTemporalFile $FILE
915635
@end verbatim
915635
1edfab
If @var{FILE} name is @file{instance.svg} and the unique random string
1edfab
is @samp{f16f7b51-ac12-4b7f-9e66-72df847f12de}, the final temporal
1edfab
file, built from previous temporal file definition, would be:
915635
915635
@verbatim
915635
/tmp/centos-art.sh-f16f7b51-ac12-4b7f-9e66-72df847f12de-instance.svg
915635
@end verbatim
915635
1edfab
When you use the @code{cli_getTemporalFile} function to create
1edfab
temporal files, be sure to remove temporal files created once you've
1edfab
ended up with them.  For example, consider the following construction:
915635
915635
@verbatim
915635
for FILE in $FILES;do
915635
915635
    # Initialize temporal instance of file.
915635
    INSTANCE=$(cli_getTemporalFile $FILE)
915635
915635
    # Do something ... 
915635
915635
    # Remove temporal instance of file.
915635
    if [[ -f $INSTANCE ]];then
915635
        rm $INSTANCE
915635
    fi
915635
915635
done
915635
@end verbatim
915635
1edfab
Use the @code{cli_getTemporalFile} function whenever you need to
1edfab
create temporal files inside @file{centos-art.sh} script.
915635
@end defun
915635
be6bef
@defun cli_getThemeName
2bb528
Output theme name.
2bb528
2bb528
In order for @code{cli_getThemeName} function to extract theme name
06717d
correctly, the @var{ACTIONVAL} variable must contain a directory path
2bb528
under @file{trunk/Identity/Themes/Motifs/} directory structure.
2bb528
Otherwise, @code{cli_getThemeName} returns an empty string.  
be6bef
@end defun
be6bef
be6bef
@defun cli_printMessage MESSAGE [FORMAT]
200d3f
Define standard output message definition supported by
200d3f
@file{centos-art.sh} script.
be6bef
be6bef
When @var{FORMAT} is not specified, @code{cli_printMessage} outputs
be6bef
information just as it was passed in @var{MESSAGE} variable.
be6bef
Otherwise, @var{FORMAT} can take one of the following values:
be6bef
be6bef
@table @option
be6bef
@item AsHeadingLine
2bb528
To print heading messages.
be6bef
@verbatim
be6bef
----------------------------------------------------------------------
be6bef
$MESSAGE
be6bef
----------------------------------------------------------------------
be6bef
@end verbatim
be6bef
be6bef
@item AsWarningLine
2bb528
To print warning messages.
be6bef
@verbatim
be6bef
----------------------------------------------------------------------
be6bef
WARNING: $MESSAGE
be6bef
----------------------------------------------------------------------
be6bef
@end verbatim
be6bef
be6bef
@item AsNoteLine
2bb528
To print note messages.
be6bef
@verbatim
be6bef
----------------------------------------------------------------------
be6bef
NOTE: $MESSAGE
be6bef
----------------------------------------------------------------------
be6bef
@end verbatim
be6bef
be6bef
@item AsUpdatingLine
200d3f
To print @samp{Updating} messages on two-columns format.
be6bef
@verbatim
be6bef
Updating        $MESSAGE
be6bef
@end verbatim
be6bef
be6bef
@item AsRemovingLine
200d3f
To print @samp{Removing} messages on two-columns format.
be6bef
@verbatim
be6bef
Removing        $MESSAGE
be6bef
@end verbatim
be6bef
be6bef
@item AsCheckingLine
200d3f
To print @samp{Checking} messages on two-columns format.
be6bef
@verbatim
be6bef
Checking        $MESSAGE
be6bef
@end verbatim
be6bef
be6bef
@item AsCreatingLine
200d3f
To print @samp{Creating} messages on two-columns format.
be6bef
@verbatim
be6bef
Creating        $MESSAGE
be6bef
@end verbatim
be6bef
be6bef
@item AsSavedAsLine
200d3f
To print @samp{Saved as} messages on two-columns format.
be6bef
@verbatim
be6bef
Saved as        $MESSAGE
be6bef
@end verbatim
be6bef
be6bef
@item AsLinkToLine
200d3f
To print @samp{Linked to} messages on two-columns format.
be6bef
@verbatim
be6bef
Linked to       $MESSAGE
be6bef
@end verbatim
be6bef
be6bef
@item AsMovedToLine
200d3f
To print @samp{Moved to} messages on two-columns format.
be6bef
@verbatim
be6bef
Moved to        $MESSAGE
be6bef
@end verbatim
be6bef
be6bef
@item AsTranslationLine
200d3f
To print @samp{Translation} messages on two-columns format.
be6bef
@verbatim
be6bef
Translation     $MESSAGE
be6bef
@end verbatim
be6bef
be6bef
@item AsConfigurationLine
200d3f
To print @samp{Configuration} messages on two-columns format.
be6bef
@verbatim
be6bef
Configuration   $MESSAGE
be6bef
@end verbatim
be6bef
be6bef
@item AsResponseLine
200d3f
To print response messages on one-column format.
be6bef
@verbatim
be6bef
--> $MESSAGE
be6bef
@end verbatim
be6bef
be6bef
@item AsRequestLine
200d3f
To print request messages on one-column format. Request messages
200d3f
output messages with one colon (@samp{:}) and without trailing newline
200d3f
(@samp{\n}) at message end.
be6bef
@verbatim
200d3f
$MESSAGE:
be6bef
@end verbatim
be6bef
be6bef
@item AsYesOrNoRequestLine
200d3f
To print @samp{yes or no} request messages on one-column format. If
2bb528
something different from @samp{y} is answered (when using
be6bef
@code{en_US.UTF-8} locale), script execution ends immediatly.  
be6bef
be6bef
@verbatim
be6bef
$MESSAGE [y/N]:
be6bef
@end verbatim
be6bef
200d3f
When we use @file{centos-art.sh} script in a locale different from
200d3f
@code{en_US.UTF-8}, confirmation answer may be different from
200d3f
@samp{y}. For example, if you use @code{es_ES.UTF-8} locale, the
be6bef
confirmation question would look like:
be6bef
be6bef
@verbatim
be6bef
$MESSAGE [s/N]:
be6bef
@end verbatim
be6bef
be6bef
and the confirmation answer would be @samp{s}, as it is on Spanish
be6bef
@samp{sí} word.
be6bef
be6bef
Definition of which confirmation word to use is set on translation
be6bef
messages for your specific locale information. @xref{trunk Scripts
be6bef
Bash Functions Locale}, for more information about locale-specific
be6bef
translation messages.
be6bef
be6bef
@item AsToKnowMoreLine
be6bef
To standardize @samp{to know more, run the following command:}
be6bef
messages. When the @option{AsToKnowMoreLine} option is used, the
be6bef
@var{MESSAGE} value should be set to @code{"$(caller)"}. @code{caller}
be6bef
is a Bash builtin that returns the context of the current subroutine
be6bef
call. @option{AsToKnowMoreLine} option uses @code{caller} builtin
2bb528
output to build documentation entries dynamically.
be6bef
be6bef
@verbatim
be6bef
----------------------------------------------------------------------
be6bef
To know more, run the following command:
f7b7e3
centos-art manual --read='path/to/dir'
be6bef
----------------------------------------------------------------------
be6bef
@end verbatim
be6bef
be6bef
Use @option{AsToKnowMoreLine} option after errors and for intentional
be6bef
script termination. 
be6bef
be6bef
@item AsRegularLine
200d3f
To standardize regular messages on one-column format. 
be6bef
be6bef
When @var{MESSAGE} contains a colon inside (e.g., @samp{description:
be6bef
message}), the @code{cli_printMessage} function outputs @var{MESSAGE}
200d3f
on two-columns format. 
6c4982
@end table
2bb528
200d3f
Use @code{cli_printMessage} function whenever you need to output
200d3f
information from @file{centos-art.sh} script.
200d3f
2bb528
@quotation
2bb528
@strong{Tip} To improve two-columns format, change the following file:
2bb528
@verbatim
2bb528
trunk/Scripts/Bash/Styles/output_forTwoColumns.awk
2bb528
@end verbatim
2bb528
@end quotation
be6bef
@end defun
6c4982
6c4982
@subsubsection Specific functions
6c4982
6c4982
The following specific functions of @file{centos-art.sh} script, are
6c4982
available for you to use:
4c79b5
38bcd9
@menu
38bcd9
* trunk Scripts Bash Functions Html::
38bcd9
* trunk Scripts Bash Functions Locale::
035049
* trunk Scripts Bash Functions Manual::
38bcd9
* trunk Scripts Bash Functions Path::
38bcd9
* trunk Scripts Bash Functions Render::
b17ce8
* trunk Scripts Bash Functions Render Config::
38bcd9
* trunk Scripts Bash Functions Shell::
38bcd9
* trunk Scripts Bash Functions Svg::
38bcd9
* trunk Scripts Bash Functions Verify::
38bcd9
@end menu
4c79b5
4c79b5
@subsection See also
4c79b5
4c79b5
@menu
38bcd9
* trunk Scripts Bash::
efa7b7
* trunk Scripts Bash Locale::
4c79b5
@end menu