diff --git a/Manual/Directories/chapter-menu.texi b/Manual/Directories/chapter-menu.texi index 2f6d74e..b3d4b54 100644 --- a/Manual/Directories/chapter-menu.texi +++ b/Manual/Directories/chapter-menu.texi @@ -42,4 +42,5 @@ * Directories trunk Scripts Functions Prepare:: * Directories trunk Scripts Functions Render:: * Directories trunk Scripts Functions Render Config:: +* Directories trunk Scripts Functions Tuneup:: @end menu diff --git a/Manual/Directories/chapter-nodes.texi b/Manual/Directories/chapter-nodes.texi index 2dff018..c3a5dc6 100644 --- a/Manual/Directories/chapter-nodes.texi +++ b/Manual/Directories/chapter-nodes.texi @@ -213,3 +213,8 @@ @cindex Directories trunk Scripts Functions Render Config @include Directories/trunk/Scripts/Functions/Render/Config.texi +@node Directories trunk Scripts Functions Tuneup +@section The @file{trunk/Scripts/Functions/Tuneup} Directory +@cindex Directories trunk Scripts Functions Tuneup +@include Directories/trunk/Scripts/Functions/Tuneup.texi + diff --git a/Manual/Directories/trunk.texi b/Manual/Directories/trunk.texi index 226013a..e6c4248 100644 --- a/Manual/Directories/trunk.texi +++ b/Manual/Directories/trunk.texi @@ -8,21 +8,6 @@ trunk concept in a trunk, branches, tags repository structure. The @file{trunk/} directory structure provides the main development line inside the CentOS Artwork Repository. - -@subsubheading Automation - -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 Usage @itemize diff --git a/Manual/Directories/trunk/Scripts.texi b/Manual/Directories/trunk/Scripts.texi index 13a77f5..960aa4c 100644 --- a/Manual/Directories/trunk/Scripts.texi +++ b/Manual/Directories/trunk/Scripts.texi @@ -1,9 +1,16 @@ @subheading Goals -The @file{trunk/Scripts} directory exists to organize the trunk -development line of @file{centos-art.sh} automation script. The -@file{centos-art.sh} script standardizes tasks you need to do -frequently inside CentOS Artwork Repository. +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 @@ -22,19 +29,18 @@ operating system trys to execute that command. In order to execute the command, the operating system needs to know where it is, so the operating system uses the @var{PATH} environment variable to look for that command location. If your system was prepared to use CentOS -Artwork Repository correctly (--- @strong{Removed}(pxref:trunk Scripts Bash Functions -Verify) ---), you should have a symbolic link inside @file{~/bin/} -directory that points to the @file{centos-art.sh} script file. As -@file{~/bin/} directory is, by default, inside @var{PATH} environment -variable, the execution of @command{centos-art} command runs the -@file{centos-art.sh} script. +Artwork Repository correctly (@pxref{Directories trunk Scripts +Functions Prepare}) you should have a symbolic link inside +@file{~/bin} directory that points to the @file{centos-art.sh} script +file. As @file{~/bin} directory is, by default, inside @var{PATH} +environment variable, the execution of @command{centos-art} command +runs the @file{centos-art.sh} script. When @file{centos-art.sh} script is executed, the first it does is -executing the @file{trunk/Scripts/Bash/initEnvironment.sh} script to -initialize global variables (e.g., @command{gettext} variables) and +initializing global variables (e.g., @command{gettext} variables) and global function scripts. Global function scripts are located inside -@file{trunk/Scripts/Bash/Functions} directory and their file names -begin with @samp{cli}. Global function scripts provide common +@file{trunk/Scripts/Functions} directory and their file names begin +with @samp{cli}. Global function scripts provide common functionalities that can be used anywhere inside @file{centos-art.sh} script execution environment. @@ -42,13 +48,13 @@ Once global variables and function scripts have been loaded, @file{centos-art.sh} script executes the @command{cli} global function from @file{cli.sh} function script to retrive command-line arguments and define some default values that may be used later by specific -function scripts (--- @strong{Removed}(pxref:trunk Scripts Bash Functions) ---). +function scripts (@pxref{Directories trunk Scripts Functions}). As convenction, the @file{centos-art.sh} command-line arguments have the following format: @verbatim -centos-art function path/to/dir --options +centos-art function path/to/dir --option='value' @end verbatim In the above example, @samp{centos-art} is the command you use to @@ -66,30 +72,26 @@ Once command-line arguments have been retrived, the functionality can be loaded at one script execution I.e., you run @command{centos-art.sh} script to run just one functionality. -@float Figure,fig:trunk/Scripts/Bash:Initialization +@float Figure, Functionalities initialization @verbatim +----------------------------------------------------------------------+ -| [centos@host]$ centos-art function --action='value' --option='value' | +| [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---+ - . | initEnvironment.sh | . - . +---------------------------------+ . - . | cli $@ | . - . +---v-------------------------v---+ . - . . | cli_getFunctions | . . - . . +---v-----------------v---+ . . - . . . | function1 | . . . - . . . | function2 | . . . - . . . | function3 | . . . - . . . +-----------------+ . . . - . . ........................... . . - . ................................... . - ........................................... ++---v--------------------------------------------------------------v---+ + | centos-art.sh | + +-v--------------------------------------------------------v---+ + . | cli $@ | . + . +-v--------------------------------------------------v---+ . + . . | cli_getFunctions | . . + . . +-v-----------v-----------v-----------v------------+ . . + . . . | function1 | function2 | functionN | . . . + . . . +-----------+-----------+-----------+ . . . + . . .................................................... . . + . .......................................................... . + ................................................................ @end verbatim -@caption{The functionalities initialization environment.} +@caption{Functionalities initialization environment.} @end float Functionalities are implemented by means of actions. Once the @@ -99,59 +101,34 @@ similar to functions initialization model. But with the difference, that actions are loaded inside function environment, and so, share variables and functions defined inside function environment. -@float Figure,fig:trunk/Scripts/Bash/Functions:Initialization +@float Figure, Actions initialization @verbatim -+--------------------------------------+ -| cli_getFunctions | -+---v------------------------------v---+ -. | function1 | . -. +---v------------------------v-+ . -. . | function1_getArguments | . . -. . +---v--------------v-----+ . . -. . . | action 1 | . . . -. . . | action 2 | . . . -. . . | action n | . . . -. . . +--------------+ . . . -. . .......................... . . -. ................................ . -. +------------------------------+ . -. | function2 | . -. +---v------------------------v-+ . -. . | function2_getArguments | . . -. . +---v--------------v-----+ . . -. . . | action 1 | . . . -. . . | action 2 | . . . -. . . | action n | . . . -. . . +--------------+ . . . -. . .......................... . . -. ................................ . -. +------------------------------+ . -. | function3 | . -. +---v------------------------v-+ . -. . | function3_getArguments | . . -. . +---v--------------v-----+ . . -. . . | action 1 | . . . -. . . | action 2 | . . . -. . . | action n | . . . -. . . +--------------+ . . . -. . .......................... . . -. ................................ . -........................................ ++----------------------------------------------------------------------+ +| cli_getFunctions | ++---v----------------------------v----v----------------------------v---+ +. | function1 | | function2 | . +. +-v------------------------v-+ +-v------------------------v-+ . +. . | function1_getArguments | . . | function2_getArguments | . . +. . +-v--------------------v-+ . . +-v--------------------v-+ . . +. . . | action 1 | . . . . | action 1 | . . . +. . . | action 2 | . . . . | action 2 | . . . +. . . | action N | . . . . | action N | . . . +. . . +--------------------+ . . . . +--------------------+ . . . +. . .......................... . . .......................... . . +. .............................. .............................. . +........................................................................ @end verbatim -@caption{The actions initialization environment.} +@caption{Actions initialization environment.} @end float @subheading Usage The @file{centos-art.sh} script usage information is described inside -each specific function documentation (--- @strong{Removed}(pxref:trunk Scripts Bash -Functions) ---). +each specific function documentation (@pxref{Directories trunk Scripts +Functions}). @subheading See also -@menu -* Directories trunk Scripts:: -* Directories trunk Scripts Functions:: -@comment --- Removed(* Directories trunk Scripts Locale::) --- -@end menu - +@itemize +@item @ref{Directories trunk} +@end itemize diff --git a/Manual/Directories/trunk/Scripts/Functions.texi b/Manual/Directories/trunk/Scripts/Functions.texi index 35141fe..ace1a4e 100755 --- a/Manual/Directories/trunk/Scripts/Functions.texi +++ b/Manual/Directories/trunk/Scripts/Functions.texi @@ -1,84 +1,56 @@ @subheading Goals -The @file{trunk/Scripts/Bash/Functions} directory exists to organize +The @file{trunk/Scripts/Functions} directory exists to organize @file{centos-art.sh} specific functionalities. @subheading Description The specific functions of @file{centos-art.sh} script are designed -with ``Software Toolbox'' philosophy (@pxref{Toolbox -introduction,,,coreutils.info}) in mind: each program ``should do one +with the ``Software Toolbox'' philosophy (@inforef{Toolbox +introduction,,coreutils.info}) in mind: each program ``should do one thing well''. Inside @file{centos-art.sh} script, each specific functionality is considered a program that should do one thing well. Of course, if you find that they still don't do it, feel free to improve them in order for them to do so. The specific functions of @file{centos-art.sh} script are organized -inside specific directories under @file{trunk/Scripts/Bash/Functions} +inside specific directories under @file{trunk/Scripts/Functions} location. Each specific function directory should be named as the function it represents, with the first letter in uppercase. For example, if the function name is @code{render}, the specific function -directory for it would be @samp{trunk/Scripts/Bash/Functions/Render}. +directory for it would be @samp{trunk/Scripts/Functions/Render}. -To better understand how specific functions of @file{centos-art.sh} -script are designed, lets create one function which only goal is to -output different kind of greetings to your screen. +@subsubheading Creating the @code{greet} functionality -When we create specific functions for @file{centos-art.sh} script it -is crucial to know what these functions will do exactly and if there -is any function that already does what we intend to do. If there is no -one, it is good time to create them then. Otherwise, if -functionalities already available don't do what you exactly expect, -contact their authors and work together to improve them. - -@quotation -@strong{Tip} Join CentOS developers mailing list -@email{centos-art@@centos.org} to share your ideas. -@end quotation - -It is also worth to know what global functions and variables do we -have available inside @file{centos-art.sh} script, so advantage can be -taken from them. Global variables are defined inside global function -scripts. Global functions scripts are stored immediatly under -@file{trunk/Scripts/Bash/Functions} directory, in files begining with -@samp{cli} prefix. - -OK, let's begin with our functionality example. - -What function name do we use? Well, lets use @code{greet}. Note that -@samp{hello} word is not a verb; but an expression, a kind of -greeting, an interjection specifically. In contrast, @samp{greet} is a -verb and describes what we do when we say @samp{Hello!}, @samp{Hi!}, -and similar expressions. - -So far, we've gathered the following function information: +To better understand how to design specific functions for +@file{centos-art.sh} script, let's create the @code{greet} +functionality which only goal is to print out different kind of +greetings to your screen. The @code{greet} functionality will be set +using the follwiing directory structure: @verbatim -Name: greet -Path: trunk/Scripts/Bash/Functions/Greet -File: trunk/Scripts/Bash/Functions/Greet/greet.sh +trunk/Scripts/Functions/Greet <-- The source location of greet function. +|-- greet_getArguments.sh <-- Defines command-line interface. +|-- greet_sayGoodbye.sh <-- Defines specific action. +|-- greet_sayHello.sh <-- Defines specific action. +`-- greet.sh <-- Defines function initialization. @end verbatim -The @file{greet.sh} function script is the first file -@file{centos-art.sh} script loads when the @samp{greet} functionality -is called using commands like @samp{centos-art greet --hello='World'}. -The @file{greet.sh} function script contains the @code{greet} function -definition. +The @file{greet.sh} file contains the initialization script of +@code{greet} functionality. It is the first file loaded from function +source location by @command{centos-art.sh} script when it is executed +using the @code{greet} functionality as first argument. Inside @file{centos-art.sh} script, as convenction, each function script has one top commentary, followed by one blank line, and then -one function defintion below it only. - -Inside @file{centos-art.sh} script functions, top commentaries have -the following components: the functionality description, one-line for -copyright note with your personal information, the license under -which the function source code is released ---the @file{centos-art.sh} -script is released as GPL, so do all its functions---, the @code{$Id$} -keyword of Subversion is later expanded by @command{svn propset} -command. - -In our @code{greet} function example, top commentary for -@file{greet.sh} function script would look like the following: +one function defintion below it only. The top commentary has the +function description, one-line for copyright notice with your personal +information, the license under which the function source code is +released ---the @file{centos-art.sh} script is released as GPL, so do +all its functions--- and the @code{$Id$} keyword of Subversion which +is later expanded by @command{svn propset} command. In our example, +the top comment of @code{greet.sh} function script would look like the +following: @verbatim #!/bin/bash @@ -91,9 +63,9 @@ In our @code{greet} function example, top commentary for # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# +# the Free Software Foundation; either version 2 of the License, or (at +# your option) any later version. +# # This program is distributed in the hope that it will be useful, but # WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU @@ -101,176 +73,182 @@ In our @code{greet} function example, top commentary for # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 -# USA. -# +# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. # ---------------------------------------------------------------------- # $Id$ # ---------------------------------------------------------------------- -@end verbatim -After top commentary, separated by one blank line, the @code{greet} -function definition would look like the following: - -@verbatim function greet { - # Define global variables. - # Define command-line interface. - greet_getActions - + greet_getArguments + + # Execute action name. + if [[ $ACTIONNAM =~ "^${FUNCNAM}_[A-Za-z]+$" ]];then + eval $ACTIONNAM + else + cli_printMessage "`gettext "A valid action is required."`" 'AsErrorLine' + cli_printMessage "${FUNCDIRNAM}" 'AsToKnowMoreLine' + fi + } @end verbatim -The first definition inside @code{greet} function, are global -variables that will be available along @code{greet} function execution -environment. This time we didn't use global variable definitions for -@code{greet} function execution environment, so we left that section -empty. - -Later, we call @code{greet_getActions} function to define the -command-line interface of @code{greet} functionality. The command-line -interface of @code{greet} functionality defines what and how actions -are performed, based on arguments combination passed to -@file{centos-art.sh} script. - -@verbatim -function greet_getActions { - - case "$ACTIONNAM" in - - --hello ) - greet_doHello - ;; - - --bye ) - greet_doBye - ;; - - * ) - cli_printMessage "`gettext "The option provided is not valid."`" - cli_printMessage "$(caller)" 'AsToKnowMoreLine' +The first definition inside @code{greet} function is for variables +that will be available along the whole execution environment of +@code{greet} function. This time we didn't define any variable here +so, we continued with definition of command-line interface, through +@code{greet_getArguments} function. + +The command-line interface of @code{greet} functionality defines how +to interpret arguments passed from @command{centos-art.sh} script +command-line. Inside @command{centos-art.sh} script, the +interpretation of arguments passed through its command-line takes +place by mean of @command{getopt} command and is written as the +following code example describes: + +@verbatim +function greet_getArguments { + + # Define short options we want to support. + local ARGSS="" + + # Define long options we want to support. + local ARGSL="hello:,bye:,quiet" + + # Redefine ARGUMENTS variable using getopt output. + cli_doParseArguments + + # Redefine positional parameters using ARGUMENTS variable. + eval set -- "$ARGUMENTS" + + # Look for options passed through command-line. + while true; do + + case "$1" in + + --hello ) + ACTIONNAM="${FUNCNAM}_sayHello" + ACTIONVAL="$2" + shift 2 + ;; + + --bye ) + ACTIONNAM="${FUNCNAM}_sayGoodbye" + ACTIONVAL="$2" + shift 2 + ;; + + -- ) + # 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 + # begining 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 - esac + # Redefine ARGUMENTS variable using current positional parameters. + cli_doParseArgumentsReDef "$@" } @end verbatim -The @var{ACTIONNAM} global variable is defined in @file{cli.sh} -function script and contains the value passed before the equal sign -(i.e., @samp{=}) in the second command-line argument of -@file{centos-art.sh} script. For example, if the second command-line -argument is @option{--hello='World'}, the value of @var{ACTIONNAM} -variable would be @samp{--hello}. Using this configuration let us -deside which action to perform based on the action name passed to -@file{centos-art.sh} script as second argument. - -The @code{greet} function definition makes available two valid -greetings through @option{--hello} and @option{--bye} options. If no -one of them is provided as second command-line argument, the @samp{*} -case is evaluated instead. - -The @samp{*} case and its two lines further on should always be -present in @file{_getActions.sh} function scripts, no matter what -specific functionality you are creating. This convenction helps the -user to find out documentation about current functionality in use, -when no valid action is provided. - -The @code{greet_doHello} and @code{greet_doBye} function definitions +The @code{greet_sayHello} and @code{greet_sayGoodbye} function definitions are the core of @code{greet} specific functionality. In such function definitions we set what our @code{greet} function really does: to output different kinds of greetings. @verbatim -function greet_doHello { +function greet_sayHello { - cli_printMessage "`gettext "Hello"` $ACTIONVAL" + cli_printMessage "`gettext "Hello"`, $ACTIONVAL" } @end verbatim -The @code{greet_doHello} function definition is stored in -@file{greet_doHello.sh} function script. +The @code{greet_sayHello} function definition is stored in +@file{greet_sayHello.sh} function script. @verbatim -function greet_doBye { +function greet_sayGoodbye { - cli_printMessage "`gettext "Goodbye"` $ACTIONVAL" + cli_printMessage "`gettext "Goodbye"`, $ACTIONVAL" } @end verbatim -The @code{greet_doBye} function definition is stored in the -@file{greet_doBye.sh} function script. - -Both @file{greet_doHello.sh} and @file{greet_doBye.sh} function -scripts are stored inside @code{greet} function directory path (i.e. -@file{trunk/Scripts/Bash/Functions/Greet}). +The @code{greet_sayGoodbye} function definition is stored in the +@file{greet_sayGoodbye.sh} function script. -The @var{ACTIONVAL} global variable is defined in @file{cli.sh} -function script and contains the value passed after the equal sign -(i.e., @samp{=}) in the second command-line argument of -@file{centos-art.sh} script. For example, if the second command-line -argument is @option{--hello='World'}, the value of @var{ACTIONVAL} -variable would be @samp{World} without quotes. - -Let's see how @code{greet} specific functionality files are organzied -under @code{greet} function directory. To see file organization we use -the @command{tree} command: - -@verbatim -trunk/Scripts/Bash/Functions/Greet -|-- greet_doBye.sh -|-- greet_doHello.sh -|-- greet_getActions.sh -`-- greet.sh -@end verbatim +@subsubheading Executing the @code{greet} functionality -To try the @code{greet} specific functionality we've just created, -pass the function name (i.e., @samp{greet}) as first argument to -@file{centos-art.sh} script, and any of the valid options as second -argument. Some examples are illustrated below: +To execute the @code{greet} specific functionality we've just created, +pass the function name (i.e., @code{greet}) as first argument to +@file{centos-art.sh} script and any of the valid options after it. +Some examples are illustrated below: @verbatim [centos@projects ~]$ centos-art greet --hello='World' -Hello World +Hello, World [centos@projects ~]$ centos-art greet --bye='World' -Goodbye World +Goodbye, World [centos@projects ~]$ @end verbatim -The word @samp{World} in the examples above can be anything. In fact, -change it to have a little fun. +The word @samp{World} in the examples above can be anything. Likewise, +if you need to change the way either the hello or goodbye messages are +printed out, you can modifie the functions @code{greet_sayHello} and +@code{greet_sayGoodbye}, respectively. + +@subsubheading Documenting the @command{greet} functionality -Now that we have a specific function that works as we expect, it is -time to document it. To document @code{greet} specific functionality, -we use its directory path and the @code{manual} functionality -(--- @strong{Removed}(pxref:trunk Scripts Bash Functions Manual) ---) of @file{centos-art.sh} -script, just as the following command illustrates: +Now that @code{greet} functionality works as we expect, it is time to +document it. To document functionalities inside +@command{centos-art.sh} script we use the function directory path as +argument to the @code{help} functionality (@pxref{Directories trunk +Scripts Functions Help}) of @file{centos-art.sh} script, just as the +following command illustrates: @verbatim -centos-art manual --edit=trunk/Scripts/Bash/Functions/Greet +centos-art help --edit trunk/Scripts/Functions/Greet @end verbatim -To have a well documented function helps user to understand how your -function really works, and how it should be used. When no valid -action is passed to a function, the @file{centos-art.sh} script uses -the function documentation entry as vehicle to communicate which the -valid functions are. When no documentation entry exists for a -function, the @file{centos-art.sh} script informs that no -documentation entry exists for such function and requests user to -create it right at that time. - -Now that we have documented our function, it is time to translate its -output messages to different languages. To translate specific -functionality output messages to different languages we use the -@code{locale} functionality (--- @strong{Removed}(pxref:trunk Scripts Bash Functions -Locale) ---) of @file{centos-art.sh} script, just as the following command -illustrates: +The function documentation helps to understand how the function really +works and how it should be used. Also, when @command{centos-art.sh} +script ends because an error, the documentation entry related to the +functionality being currently executed is used as vehicle to +communicate the user what is the correct way of using the +functionality. + +@subsubheading Localizing the @command{greet} functionality + +Now that @code{greet} functionality has been documented, it is time to +localize its output messages. Localizing specific functionalities of +@command{centos-art.sh} script takes place as part of +@command{centos-art.sh} script localization itself which is performed +by applying the path @file{trunk/Scripts} to the @code{locale} +functionality of @command{centos-art.sh} script. + +As the @code{greet} functionality added new translatable strings to +the @command{centos-art.sh} script, it is required to update the +translation messages firstly, to add the new translatable strings from +@code{greet} functionality to @command{centos-art.sh} script +translation messages and then, edit the translation messages of +@command{centos-art.sh} script to localize the new translatable +strings that have been added. To achieve this, execute the following +two commands: @verbatim -centos-art locale --edit +centos-art locale --update trunk/Scripts +centos-art locale --edit trunk/Scripts @end verbatim @quotation @@ -279,944 +257,84 @@ your system locale information ---as in @env{LANG} environment variable--- must be set to that locale you want to produce translated messages for. For example, if you want to produce translated messages for Spanish language, your system locale information must be set to -@samp{es_ES.UTF-8}, or similar, first. +@samp{es_ES.UTF-8}, or similar, before executing the @code{locale} +functionality of @command{centos-art.sh} script. @end quotation Well, it seems that our example is rather complete by now. -In @code{greet} function example we've described so far, we only use -@command{cli_printMessage} global function in action specific function +@subsubheading Extending the @code{greet} functionality + +In the @code{greet} functionality we've described so far, we only use +@code{cli_printMessage} function in action specific function definitions in order to print messages, but more interesting things can be achieved inside action specific function definitions. For -example, if you pass a directory path as action value in second -argument, you could retrive a list of files from therein, and process -them. If the list of files turns too long or you just want to control -which files to process, you could add the third argument in the form -@option{--filter='regex'} and reduce the amount of files to process +example, if you pass a directory path as argument, you could use it to +retrive a list of files from therein and process them. If the list of +files turns too long or you just want to control which files to +process, so you could add another argument in the form +@option{--filter='regex'} and reduce the list of files to process using a regular expression pattern. -The @code{greet} function described in this section may serve you as -an introduction to understand how specific functionalities work inside -@file{centos-art.sh} script. With some of luck this introduction will -also serve you as motivation to create your own @file{centos-art.sh} -script specific functionalities. +In case you consider to extend the @code{greet} functionality to do +something different but print out grettings, consider changing the +function name from @code{greet} to something more appropriate, as +well. The name change must be coherent with the actions the new +function is designed to perform. + +If you doubt what name is better for your functionality, write to +@email{centos-devel@@centos.org} mailing list, explain what your +functionality intends to do and request suggestion about what name +would be more appropriate for it. That would be also very convenient +for you, in order to evaluate the purposes of your function and what +the community thinks about it. It is a way for you to gather ideas +that help you to write using the community feeling as base. + +If your function passes the community evaluation, that is a good sign +for you to start/keep writing it. However, if it doesn't, it is time +for you to rethink what you are doing and ask again until it passes +the community evaluation. You can considered you've passed the +community evaluation when after proposing your idea, you get a +considerable amount of possitve responses for what you are doing, +specially if those responses come from community leaders. + +It is very hard to do something useful for a community of people +without any point of contact with that community you are trying to do +things for. How could you know you are doing something that is needed +if you don't know what the needs are? So, explore the community needs +first, define them, work them out and repeat the process time after +time, even when you might think the need has been already satisfied. +At that point, surely, you'll find smaller needs that need to be +satisfied, as well. + +@subsubheading Conclusions + +The @code{greet} functionality described in this section may serve as +introduction for you to understand how specific functionalities are +created inside @file{centos-art.sh} script. With some of luck this +introduction will also serve you as motivation to create your own +specific functionalities for @file{centos-art.sh} script. By the way, the @code{greet} functionality doesn't exist inside @file{centos-art.sh} script yet. Would you like to create it? @subheading Usage -@subsubheading Global variables - -The following global variables of @file{centos-art.sh} script, are -available for you to use inside specific functions: - -@defvar TEXTDOMAIN -Default domain used to retrieve translated messages. This value is set -in @file{initFunctions.sh} and shouldn't be changed. -@end defvar - -@defvar TEXTDOMAINDIR -Default directory used to retrieve translated messages. This value is -set in @file{initFunctions.sh} and shouldn't be changed. -@end defvar - -@defvar FUNCNAM -Define function name. - -Function names associate sets of actions. There is one set of actions -for each unique function name inside @file{centos-art.sh} script. - -Dunction names are passed as first argument in @file{centos-art.sh} -command-line interface. For example, in the command @samp{centos-art -render --entry=path/to/dir --filter=regex}, the @var{ACTION} passed to -@file{centos-art.sh} script is @option{render}. - -When first argument is not provided, the @file{centos-art.sh} script -immediatly ends its execution. -@end defvar - -@defvar FUNCDIR -@end defvar - -@defvar FUNCDIRNAME -@end defvar - -@defvar FUNCSCRIPT -@end defvar - -@defvar FUNCCONFIG -@end defvar - -@defvar ACTIONNAM -Define action name. - -Each action name identifies an specific action to perform, inside an -specific function. - -Action name names aare passed as second argument in -@file{centos-art.sh} command-line interface. For example, in the -command @samp{centos-art render --entry=path/to/dir --filter=regex}, -the @var{ACTIONNAM} passed to @file{centos-art.sh} script is -@option{--entry}. - -When second argument is not provided, the @file{centos-art.sh} script -immediatly ends its execution. -@end defvar - -@defvar ACTIONVAL -Define action value. - -Action values are associated to just one action name. Action values -contain the working copy entry over which its associated action will be -performed in. Working copy entries can be files or directories inside -the working copy. -@end defvar - -@defvar REGEX -Define regular expression used as pattern to build the list of files -to process. - -By default, @var{REGEX} variable is set to @code{.+} to match all -files. - -Functions that need to build a list of files to process use the option -@option{--filter} to redefine @var{REGEX} variable default value, and -so, control the amount of files to process. -@end defvar - -@defvar ARGUMENTS -Define optional arguments. - -Optional arguments, inside @file{centos-art.sh} script, are considered -as all command-line arguments passed to @file{centos-art.sh} script, -from third argument position on. For example, in the command -@samp{centos-art render --entry=path/to/dir --filter=regex} , the -optional arguments are from @samp{--filter=regex} argument on. - -Optional arguments are parsed using @command{getopt} command through -the following base construction: - -@verbatim -# Define short options we want to support. -local ARGSS="" - -# Define long options we want to support. -local ARGSL="filter:,to:" - -# Parse arguments using getopt(1) command parser. -cli_doParseArguments - -# Reset positional parameters using output from (getopt) argument -# parser. -eval set -- "$ARGUMENTS" - -# Define action to take for each option passed. -while true; do - case "$1" in - --filter ) - REGEX="$2" - shift 2 - ;; - --to ) - TARGET="$2" - shift 2 - ;; - * ) - break - esac -done -@end verbatim - -Optional arguments provide support to command options inside -@file{centos-art.sh} script. For instance, consider the Subversion -(@command{svn}) command, where there are many options (e.g., -@option{copy}, @option{delete}, @option{move}, etc), and inside each -option there are several modifiers (e.g., @samp{--revision}, -@samp{--message}, @samp{--username}, etc.) that can be combined one -another in their short or long variants. - -The @var{ARGUMENTS} variable is used to store arguments passed from -command-line for later use inside @file{centos-art.sh} script. Storing -arguments is specially useful when we want to run a command with some -specific options from them. Consider the following command: - -@verbatim -centos-art path --copy=SOURCE --to=TARGET --message="The commit message goes here." --username='johndoe' -@end verbatim - -In the above command, the @option{--message}, and @option{--username} -options are specific to @command{svn copy} command. In such cases, -options are not interpreted by @file{centos-art.sh} script itself. -Instead, the @file{centos-art.sh} script uses @command{getopt} to -retrive them and store them in the @var{ARGUMENTS} variable for later -use, as described in the following command: - -@verbatim -# Build subversion command to duplicate locations inside the -# workstation. -eval svn copy $SOURCE $TARGET --quiet $ARGUMENTS -@end verbatim - -When @command{getopt} parses @var{ARGUMENTS}, we may use short options -(e.g., @option{-m}) or long options (e.g., @option{--message}). When -we use short options, arguments are separated by one space from the -option (e.g., @option{-m 'This is a commit message.'}). When we use -long options arguments are separated by an equal sign (@samp{=}) -(e.g., @option{--message='This is a commit message'}). - -In order for @command{getopt} to parse @var{ARGUMENTS} correctly, it -is required to provide the short and long definition of options that -will be passed or at least supported by the command performing the -final action the function script exists for. - -As convenction, inside @file{centos-art.sh} script, short option -definitions are set in the @var{ARGSS} variable; and long option -definitions are set in the @var{ARGSL} variable. - -When you define short and long options, it may be needed to define -which of these option arguments are required and which not. To define -an option argument as required, you need to set one colon @samp{:} -after the option definition (e.g., @option{-o m: -l message:}). On -the other hand, to define an option argument as not required, you need -to set two colons @samp{::} after the option definition (e.g., -@option{-o m:: -l message::}). -@end defvar - -@defvar EDITOR -Default text editor. - -The @file{centos-art.sh} script uses default text @env{EDITOR} to edit -pre-commit subversion messages, translation files, configuration -files, script files, and similar text-based files. - -If @env{EDITOR} environment variable is not set, @file{centos-art.sh} -script uses @file{/usr/bin/vim} as default text editor. Otherwise, the -following values are recognized by @file{centos-art.sh} script: - -@itemize -@item @file{/usr/bin/vim} -@item @file{/usr/bin/emacs} -@item @file{/usr/bin/nano} -@end itemize - -If no one of these values is set in @env{EDITOR} environment variable, -@file{centos-art.sh} uses @file{/usr/bin/vim} text editor by default. -@end defvar - -@subsubheading Global functions - -Function scripts stored directly under -@file{trunk/Scripts/Bash/Functions/} directory are used to define -global functions. Global functions can be used inside action specific -functionalities and or even be reused inside themselves. This section -provides introductory information to global functions you can use -inside @file{centos-art.sh} script. - -@defun cli_checkActionArguments -Validate action value (@var{ACTIONVAL}) variable. - -The action value variable can take one of the following values: - -@enumerate -@item Path to one directory inside the local working copy, -@item Path to one file inside the local working copy, -@end enumerate - -If another value different from that specified above is passed to -action value variable, the @file{centos-art.sh} script prints an error -message and ends script execution. -@end defun - -@defun cli_checkFiles FILE [TYPE] -Verify file existence. - -@code{cli_checkFiles} receives a @var{FILE} absolute path and performs -file verification as specified in @var{TYPE}. When @var{TYPE} is not -specified, @code{cli_checkFiles} verifies @var{FILE} existence, no -matter what kind of file it be. If @var{TYPE} is specified, use one -of the following values: - -@table @option -@item d -@itemx directory -Ends script execution if @var{FILE} is not a directory. - -When you verify directories with cli_checkFiles, if directory doesn't -exist, @file{centos-art.sh} script asks you for confirmation in order -to create that directory. If you answer positively, -@file{centos-art.sh} script creates that directory and continues -script flows normally. Otherwise, if you answer negatively, -@file{centos-art.sh} ends script execution with an error and -documentation message. - -@item f -@item regular-file -Ends script execution if @var{FILE} is not a regular file. -@item h -@itemx symbolic-link -Ends script execution if @var{FILE} is not a symbolic link. -@item x -@itemx execution -Ends script execution if @var{FILE} is not executable. -@item fh -Ends script execution if @var{FILE} is neither a regular file nor a -symbolic link. -@item fd -Ends script execution if @var{FILE} is neither a regular file nor a -directory. -@item isInWorkingCopy -Ends script execution if @var{FILE} is not inside the working copy. -@end table - -As default behaviour, if @var{FILE} passes all verifications, -@file{centos-art.sh} script continues with its normal flow. -@end defun - -@defun cli_commitRepoChanges [LOCATION] - -Syncronize changes between repository and working copy. - -The @code{cli_commitRepoChanges} function brings changes from the -central repository down to the working copy---using @command{svn -update}---, checks the working copy changes---using @command{svn -status} command---, prints status report---using both @command{svn -update} and @command{svn status} commands output, and finally, commits -recent changes from the working copy up to the repository---using -@command{svn commit} command---. - -Previous to commit the working copy changes up to the central -repository, the @code{cli_commitRepoChanges} function asks you to -verify changes---using @command{svn diff} command---, and later, -another confirmation question is shown to be sure you really want to -commit changes up to central repository. - -If @var{LOCATION} argument is not specified, the value of -@var{ACTIONVAL} variable is used as reference instead. - -@float Figure, trunk/Scripts/Bash/Functions/cli_commitRepoChanges -@verbatim ----------------------------------------------------------------------- ---> Bringing changes from the repository into the working copy ---> Checking changes in the working copy ----------------------------------------------------------------------- -Added 0 file from the repository. -Deleted 0 file from the repository. -Updated 0 file from the repository. -Conflicted 0 file from the repository. -Merged 0 file from the repository. -Modified 4 files from the working copy. -Unversioned 0 file from the working copy. -Deleted 0 file from the working copy. -Added 0 file from the working copy. ----------------------------------------------------------------------- -@end verbatim -@caption{The @code{cli_commitRepoChanges} function output.} -@end float - -Call the @code{cli_commitRepoChanges} function before or/and after -calling functions that modify files or directories inside the working -copy as you may need to. -@end defun - -@defun cli_doParseArguments -Redefine arguments (@var{ARGUMENTS}) global variable using -@command{getopt} command output. For more information about how to use -@code{cli_doParseArguments} function, see @var{ARGUMENTS} variable -description above. -@end defun - -@defun cli_doParseArgumentsReDef $@@ -Initialize/reset arguments (@var{ARGUMENTS}) global variable using -positional parameters variable (@var{$@@}) as reference. - -When we work inside function definitions, positional parameters are -reset to the last function definition positional parameters. If you -need to redefine positional parameters from one specific function, you -need to call @code{cli_doParseArgumentsReDef} with the positional -parameters variable (@var{$@@}), set as first argument, to that -specific function you want to redefine positional parameters at. -@end defun - -@defun cli_getArguments - -Initialize function name (@var{FUNCNAM}), action name -(@var{ACTIONNAM}), and action value (@var{ACTIONVAL}) global -variables, using positional parameters passed in @var{$@@} variable. - -The @code{cli_getArguments} function is called from @code{cli.sh} -function script, using @code{cli} function positional parameters -(i.e., the positional parameters passed as arguments in the -command-line) as first function argument. - -Once command-line positional parameters are accesible to -@file{centos-art.sh} script execution evironment, -@code{cli_getArguments} uses regular expression to retrive -action variables from first and second argument. The first argument -defines the value used as function name (@var{FUNCNAM}), and the -second argument defines both values used as action name -(@var{ACTIONNAM}) and action value (@var{ACTIONVAL}), respectively. - -The first argument is a word in lower case. This word specifies the -name of the functionality you want to use (e.g., @samp{render} to -render images, @samp{manual} to work on documentation, and so on.) - -The second argument has a long option style (e.g., -@samp{--option=value}). The @samp{--option} represents the action name -(@var{ACTIONNAM}), and the characters inbetween the equal sign -(@samp{=}) and the first space character, are considered as the action -value (@var{ACTIONVAL}). In order to provide action values with space -characters inbetween you need to enclose action value with quotes like -in @samp{--option='This is long value with spaces inbetween'}. -Generally, action values are used to specify paths over which the -action name acts on. - -Once action related variables (i.e., @var{FUNCNAM}, @var{ACTIONNAM}, -and @var{ACTIONVAL}) are defined and validated, -@code{cli_getArguments} shifts the positional arguments to remove the -first two arguments passed (i.e., those used to retrive action related -variables) and redefine the arguments (@var{ARGUMENTS}) global -variable with the new positional parameters information. -@end defun - -@defun cli_getFunctions -Initialize funtionalities supported by @file{centos-art.sh} script. - -Functionalities supported by @file{centos-art.sh} script are organized -in functionality directories under -@file{trunk/Scripts/Bash/Functions/} directory. Each functionality -directory stores function scripts to the functionality such directory -was created for. Function scripts contain function definitions. -Function definitions contain several commands focused on achieving one -specific task only (i.e., the one such functionality was created for). - -In order for @file{centos-art.sh} script to recognize a functionality, -such functionality needs to be stored under -@file{trunk/Scripts/Bash/Functions/} in a directory written -capitalized (i.e., the whole name is written in lowercase except the -first character which is in uppercase). The directory where one -specific functionality is stored is known as the @samp{functionality -directory}. - -Inside each functionality directory, the functionalty itself is -implemented through function scripts. Function scripts are organized -in files independently one another and written in @samp{camelCase} -format with the function name as prefix. Separation between prefix -and description is done using underscore (@samp{_}) character. - -In order for @file{centos-art.sh} script to load functionalities -correctly, function definition inside function scripts should be set -using the @samp{function} reserved word, just as in the following -example: - -@verbatim -function prefix_doSomething { - - # Do something here... - -} -@end verbatim - -The above function definition is just a convenction we use, in order -to make identification of function names easier read and automate by -@file{centos-art.sh} script initialization commands, once -@file{centos-art.sh} script determines which functionality directory -to use. Specifically, in order to initialize and export functions, -@file{centos-art.sh} script executes all function scripts inside the -functionality directory, and later @command{grep} on them using a -regular expression pattern, where the @samp{function} reserved word is -used as reference to retrive the function names and export them to -@file{centos-art.sh} script execution environment, and so, make -function definitions ---from function scripts inside the functionality -directory--- available for further calls. - -If the functionality specified in the command-line first argument -doesn't have a functionality directory, @file{centos-art.sh} script -considers the functionality provided in the command-line as invalid -functionality and immediatly stops script execution with an error -message. - -In order to keep visual consistency among function scripts, please -consider using the following function script design model as template -for your own function scripts: - -@verbatim -#!/bin/bash -# -# prefix_doSomething.sh -- This function illustrates function scripts -# design model you can use to create your own function scripts inside -# centos-art.sh script. -# -# Copyright (C) YEAR YOURFULLNAME -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, but -# WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 -# USA. -# -# ---------------------------------------------------------------------- -# $Id$ -# ---------------------------------------------------------------------- - -function prefix_doSomething { - - # Do something here... - -} -@end verbatim -@end defun - -@defun cli_getCountryCodes [FILTER] -Output country codes supported by @file{centos-art.sh} script. - -The @code{cli_getCountryCodes} function outputs a list with country -codes as defined in ISO3166 standard. When @var{FILTER} is provided, -@code{cli_getCountryCodes} outputs country codes that match -@var{FILTER} regular expression pattern. -@end defun - -@defun cli_getCountryName [FILTER] -Outputs country name supported by @file{centos-art.sh} script. - -The @code{cli_getCountryName} function reads one language locale code -in the format LL_CC and outputs the name of its related country as in -ISO3166. If filter is specified, @code{cli_getCountryName} returns the -country name that matches the locale code specified in @var{FILTER}, -exactly. -@end defun - -@defun cli_getCurrentLocale -Output current locale used by @file{centos-art.sh} script. - -The @code{cli_getCurrentLocale} function uses @env{LANG} environment -variable to build a locale pattern that is later applied to -@code{cli_getLocales} function output in order to return the current -locale that @file{centos-art.sh} script works with. - -The current locale information, returned by -@code{cli_getCurrentLocale}, is output from more specific to less -specific. For example, if @samp{en_GB} locale exists in -@code{cli_getLocales} function output, the @samp{en_GB} locale would -take precedence before @samp{en} locale. - -Locale precedence selection is quite important in order to define the -locale type we use for message translations. For example, if -@samp{en_GB} is used, we are also saying that the common language -specification for English language (i.e., @samp{en}) is no longer -used. Instead, we are using English non-common country-specific -language specifications like @samp{en_AU}, @samp{en_BW}, @samp{en_GB}, -@samp{en_US}, etc., for message translations. - -Use @code{cli_getCurrentLocale} function to know what current locale -information to use inside @file{centos-art.sh} script. -@end defun - -@defun cli_getFilesList [LOCATION] -Output list of files to process. - -The @code{cli_getFilesList} function uses @var{LOCATION} variable as -source location to build a list of files just as specified by regular -expression (@var{REGEX}) global variable. Essentially, what the -@code{cli_getFilesList} function does is using @command{find} command -to look for files in the location (@var{LOCATION}) just as posix-egrep -regular expression (@var{REGEX}) specifies. - -If @var{LOCATION} is not specified when @code{cli_getFilesList} -function is called, the action value (@var{ACTIONVAL}) global variable -is used as location value instead. - -By default, if the regular expression (@var{REGEX}) global variable is -not redefined after its first definition in the @code{cli} function, -all files that match default regular expression value (i.e., -@samp{.+}) will be added to the list of files to process. Otherwise, -if you redefine the regular expression global variable after its first -definition in the @code{cli} function and before calling -@code{cli_getFilesList} function, the last value you specifed is used -instead. - -When you need to customize the regular expression (@var{REGEX}) global -variable value inside a function, do not redefine the global variable -(at least you be absolutly convinced you need to). Instead, set the -regular expression global variable as @samp{local} to the function you -need a customized regular expression value for. If we don't redefine -the regular expression global variable as local to the function, or -use another name for the regular expression variable (which is not -very convenient in order to keep the amount of names to remember low), -you may experiment undesired concantenation issues that make your -regular expression to be something different from that you expect them -to be, specially if the function where you are doing the variable -redefinition is called several times during the same script execution. - -As result, the @code{cli_getFilesList} re-defines the value of -@var{FILES} variable with the list of files the @command{find} command -returned. As example, consider the following construction: - -@verbatim -function prefix_doSomething { - - # Initialize the list of files to process. - local FILES='' - - # Initialize location. - local LOCATION=/home/centos/artwork/trunk/Identity/Themes/Models/Default - - # Re-define regular expression to match scalable vector graphic - # files only. Note how we use the global value of REGEX to build a - # new local REGEX value here. - local REGEX="${REGEX}.*\.(svgz|svg)" - - # Redefine list of files to process. - cli_getFilesList $LOCATION - - # Process list of files. - for FILE in $FILES;do - cli_printMessages "$FILE" 'AsResponseLine' - # Do something else here on... - done - -} -@end verbatim - -@end defun - -@defun cli_getLangCodes [FILTER] -Outputs language codes supported by @file{centos-art.sh} script. - -@code{cli_getLangCodes} function outputs a list of language codes as -defined in ISO639 standard. When @var{FILTER} is provided, -@code{cli_getLangCodes} outputs language codes that match @var{FILTER} -regular expression pattern. -@end defun - -@defun cli_getLangName [FILTER] -Outputs language names supported by @file{centos-art.sh} script. - -@code{cli_getLangName} function reads one language locale code in the -format LL_CC and outputs the language related name as in ISO639. If -filter is specified, @code{cli_getLangName} returns the language name -that matches the locale code specified in @var{FILTER}, exactly. -@end defun - -@defun cli_getLocales -Output locale codes supported by @file{centos-art.sh} script. - -Occasionally, you use @code{cli_getLocales} function to add locale -information in non-common country-specific language (@samp{LL_CC}) -format for those languages (e.g., @samp{bn_IN}, @samp{pt_BR}, etc.) -which locale differences cannot be solved using common language -specifications (@samp{LL}) into one unique common locale specification -(e.g., @samp{bn}, @samp{pt}, etc.). -@end defun - -@defun cli_getRepoName NAME TYPE -Sanitate file names. - -Inside @file{centos-art.sh} script, specific functionalities rely both -in @code{cli_getRepoName} and repository file system organization to -achieve their goals. Consider @code{cli_getRepoName} function as -central place to manage file name convenctions for other functions -inside @file{centos-art.sh} script. - -@quotation -@strong{Important} @code{cli_getRepoName} function doesn't verify file -or directory existence, for that purpose use @code{cli_checkFiles} -function instead. -@end quotation - -The @var{NAME} variable contains the file name or directory name you -want to sanitate. - -The @var{TYPE} variable specifies what type of sanitation you want to -perform on @var{NAME}. The @var{TYPE} can be one of the following -values: - -@table @option -@item d -@itemx directory -Sanitate directory @var{NAME}s. -@item f -@item regular-file -Sanitate regular file @var{NAME}s. -@end table - -Use @code{cli_getRepoName} function to sanitate file names and -directory names before their utilization. - -Use @code{cli_getRepoName} when you need to change file name -convenctions inside @file{centos-art.sh} script. - -When we change file name convenctions inside @code{cli_getRepoName} -what we are really changing is the way functions interpret repository -file system organization. Notice that when we change a file name -(e.g., a function name), it is necessary to update all files where -such file name is placed on. This may require a massive substitution -inside the repository, each time we change name convenctions in the -repository (--- @strong{Removed}(pxref:trunk Scripts Bash Functions Path) ---, for more -information). -@end defun - -@defun cli_getRepoStatus [LOCATION] -Request repository status. - -This function requests the status of a @var{LOCATION} inside the -working copy using the @command{svn status} command and returns the -first character in the output line, just as described in @command{svn -help status}. If @var{LOCATION} is not a regular file or a directory, -inside the working copy, the @file{centos-art.sh} script prints a -message and ends its execution. - -Use this function to perform verifications based a repository -@var{LOCATION} status. -@end defun - -@defun cli_getTemporalFile @var{NAME} -Output absolute path to temporal file @var{NAME}. - -The @code{cli_getTemporalFile} function uses @file{/tmp} directory as -source location to store temporal files, the @file{centos-art.sh} -script name, and a random identification string to let you run more -than one @file{centos-art.sh} script simultaneously on the same user -session. For example, due the following temporal file defintion: - -@verbatim -cli_getTemporalFile $FILE -@end verbatim - -If @var{FILE} name is @file{instance.svg} and the unique random string -is @samp{f16f7b51-ac12-4b7f-9e66-72df847f12de}, the final temporal -file, built from previous temporal file definition, would be: - -@verbatim -/tmp/centos-art.sh-f16f7b51-ac12-4b7f-9e66-72df847f12de-instance.svg -@end verbatim - -When you use the @code{cli_getTemporalFile} function to create -temporal files, be sure to remove temporal files created once you've -ended up with them. For example, consider the following construction: - -@verbatim -for FILE in $FILES;do - - # Initialize temporal instance of file. - INSTANCE=$(cli_getTemporalFile $FILE) - - # Do something ... - - # Remove temporal instance of file. - if [[ -f $INSTANCE ]];then - rm $INSTANCE - fi - -done -@end verbatim - -Use the @code{cli_getTemporalFile} function whenever you need to -create temporal files inside @file{centos-art.sh} script. -@end defun - -@defun cli_getThemeName -Output theme name. - -In order for @code{cli_getThemeName} function to extract theme name -correctly, the @var{ACTIONVAL} variable must contain a directory path -under @file{trunk/Identity/Themes/Motifs/} directory structure. -Otherwise, @code{cli_getThemeName} returns an empty string. -@end defun - -@defun cli_printMessage MESSAGE [FORMAT] -Define standard output message definition supported by -@file{centos-art.sh} script. - -When @var{FORMAT} is not specified, @code{cli_printMessage} outputs -information just as it was passed in @var{MESSAGE} variable. -Otherwise, @var{FORMAT} can take one of the following values: - -@table @option -@item AsHeadingLine -To print heading messages. -@verbatim ----------------------------------------------------------------------- -$MESSAGE ----------------------------------------------------------------------- -@end verbatim - -@item AsWarningLine -To print warning messages. -@verbatim ----------------------------------------------------------------------- -WARNING: $MESSAGE ----------------------------------------------------------------------- -@end verbatim - -@item AsNoteLine -To print note messages. -@verbatim ----------------------------------------------------------------------- -NOTE: $MESSAGE ----------------------------------------------------------------------- -@end verbatim - -@item AsUpdatingLine -To print @samp{Updating} messages on two-columns format. -@verbatim -Updating $MESSAGE -@end verbatim - -@item AsRemovingLine -To print @samp{Removing} messages on two-columns format. -@verbatim -Removing $MESSAGE -@end verbatim - -@item AsCheckingLine -To print @samp{Checking} messages on two-columns format. -@verbatim -Checking $MESSAGE -@end verbatim - -@item AsCreatingLine -To print @samp{Creating} messages on two-columns format. -@verbatim -Creating $MESSAGE -@end verbatim - -@item AsSavedAsLine -To print @samp{Saved as} messages on two-columns format. -@verbatim -Saved as $MESSAGE -@end verbatim - -@item AsLinkToLine -To print @samp{Linked to} messages on two-columns format. -@verbatim -Linked to $MESSAGE -@end verbatim - -@item AsMovedToLine -To print @samp{Moved to} messages on two-columns format. -@verbatim -Moved to $MESSAGE -@end verbatim - -@item AsTranslationLine -To print @samp{Translation} messages on two-columns format. -@verbatim -Translation $MESSAGE -@end verbatim - -@item AsConfigurationLine -To print @samp{Configuration} messages on two-columns format. -@verbatim -Configuration $MESSAGE -@end verbatim - -@item AsResponseLine -To print response messages on one-column format. -@verbatim ---> $MESSAGE -@end verbatim - -@item AsRequestLine -To print request messages on one-column format. Request messages -output messages with one colon (@samp{:}) and without trailing newline -(@samp{\n}) at message end. -@verbatim -$MESSAGE: -@end verbatim - -@item AsYesOrNoRequestLine -To print @samp{yes or no} request messages on one-column format. If -something different from @samp{y} is answered (when using -@code{en_US.UTF-8} locale), script execution ends immediatly. - -@verbatim -$MESSAGE [y/N]: -@end verbatim - -When we use @file{centos-art.sh} script in a locale different from -@code{en_US.UTF-8}, confirmation answer may be different from -@samp{y}. For example, if you use @code{es_ES.UTF-8} locale, the -confirmation question would look like: - -@verbatim -$MESSAGE [s/N]: -@end verbatim - -and the confirmation answer would be @samp{s}, as it is on Spanish -@samp{sí} word. - -Definition of which confirmation word to use is set on translation -messages for your specific locale information. --- @strong{Removed}(xref:trunk Scripts -Bash Functions Locale) ---, for more information about locale-specific -translation messages. - -@item AsToKnowMoreLine -To standardize @samp{to know more, run the following command:} -messages. When the @option{AsToKnowMoreLine} option is used, the -@var{MESSAGE} value should be set to @code{"$(caller)"}. @code{caller} -is a Bash builtin that returns the context of the current subroutine -call. @option{AsToKnowMoreLine} option uses @code{caller} builtin -output to build documentation entries dynamically. - -@verbatim ----------------------------------------------------------------------- -To know more, run the following command: -centos-art manual --read='path/to/dir' ----------------------------------------------------------------------- -@end verbatim - -Use @option{AsToKnowMoreLine} option after errors and for intentional -script termination. - -@item AsRegularLine -To standardize regular messages on one-column format. - -When @var{MESSAGE} contains a colon inside (e.g., @samp{description: -message}), the @code{cli_printMessage} function outputs @var{MESSAGE} -on two-columns format. -@end table - -Use @code{cli_printMessage} function whenever you need to output -information from @file{centos-art.sh} script. - -@quotation -@strong{Tip} To improve two-columns format, change the following file: -@verbatim -trunk/Scripts/Bash/Styles/output_forTwoColumns.awk -@end verbatim -@end quotation -@end defun - -@subsubheading Specific functions - The following specific functions of @file{centos-art.sh} script, are available for you to use: -@menu -@comment --- Removed(* Directories trunk Scripts Functions Html::) --- -* Directories trunk Scripts Functions Locale:: -@comment --- Removed(* Directories trunk Scripts Functions Manual::) --- -* Directories trunk Scripts Functions Path:: -* Directories trunk Scripts Functions Render:: -* Directories trunk Scripts Functions Render Config:: -@comment --- Removed(* Directories trunk Scripts Functions Shell::) --- -@comment --- Removed(* Directories trunk Scripts Functions Svg::) --- -* Directories trunk Scripts Functions Prepare:: -@end menu +@itemize +@item @xref{Directories trunk Scripts Functions Prepare}. +@item @xref{Directories trunk Scripts Functions Render}. +@item @xref{Directories trunk Scripts Functions Locale}. +@item @xref{Directories trunk Scripts Functions Help}. +@item @xref{Directories trunk Scripts Functions Path}. +@item @xref{Directories trunk Scripts Functions Tuneup}. +@end itemize @subheading See also -@menu -* Directories trunk Scripts:: -@comment --- Removed(* Directories trunk Scripts Locale::) --- -@end menu +@itemize +@item @ref{Directories trunk Scripts} +@item @ref{Directories trunk} +@end itemize diff --git a/Manual/Directories/trunk/Scripts/Functions/Prepare.texi b/Manual/Directories/trunk/Scripts/Functions/Prepare.texi index 70d29d1..e71d550 100644 --- a/Manual/Directories/trunk/Scripts/Functions/Prepare.texi +++ b/Manual/Directories/trunk/Scripts/Functions/Prepare.texi @@ -308,13 +308,13 @@ GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1989, 1991 Free Software Foundation, Inc. -59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + 675 Mass Ave, Cambridge, MA 02139, USA @end verbatim Do not change the license information under which @file{centos-art.sh} script is released. Instead, if you think a different license must be -used, please share your reasons at @email{centos-devel@@centos-art.sh, -CentOS Developers mailing list}. +used, please share your reasons at @email{centos-devel@@centos-art.sh} +mailing list. See file @url{file:///home/centos/artwork/trunk/Scripts/COPYING,trunk/Scripts/COPYING}, diff --git a/Manual/Introduction/authors.texi b/Manual/Introduction/authors.texi index f8538b5..4a7eba0 100755 --- a/Manual/Introduction/authors.texi +++ b/Manual/Introduction/authors.texi @@ -3,26 +3,37 @@ Repository along the years: @subheading Graphic Design +Work line: @ref{Directories trunk Identity} + @itemize @item Guideon de Kok -@item @email{alain.reguera@@gmail.com,Alain Reguera Delgado}, 2009, 2010, 2011 +@item @email{alain.reguera@@gmail.com,Alain Reguera Delgado} @item @email{marcus@@moeller.org,Marcus Moeller} @end itemize @subheading Documentation + +Work line: @ref{Directories trunk Manual} + @itemize -@item @email{alain.reguera@@gmail.com,Alain Reguera Delgado}, 2009, 2010, 2011 +@item @email{alain.reguera@@gmail.com,Alain Reguera Delgado} @item @email{ralph@@centos.org,Ralph Angenendt} @end itemize @subheading Localization + +Work line: @ref{Directories trunk Locales} + @itemize -@item @email{alain.reguera@@gmail.com,Alain Reguera Delgado} (Spanish), 2009, 2010, 2011 +@item @email{alain.reguera@@gmail.com,Alain Reguera Delgado} (Spanish) @end itemize @subheading Automation + +Work line: @ref{Directories trunk Scripts} + @itemize -@item @email{alain.reguera@@gmail.com,Alain Reguera Delgado}, 2009, 2010, 2011 +@item @email{alain.reguera@@gmail.com,Alain Reguera Delgado} @end itemize @subheading Infrastructure diff --git a/Manual/Introduction/copying.texi b/Manual/Introduction/copying.texi index 50057bb..442012f 100755 --- a/Manual/Introduction/copying.texi +++ b/Manual/Introduction/copying.texi @@ -10,8 +10,8 @@ identity. If you are using the CentOS Artwork Repository for producing your own corporate visual identity, you should remove all The CentOS Trademarks -from your contents and rename the repository to something other than -CentOS Artwork Repository. +from your contents and rename the repository to something different +from CentOS Artwork Repository. The CentOS Artwork Repository organizes files in a very specific way to implement The CentOS Project corporate visual identity. This very diff --git a/Manual/Introduction/repo-convenctions.texi b/Manual/Introduction/repo-convenctions.texi index 13eb51b..01d825b 100644 --- a/Manual/Introduction/repo-convenctions.texi +++ b/Manual/Introduction/repo-convenctions.texi @@ -14,7 +14,7 @@ independent working copies to interchange data and provides the information required to permit extracting previous versions of files at any time. -@subheading Repository policy +@subsection Repository policy @cindex Repository policy The CentOS Artwork Repository is a collaborative tool that anyone can @@ -56,7 +56,7 @@ License in order for them to remain inside the repository. See file @url{file:///home/centos/artwork/trunk/Scripts/COPYING,trunk/Scripts/COPYING}, for a complete license description. -@subheading Repository organization +@subsection Repository organization @cindex Repository organization The CentOS Artwork Repository uses a @file{trunk}, @file{branches}, @@ -82,7 +82,7 @@ either from the main or the intermediate lines of development. @xref{Directories tags}, for more information. @end table -@subheading Repository file names +@subsection Repository file names @cindex Repository file names Inside the CentOS Artwork Repository, file names are all written in @@ -91,7 +91,7 @@ lowercase (e.g., @samp{01-welcome.png}, @samp{splash.png}, capitalized (e.g., @samp{Identity}, @samp{Themes}, @samp{Motifs}, @samp{TreeFlower}, etc.). -@subheading Repository work lines +@subsection Repository work lines Inside CentOS Artwork Repository there are four major work lines of production which are: @emph{graphic design}, @emph{documentation}, @@ -104,7 +104,7 @@ content produced in one area depends somehow from content produced in another different area. So, a @emph{content production standard} is required for each available work line. -@subsubheading Graphic design +@subsubsection Graphic design @cindex Graphic design work line The graphic design work line exists to cover brand design, typography @@ -171,7 +171,7 @@ itself is controlled by the @code{render} functionality of @xref{Directories trunk Identity}, for more information about The CentOS Corporate Identity and how graphic design fits on it. -@subsubheading Documentation +@subsubsection Documentation @cindex Documentation work line The documentation work line exists to describe what each directory @@ -202,7 +202,7 @@ automate such process yet. @xref{Directories trunk Manual}, for more information on documentation. -@subsubheading Localization +@subsubsection Localization @cindex Localization work line The localization work line exists to provide the translation messages @@ -262,7 +262,7 @@ Artwork Repository be sure to use source files supported either by @xref{Directories trunk Locales}, for more information. -@subsubheading Automation +@subsubsection Automation @cindex Automation work line The automation work line exists to standardize content production in @@ -287,7 +287,7 @@ to benefit. @xref{Directories trunk Scripts}, for more information on automation. -@subheading Connection between directories +@subsection Connection between directories @cindex Connection between directories @cindex Master paths @cindex Auxiliar paths @@ -416,7 +416,7 @@ like Syslinux, Grub, Rhgb, Gdm, Kdm, Gsplash and Ksplash that share a similar file organization to that described above for @file{Anaconda} component. -@subheading Syncronizing path information +@subsection Syncronizing path information @cindex Syncronizing path information Syncronizing path information is the action that keeps all path @@ -483,7 +483,7 @@ exist. The syncronization of path information is aimed to solve these kind of issues. -@subheading Extending repository organization +@subsection Extending repository organization @cindex Extending repository organization Occasionly, you may find that new components of The CentOS Project diff --git a/Manual/repository.info.bz2 b/Manual/repository.info.bz2 index 42562ad..3f64a97 100644 Binary files a/Manual/repository.info.bz2 and b/Manual/repository.info.bz2 differ diff --git a/Manual/repository.pdf b/Manual/repository.pdf index 6e939ad..2795898 100644 Binary files a/Manual/repository.pdf and b/Manual/repository.pdf differ diff --git a/Manual/repository.txt.bz2 b/Manual/repository.txt.bz2 index c717a0c..f9defed 100644 Binary files a/Manual/repository.txt.bz2 and b/Manual/repository.txt.bz2 differ diff --git a/Manual/repository.xhtml.tar.bz2 b/Manual/repository.xhtml.tar.bz2 index c08f98f..fadda21 100644 Binary files a/Manual/repository.xhtml.tar.bz2 and b/Manual/repository.xhtml.tar.bz2 differ diff --git a/Manual/repository.xml b/Manual/repository.xml index ead4c4f..29ca55c 100644 --- a/Manual/repository.xml +++ b/Manual/repository.xml @@ -157,40 +157,44 @@ Authors AuthorsThis section records authoring information of CentOS Artwork Repository along the years: Graphic Design + Work line: Directories trunk Identity • Guideon de Kok - alain.reguera@gmail.comAlain Reguera Delgado, 2009, 2010, 2011 + alain.reguera@gmail.comAlain Reguera Delgado marcus@moeller.orgMarcus Moeller Documentation + Work line: Directories trunk Manual • - alain.reguera@gmail.comAlain Reguera Delgado, 2009, 2010, 2011 + alain.reguera@gmail.comAlain Reguera Delgado ralph@centos.orgRalph Angenendt Localization + Work line: Directories trunk Locales • - alain.reguera@gmail.comAlain Reguera Delgado (Spanish), 2009, 2010, 2011 + alain.reguera@gmail.comAlain Reguera Delgado (Spanish) Automation + Work line: Directories trunk Scripts • - alain.reguera@gmail.comAlain Reguera Delgado, 2009, 2010, 2011 + alain.reguera@gmail.comAlain Reguera Delgado Infrastructure @@ -223,7 +227,7 @@
Copying Conditions Copying conditionsInside the CentOS Artwork Repository you can find content branded by The CentOS Project and content not branded at all. Contents branded by The CentOS Project contain either The CentOS Trademark, The CentOS Logo or The CentOS Symbol. Content branded by The CentOS Project cannot be redistributed without previous conversation with The CentOS Project. However, you can study and modify both content branded by The CentOS Project and content not branded at all in the sake of proposing improvements to The CentOS Project corporate visual identity. - If you are using the CentOS Artwork Repository for producing your own corporate visual identity, you should remove all The CentOS Trademarks from your contents and rename the repository to something other than CentOS Artwork Repository. + If you are using the CentOS Artwork Repository for producing your own corporate visual identity, you should remove all The CentOS Trademarks from your contents and rename the repository to something different from CentOS Artwork Repository. The CentOS Artwork Repository organizes files in a very specific way to implement The CentOS Project corporate visual identity. This very specific organization of files is part of centos-art.sh script, a bash script that automates most of the frequent tasks inside the repository. The centos-art.sh script The centos-art.sh script and the organization of files it needs to work are not in the public domain; they are copyrighted and there are restrictions on their distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of this program that they might get from you. @@ -321,85 +325,111 @@ manual_deleteCrossReferences.sh manual_searchIndex.sh Repository Convenctions Repository convenctionsThe CentOS Artwork Repository is supported by Subversion (http://subversion.tigris.org/), a version control system which allows you to keep old versions of files and directories (usually source code), keep a log of who, when, and why changes occurred, etc., like CVS, RCS or SCCS. When using Subversion there is one source repository and many working copies of that source repository. The working copies are independent one another, can be distributed all around the world and provide a local place for designers, documentors, translators and programmers to perform their works in a descentralized way. The source repository, on the other hand, provides a central place for all independent working copies to interchange data and provides the information required to permit extracting previous versions of files at any time. - Repository policy - Repository policy The CentOS Artwork Repository is a collaborative tool that anyone can have access to. However, changing that tool in any form is something that should be requested in centos-devel@centos.org mailing list. Generally, people download working copies from CentOS Artwork Repository, study the repository organization, make some changes in their working copies, make some tests to verify such changes do work the way expected and finally request access to commit them up to the CentOS Artwork Repository (i.e., the source repository) for others to benefit from them. - Once you've received access to commit your changes, there is no need for you to request permission again to commit other changes from your working copy to CentOS Artwork Repository as long as you behave as a good community citizen. - As a good community citizen one understand of a person who respects the work already done for others and share ideas with authors before changing relevant parts of their work, specially in situations when the access required to realize the changes has been granted already. Of course, there is a time when conversation has taken place, the paths has been traced and changing the work is so obvious that there is no need for you to talk about it; that's because you already did, you already built the trust to keep going. Anyway, the mailing list mentioned above is available for sharing ideas in a way that good relationship between community citizens could be constantly balanced. - The relationship between community citizens is monitored by repository administrators. Repository administrators are responsible of granting everything goes the way it needs to go in order for the CentOS Artwork Repository to comply its mission which is: to provide a colaborative tool for The CentOS Community where The CentOS Project Corporate Identity is built and maintained from The CentOS Community itself. - It is also important to remember that all source files inside CentOS Artwork Repository should comply the terms of GNU General Public License in order for them to remain inside the repository. See file file:///home/centos/artwork/trunk/Scripts/COPYINGtrunk/Scripts/COPYING, for a complete license description. - Repository organization - Repository organization The CentOS Artwork Repository uses a trunk, branches, and tags organization. - - - trunk - - The trunk directory organizes the main development line of CentOS Artwork Repository. See Directories trunk, for more information. - - - - branches - - The branches directory oranizes intermediate development lines taken from the main development line. See Directories branches, for more information. - - - - tags - - The tags directory organizes frozen development lines taken either from the main or the intermediate lines of development. See Directories tags, for more information. - - -
- Repository file names - Repository file names Inside the CentOS Artwork Repository, file names are all written in lowercase (e.g., 01-welcome.png, splash.png, anaconda_header.png, etc.) and directory names are all written capitalized (e.g., Identity, Themes, Motifs, TreeFlower, etc.). - Repository work lines - Inside CentOS Artwork Repository there are four major work lines of production which are: graphic design, documentation, localization and automation. These work lines describe different areas of content production. Content production inside these specific areas may vary as much as persons be working on them. Producing content in too many different ways may result innapropriate in a collaborative environment like CentOS Artwork Repository where content produced in one area depends somehow from content produced in another different area. So, a content production standard is required for each available work line. - Graphic design - Graphic design work line The graphic design work line exists to cover brand design, typography design and themes design mainly. Additionally, some auxiliar areas like icon design, illustration design, brushes design, patterns designs and palettes of colors are also included here for completeness. - Inside CentOS Artwork Repository graphic design is performed through Inkscape (http://www.inkscape.org/) and GIMP (http://www.gimp.org/). The Inkscape tool is used to create and manipulate scalable vector graphics and export them to PNG format; it also provides a command-line interface that we use to perform massive exportation from SVG files to PNG files in automation scripts. On the other hand, GIMP is used to create and manipulate rastered images, create brushes, patterns and palettes of colors. - - Tip Combine both Inkscape and GIMP specific functionalities and possibilities to produce very beautiful images. - - The CentOS Project Corporate Visual Identity is made of different visual manifestations (e.g., Distributions, Web sites, Stationery, etc.). Visual manifestations implement the corporate identity concepts by mean of images. To produce these images, we decompose image production in design models and artistic motifs. - Design models provide the structural information of images (i.e., dimension, position of common elements in the visible area, translation markers, etc.) and they are generally produced as scalable vector graphics to take advantage of SVG standard, an XML-based standard. - Artistic motifs provide the visual style (i.e., the background information, the look and feel) some design models need to complete the final image produced by automation scripts. Artistic motifs are generally produced as rastered images. - The result produced from combining one design model with one artistic motif is what we know as a theme. Inside themes directory structure (see Directories trunk Identity Themes), you can find several design models and several artistic motifs independently one another that can be albitrarily combined through theme rendition, a flexible way to produce images for different visual manifestations in very specific visual styles. Inside themes directory structure, theme rendition is performed in trunk/Identity/Themes/Motifs directory structure, the required design models are taken from trunk/Identity/Themes/Models directory structure and the action itself is controlled by the render functionality of centos-art.sh script. - In addition to theme rendition you can find direct rendition, too. Direct rendition is another way of image production where there is no artistic motif at all but design models only. Direct rendition is very useful to produce simple content that doesn't need specific background information. Some of these contents are brands, icons and illustrations. Direct rendition is performed in trunk/Identity/Images, the required design models are taken from trunk/Identity/Models directory structure and the action itself is controlled by the render functionality of centos-art.sh script. - See Directories trunk Identity, for more information about The CentOS Corporate Identity and how graphic design fits on it. - Documentation - Documentation work line The documentation work line exists to describe what each directory inside the CentOS Artwork Repository is for, the conceptual ideas behind them and, if possible, how automation scripts make use of them. - The CentOS Artwork Repository documentation is supported by Texinfo, a documentation system that uses a single source file to produce both online information and printed output. - The repository documentation is organized under trunk/Manual directory structure and uses the repository directories as reference. Each directory structure in the repository has a documentation entry associated in the documentation manual. Documentation entries are stored under trunk/Manual/Directories directory structure and the action itself is controlled by the help functionality of centos-art.sh script. - The help functionality let you create, edit and delete documentation entries in a way that you don't need to take care of updating menus, nodes and cross reference information inside the manual structure; the functionality takes care of it for you. However, if you need to write repository documentation that have nothing to do with repository directories (e.g., Preface, Introduction and similar) you need to do it manually, there is no functionality to automate such process yet. - See Directories trunk Manual, for more information on documentation. - Localization - Localization work line The localization work line exists to provide the translation messages required to produce content in different languages. Translation messages inside the repository are stored as portable objects (e.g., .po, .pot) and machine objects (.mo) under trunk/Locales directory structure. - The procedure used to localize content is taken from gettext standard specification. Basically, translatable strings are retrived from source files in order to create portable objects and machine objects for them. These portable objects are editable files that contain the information used by translators to localize the translatable strings retrived from source files. On the other hand, machine objects are produced to be machine-redable only, as its name implies, and are produced from portable objects. - Since gettext needs to extract translatable strings form source files in order to let translators to localize them, we are limitted to use source files supported by gettext program. This is not a limitation at all since gettext supports most popular programming laguages (e.g., C, C++, Java, Bash, Python, Perl, PHP and GNU Awk just to mention a few ones). Nevertheless, formats like SVG, XHTML and Docbook don't figure as supported formats in the list of gettext supported source files. - To translate XML based source files like SVG, XHTML and Docbook we use the xml2po program instead. The xml2po comes with the gnome-doc-utils package and retrives translatable strings from one XML file to produce portable objects for them. - - Note Portable objects produced by xml2po have the same format that portable objects produced by gettext. This make the localization process quite consistent from translators' point of view. No matter what the source file be, the translator will always face the same translation file format (i.e., the portable object format). - - With the portable object in place, the xml2po program is used again to create the final translated XML, just with the same definition of the source file where translatable strings were taken from (e.g., if we extract translatable strings from a SVG file, as result we get the same SVG file but with translatable strings already localized —obviously, for this to happen translators need to localize translatable strings inside the portable object first, localization won't appear as art of magic—). When using xml2po, the machine object is used as temporal file to produce the final translated XML file. - - Tip If you want to have your content localized inside CentOS Artwork Repository be sure to use source files supported either by gettext or xml2po programs. - - See Directories trunk Locales, for more information. - Automation - 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. - The automation work line takes place under trunk/Scripts directory structure. Here is developed the centos-art.sh script, a bash script specially designed to automate most frequent tasks (e.g., rendition, documentation and localization) inside the repository. Basically, the centos-art.sh script is divided in several functionalities independent one another that perform specific tasks and relay on repository organization to work as expected. - - Tip If you need to improve the way content is produced, look inside automation scripts and make your improvement there for everyone to benefit. - - See Directories trunk Scripts, for more information on automation. - Connection between directories - Connection between directoriesMaster pathsAuxiliar paths In order to produce content in CentOS Artwork Repository, it is required that all work lines be connected somehow. This is the way automation scripts can know where to retrive the information they need to work with (e.g., design model, translation messages, output location, etc.). We build this kind of connection using two path constructions named master paths and auxiliar paths. - The master path points only to directories that contain the source files (e.g., SVG files) required to produce base content (e.g., PNG files) through automation scripts. Each master path inside the repository may have several auxiliar paths associated, but auxiliar paths can only have one master path associated. - The auxiliar paths can point either to directories or files. When an auxiliar path points to a directory, that directory contains information that modifies somehow the content produced from master paths (e.g., translation messages) or provides the output information required to know where to store the content produced from master path. When an auxiliar path points to a file, that file has no other purpose but to document the master path it refers to. - The relation between auxiliar paths and master paths is realized combining two path informations which are: the master path itself and one second level directory structure from the repository. Generally, the master path is considered the path identifier and the second level directory structure taken from the repository is considered the common part of the path where the identifier is appended. - - Figure - - + Repository policy + Repository policy The CentOS Artwork Repository is a collaborative tool that anyone can have access to. However, changing that tool in any form is something that should be requested in centos-devel@centos.org mailing list. Generally, people download working copies from CentOS Artwork Repository, study the repository organization, make some changes in their working copies, make some tests to verify such changes do work the way expected and finally request access to commit them up to the CentOS Artwork Repository (i.e., the source repository) for others to benefit from them. + Once you've received access to commit your changes, there is no need for you to request permission again to commit other changes from your working copy to CentOS Artwork Repository as long as you behave as a good community citizen. + As a good community citizen one understand of a person who respects the work already done for others and share ideas with authors before changing relevant parts of their work, specially in situations when the access required to realize the changes has been granted already. Of course, there is a time when conversation has taken place, the paths has been traced and changing the work is so obvious that there is no need for you to talk about it; that's because you already did, you already built the trust to keep going. Anyway, the mailing list mentioned above is available for sharing ideas in a way that good relationship between community citizens could be constantly balanced. + The relationship between community citizens is monitored by repository administrators. Repository administrators are responsible of granting everything goes the way it needs to go in order for the CentOS Artwork Repository to comply its mission which is: to provide a colaborative tool for The CentOS Community where The CentOS Project Corporate Identity is built and maintained from The CentOS Community itself. + It is also important to remember that all source files inside CentOS Artwork Repository should comply the terms of GNU General Public License in order for them to remain inside the repository. See file file:///home/centos/artwork/trunk/Scripts/COPYINGtrunk/Scripts/COPYING, for a complete license description. + + + + Repository organization + Repository organization The CentOS Artwork Repository uses a trunk, branches, and tags organization. + + + trunk + + The trunk directory organizes the main development line of CentOS Artwork Repository. See Directories trunk, for more information. + + + + branches + + The branches directory oranizes intermediate development lines taken from the main development line. See Directories branches, for more information. + + + + tags + + The tags directory organizes frozen development lines taken either from the main or the intermediate lines of development. See Directories tags, for more information. + + +
+ + + + Repository file names + Repository file names Inside the CentOS Artwork Repository, file names are all written in lowercase (e.g., 01-welcome.png, splash.png, anaconda_header.png, etc.) and directory names are all written capitalized (e.g., Identity, Themes, Motifs, TreeFlower, etc.). + + + + Repository work lines + Inside CentOS Artwork Repository there are four major work lines of production which are: graphic design, documentation, localization and automation. These work lines describe different areas of content production. Content production inside these specific areas may vary as much as persons be working on them. Producing content in too many different ways may result innapropriate in a collaborative environment like CentOS Artwork Repository where content produced in one area depends somehow from content produced in another different area. So, a content production standard is required for each available work line. + + + Graphic design + Graphic design work line The graphic design work line exists to cover brand design, typography design and themes design mainly. Additionally, some auxiliar areas like icon design, illustration design, brushes design, patterns designs and palettes of colors are also included here for completeness. + Inside CentOS Artwork Repository graphic design is performed through Inkscape (http://www.inkscape.org/) and GIMP (http://www.gimp.org/). The Inkscape tool is used to create and manipulate scalable vector graphics and export them to PNG format; it also provides a command-line interface that we use to perform massive exportation from SVG files to PNG files in automation scripts. On the other hand, GIMP is used to create and manipulate rastered images, create brushes, patterns and palettes of colors. + + Tip Combine both Inkscape and GIMP specific functionalities and possibilities to produce very beautiful images. + + The CentOS Project Corporate Visual Identity is made of different visual manifestations (e.g., Distributions, Web sites, Stationery, etc.). Visual manifestations implement the corporate identity concepts by mean of images. To produce these images, we decompose image production in design models and artistic motifs. + Design models provide the structural information of images (i.e., dimension, position of common elements in the visible area, translation markers, etc.) and they are generally produced as scalable vector graphics to take advantage of SVG standard, an XML-based standard. + Artistic motifs provide the visual style (i.e., the background information, the look and feel) some design models need to complete the final image produced by automation scripts. Artistic motifs are generally produced as rastered images. + The result produced from combining one design model with one artistic motif is what we know as a theme. Inside themes directory structure (see Directories trunk Identity Themes), you can find several design models and several artistic motifs independently one another that can be albitrarily combined through theme rendition, a flexible way to produce images for different visual manifestations in very specific visual styles. Inside themes directory structure, theme rendition is performed in trunk/Identity/Themes/Motifs directory structure, the required design models are taken from trunk/Identity/Themes/Models directory structure and the action itself is controlled by the render functionality of centos-art.sh script. + In addition to theme rendition you can find direct rendition, too. Direct rendition is another way of image production where there is no artistic motif at all but design models only. Direct rendition is very useful to produce simple content that doesn't need specific background information. Some of these contents are brands, icons and illustrations. Direct rendition is performed in trunk/Identity/Images, the required design models are taken from trunk/Identity/Models directory structure and the action itself is controlled by the render functionality of centos-art.sh script. + See Directories trunk Identity, for more information about The CentOS Corporate Identity and how graphic design fits on it. + + + + Documentation + Documentation work line The documentation work line exists to describe what each directory inside the CentOS Artwork Repository is for, the conceptual ideas behind them and, if possible, how automation scripts make use of them. + The CentOS Artwork Repository documentation is supported by Texinfo, a documentation system that uses a single source file to produce both online information and printed output. + The repository documentation is organized under trunk/Manual directory structure and uses the repository directories as reference. Each directory structure in the repository has a documentation entry associated in the documentation manual. Documentation entries are stored under trunk/Manual/Directories directory structure and the action itself is controlled by the help functionality of centos-art.sh script. + The help functionality let you create, edit and delete documentation entries in a way that you don't need to take care of updating menus, nodes and cross reference information inside the manual structure; the functionality takes care of it for you. However, if you need to write repository documentation that have nothing to do with repository directories (e.g., Preface, Introduction and similar) you need to do it manually, there is no functionality to automate such process yet. + See Directories trunk Manual, for more information on documentation. + + + + Localization + Localization work line The localization work line exists to provide the translation messages required to produce content in different languages. Translation messages inside the repository are stored as portable objects (e.g., .po, .pot) and machine objects (.mo) under trunk/Locales directory structure. + The procedure used to localize content is taken from gettext standard specification. Basically, translatable strings are retrived from source files in order to create portable objects and machine objects for them. These portable objects are editable files that contain the information used by translators to localize the translatable strings retrived from source files. On the other hand, machine objects are produced to be machine-redable only, as its name implies, and are produced from portable objects. + Since gettext needs to extract translatable strings form source files in order to let translators to localize them, we are limitted to use source files supported by gettext program. This is not a limitation at all since gettext supports most popular programming laguages (e.g., C, C++, Java, Bash, Python, Perl, PHP and GNU Awk just to mention a few ones). Nevertheless, formats like SVG, XHTML and Docbook don't figure as supported formats in the list of gettext supported source files. + To translate XML based source files like SVG, XHTML and Docbook we use the xml2po program instead. The xml2po comes with the gnome-doc-utils package and retrives translatable strings from one XML file to produce portable objects for them. + + Note Portable objects produced by xml2po have the same format that portable objects produced by gettext. This make the localization process quite consistent from translators' point of view. No matter what the source file be, the translator will always face the same translation file format (i.e., the portable object format). + + With the portable object in place, the xml2po program is used again to create the final translated XML, just with the same definition of the source file where translatable strings were taken from (e.g., if we extract translatable strings from a SVG file, as result we get the same SVG file but with translatable strings already localized —obviously, for this to happen translators need to localize translatable strings inside the portable object first, localization won't appear as art of magic—). When using xml2po, the machine object is used as temporal file to produce the final translated XML file. + + Tip If you want to have your content localized inside CentOS Artwork Repository be sure to use source files supported either by gettext or xml2po programs. + + See Directories trunk Locales, for more information. + + + + Automation + 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. + The automation work line takes place under trunk/Scripts directory structure. Here is developed the centos-art.sh script, a bash script specially designed to automate most frequent tasks (e.g., rendition, documentation and localization) inside the repository. Basically, the centos-art.sh script is divided in several functionalities independent one another that perform specific tasks and relay on repository organization to work as expected. + + Tip If you need to improve the way content is produced, look inside automation scripts and make your improvement there for everyone to benefit. + + See Directories trunk Scripts, for more information on automation. + + + + + Connection between directories + Connection between directoriesMaster pathsAuxiliar paths In order to produce content in CentOS Artwork Repository, it is required that all work lines be connected somehow. This is the way automation scripts can know where to retrive the information they need to work with (e.g., design model, translation messages, output location, etc.). We build this kind of connection using two path constructions named master paths and auxiliar paths. + The master path points only to directories that contain the source files (e.g., SVG files) required to produce base content (e.g., PNG files) through automation scripts. Each master path inside the repository may have several auxiliar paths associated, but auxiliar paths can only have one master path associated. + The auxiliar paths can point either to directories or files. When an auxiliar path points to a directory, that directory contains information that modifies somehow the content produced from master paths (e.g., translation messages) or provides the output information required to know where to store the content produced from master path. When an auxiliar path points to a file, that file has no other purpose but to document the master path it refers to. + The relation between auxiliar paths and master paths is realized combining two path informations which are: the master path itself and one second level directory structure from the repository. Generally, the master path is considered the path identifier and the second level directory structure taken from the repository is considered the common part of the path where the identifier is appended. + + Figure + + - Path construction. - - The path information described above (see Path construction) is used by direct rendition and can be taken as reference to add other components that are equally produced in the repository. To add new components that make use of direct rendition inside the repository, change just the component name used above (e.g., Brands) to that one you want to add, without changing the path structure around it. - The file organization used by theme rendition extends direct rendition by separating design models information from backgrounds information. To better understand this configuration, you can consider it as two independent lists, one of design models and one of artistic motifs, which are arbitrary combined between themselves in order to render images in specific ways. The possibilities of this configuration are endless and let us describe visual manifestations very well. For example, consider the organization used to produce Anaconda images; for CentOS distribution major release 5; using Default design models and version 3 of Flame artistic motif: - - Figure - - Path construction. + + The path information described above (see Path construction) is used by direct rendition and can be taken as reference to add other components that are equally produced in the repository. To add new components that make use of direct rendition inside the repository, change just the component name used above (e.g., Brands) to that one you want to add, without changing the path structure around it. + The file organization used by theme rendition extends direct rendition by separating design models information from backgrounds information. To better understand this configuration, you can consider it as two independent lists, one of design models and one of artistic motifs, which are arbitrary combined between themselves in order to render images in specific ways. The possibilities of this configuration are endless and let us describe visual manifestations very well. For example, consider the organization used to produce Anaconda images; for CentOS distribution major release 5; using Default design models and version 3 of Flame artistic motif: + + Figure + + - Path construction extended. - - The path information described above (see Path construction extended) is used by theme rendition and can be taken as reference to add other components that are equally produced in the repository. - In this configuration we can change both design model name (e.g., Default) and artistic motif name (e.g., Flame/3) to something else in order to achieve a different result. The only limitations impossed are the storage space provided in the server machine and your own creativeness as graphic designer. - - Note A theme ready for implementation may consume from 100 MB to 400 MB of storage space. The exact space consumed by a theme depends on the amount of screen resolutions the theme supports. The more screen resolutions the theme supports, the more storage space demanded for it. - - In this configuration we saw how to build the path information for Anaconda component as part of CentOS Distribution visual manifestation, but that is not the only component we have inside CentOS Distribution visual manifestation. There are other components like Syslinux, Grub, Rhgb, Gdm, Kdm, Gsplash and Ksplash that share a similar file organization to that described above for Anaconda component. - Syncronizing path information - Syncronizing path information Syncronizing path information is the action that keeps all path information up to date in the repository. This action implies both file movement and file content replacement in this very specific order. File movement is related to duplicate, delete and rename files and directories in the repository. File content replacement is related to replace information, path information in this case, inside files in the repository. - The order followed to syncronize path information is relevant because the versioned nature of the files we are working with. We don't perform file content replacement first because that would imply a repository change which will immediatly demmand a commit in order for actions like duplicate, delete or rename to take place. However, if we perform file movement first, it is possible to commit both file moved and file content replacements as if they were just one change. In this case the file content replacement takes palce in the target location that have been duplicated or renamed, not the one use as source location. This configuration is specially useful when files are renamed (i.e., one file is copied from a source location to a target location and then the source location of it is removed from repository). - - Warning There is no support for URLs actions inside centos-art.sh script. The centos-art.sh script is designed to work with local files inside the working copy only. If you need to perform URL actions directly, use Subversion commands instead. - - When one master path is changed it is required that all related auxiliar paths be changed, too. This is required in order for master paths to retain their relation with auxiliar paths. This way, automation scripts are able to know where to retrive translation messages from, where to store final output images to and where to look for documentation. If relation between master paths and auxiliar paths is lost, there is no way for automation scripts to know where to retrive the information they need. - The auxiliar paths should never be modified under any reason but to satisfy the relationship with the master path. Liberal change of auxiliar paths may suppress the conceptual idea they were initially created for; and certainly, automation scripts may stop working as expected. The update direction to rename path information must be from master path to auxiliar path and never the opposite. - The relation between master and auxiliar paths is useful to keep repository organized but introduce some complications when we work with files that use master path information as reference to build structural information. This is the case of repository documentation manual source files where inclusions, menus, nodes and cross references are built using master path information as reference. Now, to see what kind of complication we are talking about, consider what would happen to a structural definitions (i.e., inlusions, menus, nodes and cross refereces) already set in the manual from one master path that is suddenly renamed to something different. If the path information is not syncronized, at this point, we lose connection between the master path and the auxiliar path created to store the related documentation entry, as well as the related structural definitions that end up pointing to a master path that no longer exist. - The syncronization of path information is aimed to solve these kind of issues. - Extending repository organization - Extending repository organization Occasionly, you may find that new components of The CentOS Project Corporate Identity need to be added to the repository in order to work them out. If that is the case, the first question we need to ask ourselves, before start to create directories blindly all over, is: What is the right place to store it? - The best place to find answers is in The CentOS Community (see page http://wiki.centos.org/GettingHelp), but going there with hands empty is not good idea. It may give the impression you don't really care about. Instead, consider the following suggestions to find your own comprehension in order to make your own propositions based on it. - When extending respository structure it is very useful to bear in mind The CentOS Project Corporate Identity Structure (see Directories trunk Identity) The CentOS Mission and The CentOS Release Schema. The rest is just matter of choosing appropriate names. It is also worth to know that each directory in the repository responds to a conceptual idea that justifies its existence. - To build a directory structure, you need to define the conceptual idea first and later create the directory. There are some locations inside the repository that already define some concepts you probably want to reuse. For example, trunk/Identity/Themes/Motifs to store theme artistic motifs, trunk/Identity/Themes/Models to store theme design models, trunk/Manual to store documentation files, trunk/Locales to store translation messages, trunk/Scripts to store automation scripts and so on. - To illustrate this desition process let's consider the trunk/Identity/Themes/Motifs/TreeFlower/3 directory structure as example. This directory can be read as: the theme development line of version 3 of TreeFlower artistic motif. Additional, we can identify that artistic motifs are part of themes as well as themes are part of The CentOS Project Corporate Identity. These concepts are better described independently in each documentation entry related to the directory structure as it is respectively shown in the list of commands bellow. - Path construction extended. + + The path information described above (see Path construction extended) is used by theme rendition and can be taken as reference to add other components that are equally produced in the repository. + In this configuration we can change both design model name (e.g., Default) and artistic motif name (e.g., Flame/3) to something else in order to achieve a different result. The only limitations impossed are the storage space provided in the server machine and your own creativeness as graphic designer. + + Note A theme ready for implementation may consume from 100 MB to 400 MB of storage space. The exact space consumed by a theme depends on the amount of screen resolutions the theme supports. The more screen resolutions the theme supports, the more storage space demanded for it. + + In this configuration we saw how to build the path information for Anaconda component as part of CentOS Distribution visual manifestation, but that is not the only component we have inside CentOS Distribution visual manifestation. There are other components like Syslinux, Grub, Rhgb, Gdm, Kdm, Gsplash and Ksplash that share a similar file organization to that described above for Anaconda component. + + + + Syncronizing path information + Syncronizing path information Syncronizing path information is the action that keeps all path information up to date in the repository. This action implies both file movement and file content replacement in this very specific order. File movement is related to duplicate, delete and rename files and directories in the repository. File content replacement is related to replace information, path information in this case, inside files in the repository. + The order followed to syncronize path information is relevant because the versioned nature of the files we are working with. We don't perform file content replacement first because that would imply a repository change which will immediatly demmand a commit in order for actions like duplicate, delete or rename to take place. However, if we perform file movement first, it is possible to commit both file moved and file content replacements as if they were just one change. In this case the file content replacement takes palce in the target location that have been duplicated or renamed, not the one use as source location. This configuration is specially useful when files are renamed (i.e., one file is copied from a source location to a target location and then the source location of it is removed from repository). + + Warning There is no support for URLs actions inside centos-art.sh script. The centos-art.sh script is designed to work with local files inside the working copy only. If you need to perform URL actions directly, use Subversion commands instead. + + When one master path is changed it is required that all related auxiliar paths be changed, too. This is required in order for master paths to retain their relation with auxiliar paths. This way, automation scripts are able to know where to retrive translation messages from, where to store final output images to and where to look for documentation. If relation between master paths and auxiliar paths is lost, there is no way for automation scripts to know where to retrive the information they need. + The auxiliar paths should never be modified under any reason but to satisfy the relationship with the master path. Liberal change of auxiliar paths may suppress the conceptual idea they were initially created for; and certainly, automation scripts may stop working as expected. The update direction to rename path information must be from master path to auxiliar path and never the opposite. + The relation between master and auxiliar paths is useful to keep repository organized but introduce some complications when we work with files that use master path information as reference to build structural information. This is the case of repository documentation manual source files where inclusions, menus, nodes and cross references are built using master path information as reference. Now, to see what kind of complication we are talking about, consider what would happen to a structural definitions (i.e., inlusions, menus, nodes and cross refereces) already set in the manual from one master path that is suddenly renamed to something different. If the path information is not syncronized, at this point, we lose connection between the master path and the auxiliar path created to store the related documentation entry, as well as the related structural definitions that end up pointing to a master path that no longer exist. + The syncronization of path information is aimed to solve these kind of issues. + + + + Extending repository organization + Extending repository organization Occasionly, you may find that new components of The CentOS Project Corporate Identity need to be added to the repository in order to work them out. If that is the case, the first question we need to ask ourselves, before start to create directories blindly all over, is: What is the right place to store it? + The best place to find answers is in The CentOS Community (see page http://wiki.centos.org/GettingHelp), but going there with hands empty is not good idea. It may give the impression you don't really care about. Instead, consider the following suggestions to find your own comprehension in order to make your own propositions based on it. + When extending respository structure it is very useful to bear in mind The CentOS Project Corporate Identity Structure (see Directories trunk Identity) The CentOS Mission and The CentOS Release Schema. The rest is just matter of choosing appropriate names. It is also worth to know that each directory in the repository responds to a conceptual idea that justifies its existence. + To build a directory structure, you need to define the conceptual idea first and later create the directory. There are some locations inside the repository that already define some concepts you probably want to reuse. For example, trunk/Identity/Themes/Motifs to store theme artistic motifs, trunk/Identity/Themes/Models to store theme design models, trunk/Manual to store documentation files, trunk/Locales to store translation messages, trunk/Scripts to store automation scripts and so on. + To illustrate this desition process let's consider the trunk/Identity/Themes/Motifs/TreeFlower/3 directory structure as example. This directory can be read as: the theme development line of version 3 of TreeFlower artistic motif. Additional, we can identify that artistic motifs are part of themes as well as themes are part of The CentOS Project Corporate Identity. These concepts are better described independently in each documentation entry related to the directory structure as it is respectively shown in the list of commands bellow. + - The concepts behind other location can be found in the same way described above, just change the path information used above to the one you are trying to know concepts for. + The concepts behind other location can be found in the same way described above, just change the path information used above to the one you are trying to know concepts for. +
@@ -718,6 +755,11 @@ centos-art help --read turnk/Identity/Themes/Motifs/TreeFlower/3 Directories trunk Scripts Functions Render Config + + Directories trunk Scripts Functions Tuneup + Directories trunk Scripts Functions Tuneup + + @@ -790,9 +832,6 @@ centos-art help --read turnk/Identity/Themes/Motifs/TreeFlower/3 The trunk/ directory structure implements the Subversion's trunk concept in a trunk, branches, tags repository structure. Description The trunk/ directory structure provides the main development line inside the CentOS Artwork Repository. - Automation - 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 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. Usage • @@ -2423,106 +2462,74 @@ priority=10 The <file>trunk/Scripts</file> Directory Directories trunk Scripts Goals - The trunk/Scripts directory exists to organize the trunk development line of centos-art.sh automation script. The centos-art.sh script standardizes tasks you need to do frequently inside CentOS Artwork Repository. + 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 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. Description The best way to understand centos-art.sh automation script is studying its source code. However, as start point, you may prefer to read an introductory resume before diving into the source code details. The centos-art.sh script is written in Bash. Most tasks, inside centos-art.sh script, have been organized in many specific functionalities that you can invoke from the centos-art command-line interface. - When you type the centos-art command in your terminal, the operating system trys to execute that command. In order to execute the command, the operating system needs to know where it is, so the operating system uses the PATH environment variable to look for that command location. If your system was prepared to use CentOS Artwork Repository correctly (— Removed(pxref:trunk Scripts Bash Functions Verify) —), you should have a symbolic link inside ~/bin/ directory that points to the centos-art.sh script file. As ~/bin/ directory is, by default, inside PATH environment variable, the execution of centos-art command runs the centos-art.sh script. - When centos-art.sh script is executed, the first it does is executing the trunk/Scripts/Bash/initEnvironment.sh script to initialize global variables (e.g., gettext variables) and global function scripts. Global function scripts are located inside trunk/Scripts/Bash/Functions directory and their file names begin with cli. Global function scripts provide common functionalities that can be used anywhere inside centos-art.sh script execution environment. - Once global variables and function scripts have been loaded, centos-art.sh script executes the cli global function from cli.sh function script to retrive command-line arguments and define some default values that may be used later by specific function scripts (— Removed(pxref:trunk Scripts Bash Functions) —). + When you type the centos-art command in your terminal, the operating system trys to execute that command. In order to execute the command, the operating system needs to know where it is, so the operating system uses the PATH environment variable to look for that command location. If your system was prepared to use CentOS Artwork Repository correctly (see Directories trunk Scripts Functions Prepare) you should have a symbolic link inside ~/bin directory that points to the centos-art.sh script file. As ~/bin directory is, by default, inside PATH environment variable, the execution of centos-art command runs the centos-art.sh script. + When centos-art.sh script is executed, the first it does is initializing global variables (e.g., gettext variables) and global function scripts. Global function scripts are located inside trunk/Scripts/Functions directory and their file names begin with cli. Global function scripts provide common functionalities that can be used anywhere inside centos-art.sh script execution environment. + Once global variables and function scripts have been loaded, centos-art.sh script executes the cli global function from cli.sh function script to retrive command-line arguments and define some default values that may be used later by specific function scripts (see Directories trunk Scripts Functions). As convenction, the centos-art.sh command-line arguments have the following format: In the above example, centos-art is the command you use to invoke centos-art.sh script. The arg1 is required and represents the functionality you want to perform (e.g., , , , , etc.). The remaining arguments are modifiers to . The definition is required and represets, specifically, the action inside the functionality you want to perform. The and on, are optional. Once command-line arguments have been retrived, the centos-art.sh script loads specific functionalities using the cli_getFunctions.sh function script. Only one specific functionality can be loaded at one script execution I.e., you run centos-art.sh script to run just one functionality. - + Figure ~/artwork/trunk/Scripts/centos-art.sh | -+---v-----------------------------------------v------------------------+ - | centos-art.sh | - +---v---------------------------------v---+ - . | initEnvironment.sh | . - . +---------------------------------+ . - . | cli $@ | . - . +---v-------------------------v---+ . - . . | cli_getFunctions | . . - . . +---v-----------------v---+ . . - . . . | function1 | . . . - . . . | function2 | . . . - . . . | function3 | . . . - . . . +-----------------+ . . . - . . ........................... . . - . ................................... . - ........................................... -]]> - The functionalities initialization environment. ++---v--------------------------------------------------------------v---+ + | centos-art.sh | + +-v--------------------------------------------------------v---+ + . | cli $@ | . + . +-v--------------------------------------------------v---+ . + . . | cli_getFunctions | . . + . . +-v-----------v-----------v-----------v------------+ . . + . . . | function1 | function2 | functionN | . . . + . . . +-----------+-----------+-----------+ . . . + . . .................................................... . . + . .......................................................... . + ................................................................ +]]> + Functionalities initialization environment. Functionalities are implemented by means of actions. Once the functionality has been initiazalized, actions initialization take place for that functionality. Actions initialization model is very similar to functions initialization model. But with the difference, that actions are loaded inside function environment, and so, share variables and functions defined inside function environment. - + Figure - The actions initialization environment. ++----------------------------------------------------------------------+ +| cli_getFunctions | ++---v----------------------------v----v----------------------------v---+ +. | function1 | | function2 | . +. +-v------------------------v-+ +-v------------------------v-+ . +. . | function1_getArguments | . . | function2_getArguments | . . +. . +-v--------------------v-+ . . +-v--------------------v-+ . . +. . . | action 1 | . . . . | action 1 | . . . +. . . | action 2 | . . . . | action 2 | . . . +. . . | action N | . . . . | action N | . . . +. . . +--------------------+ . . . . +--------------------+ . . . +. . .......................... . . .......................... . . +. .............................. .............................. . +........................................................................ +]]> + Actions initialization environment. Usage - The centos-art.sh script usage information is described inside each specific function documentation (— Removed(pxref:trunk Scripts Bash Functions) —). + The centos-art.sh script usage information is described inside each specific function documentation (see Directories trunk Scripts Functions). See also - - - Directories trunk Scripts - Directories trunk Scripts - - - - Directories trunk Scripts Functions - Directories trunk Scripts Functions - - - - + + • + + Directories trunk + + @@ -2534,28 +2541,21 @@ centos-art function path/to/dir --options The <file>trunk/Scripts/Functions</file> Directory Directories trunk Scripts Functions Goals - The trunk/Scripts/Bash/Functions directory exists to organize centos-art.sh specific functionalities. + The trunk/Scripts/Functions directory exists to organize centos-art.sh specific functionalities. Description - The specific functions of centos-art.sh script are designed with “Software Toolbox” philosophy (see Toolbox introductioncoreutils.info) in mind: each program “should do one thing well”. Inside centos-art.sh script, each specific functionality is considered a program that should do one thing well. Of course, if you find that they still don't do it, feel free to improve them in order for them to do so. - The specific functions of centos-art.sh script are organized inside specific directories under trunk/Scripts/Bash/Functions location. Each specific function directory should be named as the function it represents, with the first letter in uppercase. For example, if the function name is render, the specific function directory for it would be trunk/Scripts/Bash/Functions/Render. - To better understand how specific functions of centos-art.sh script are designed, lets create one function which only goal is to output different kind of greetings to your screen. - When we create specific functions for centos-art.sh script it is crucial to know what these functions will do exactly and if there is any function that already does what we intend to do. If there is no one, it is good time to create them then. Otherwise, if functionalities already available don't do what you exactly expect, contact their authors and work together to improve them. - - Tip Join CentOS developers mailing list centos-art@centos.org to share your ideas. - - It is also worth to know what global functions and variables do we have available inside centos-art.sh script, so advantage can be taken from them. Global variables are defined inside global function scripts. Global functions scripts are stored immediatly under trunk/Scripts/Bash/Functions directory, in files begining with cli prefix. - OK, let's begin with our functionality example. - What function name do we use? Well, lets use greet. Note that hello word is not a verb; but an expression, a kind of greeting, an interjection specifically. In contrast, greet is a verb and describes what we do when we say Hello!, Hi!, and similar expressions. - So far, we've gathered the following function information: + The specific functions of centos-art.sh script are designed with the “Software Toolbox” philosophy (Toolbox introductioncoreutils.info) in mind: each program “should do one thing well”. Inside centos-art.sh script, each specific functionality is considered a program that should do one thing well. Of course, if you find that they still don't do it, feel free to improve them in order for them to do so. + The specific functions of centos-art.sh script are organized inside specific directories under trunk/Scripts/Functions location. Each specific function directory should be named as the function it represents, with the first letter in uppercase. For example, if the function name is render, the specific function directory for it would be trunk/Scripts/Functions/Render. + Creating the greet functionality + To better understand how to design specific functions for centos-art.sh script, let's create the greet functionality which only goal is to print out different kind of greetings to your screen. The greet functionality will be set using the follwiing directory structure: - The greet.sh function script is the first file centos-art.sh script loads when the greet functionality is called using commands like centos-art greet --hello='World'. The greet.sh function script contains the greet function definition. - Inside centos-art.sh script, as convenction, each function script has one top commentary, followed by one blank line, and then one function defintion below it only. - Inside centos-art.sh script functions, top commentaries have the following components: the functionality description, one-line for copyright note with your personal information, the license under which the function source code is released —the centos-art.sh script is released as GPL, so do all its functions—, the $Id$ keyword of Subversion is later expanded by svn propset command. - In our greet function example, top commentary for greet.sh function script would look like the following: +trunk/Scripts/Functions/Greet <-- The source location of greet function. +|-- greet_getArguments.sh <-- Defines command-line interface. +|-- greet_sayGoodbye.sh <-- Defines specific action. +|-- greet_sayHello.sh <-- Defines specific action. +`-- greet.sh <-- Defines function initialization. +]]> + The greet.sh file contains the initialization script of greet functionality. It is the first file loaded from function source location by centos-art.sh script when it is executed using the greet functionality as first argument. + Inside centos-art.sh script, as convenction, each function script has one top commentary, followed by one blank line, and then one function defintion below it only. The top commentary has the function description, one-line for copyright notice with your personal information, the license under which the function source code is released —the centos-art.sh script is released as GPL, so do all its functions— and the $Id$ keyword of Subversion which is later expanded by svn propset command. In our example, the top comment of greet.sh function script would look like the following: - After top commentary, separated by one blank line, the greet function definition would look like the following: - - The first definition inside greet function, are global variables that will be available along greet function execution environment. This time we didn't use global variable definitions for greet function execution environment, so we left that section empty. - Later, we call greet_getActions function to define the command-line interface of greet functionality. The command-line interface of greet functionality defines what and how actions are performed, based on arguments combination passed to centos-art.sh script. + The first definition inside greet function is for variables that will be available along the whole execution environment of greet function. This time we didn't define any variable here so, we continued with definition of command-line interface, through greet_getArguments function. + The command-line interface of greet functionality defines how to interpret arguments passed from centos-art.sh script command-line. Inside centos-art.sh script, the interpretation of arguments passed through its command-line takes place by mean of getopt command and is written as the following code example describes: - The ACTIONNAM global variable is defined in cli.sh function script and contains the value passed before the equal sign (i.e., =) in the second command-line argument of centos-art.sh script. For example, if the second command-line argument is , the value of ACTIONNAM variable would be --hello. Using this configuration let us deside which action to perform based on the action name passed to centos-art.sh script as second argument. - The greet function definition makes available two valid greetings through and options. If no one of them is provided as second command-line argument, the * case is evaluated instead. - The * case and its two lines further on should always be present in _getActions.sh function scripts, no matter what specific functionality you are creating. This convenction helps the user to find out documentation about current functionality in use, when no valid action is provided. - The greet_doHello and greet_doBye function definitions are the core of greet specific functionality. In such function definitions we set what our greet function really does: to output different kinds of greetings. + The greet_sayHello and greet_sayGoodbye function definitions are the core of greet specific functionality. In such function definitions we set what our greet function really does: to output different kinds of greetings. - The greet_doHello function definition is stored in greet_doHello.sh function script. + The greet_sayHello function definition is stored in greet_sayHello.sh function script. - The greet_doBye function definition is stored in the greet_doBye.sh function script. - Both greet_doHello.sh and greet_doBye.sh function scripts are stored inside greet function directory path (i.e. trunk/Scripts/Bash/Functions/Greet). - The ACTIONVAL global variable is defined in cli.sh function script and contains the value passed after the equal sign (i.e., =) in the second command-line argument of centos-art.sh script. For example, if the second command-line argument is , the value of ACTIONVAL variable would be World without quotes. - Let's see how greet specific functionality files are organzied under greet function directory. To see file organization we use the tree command: - - To try the greet specific functionality we've just created, pass the function name (i.e., greet) as first argument to centos-art.sh script, and any of the valid options as second argument. Some examples are illustrated below: + The greet_sayGoodbye function definition is stored in the greet_sayGoodbye.sh function script. + Executing the greet functionality + To execute the greet specific functionality we've just created, pass the function name (i.e., greet) as first argument to centos-art.sh script and any of the valid options after it. Some examples are illustrated below: - The word World in the examples above can be anything. In fact, change it to have a little fun. - Now that we have a specific function that works as we expect, it is time to document it. To document greet specific functionality, we use its directory path and the manual functionality (— Removed(pxref:trunk Scripts Bash Functions Manual) —) of centos-art.sh script, just as the following command illustrates: + The word World in the examples above can be anything. Likewise, if you need to change the way either the hello or goodbye messages are printed out, you can modifie the functions greet_sayHello and greet_sayGoodbye, respectively. + Documenting the greet functionality + Now that greet functionality works as we expect, it is time to document it. To document functionalities inside centos-art.sh script we use the function directory path as argument to the help functionality (see Directories trunk Scripts Functions Help) of centos-art.sh script, just as the following command illustrates: - To have a well documented function helps user to understand how your function really works, and how it should be used. When no valid action is passed to a function, the centos-art.sh script uses the function documentation entry as vehicle to communicate which the valid functions are. When no documentation entry exists for a function, the centos-art.sh script informs that no documentation entry exists for such function and requests user to create it right at that time. - Now that we have documented our function, it is time to translate its output messages to different languages. To translate specific functionality output messages to different languages we use the locale functionality (— Removed(pxref:trunk Scripts Bash Functions Locale) —) of centos-art.sh script, just as the following command illustrates: + The function documentation helps to understand how the function really works and how it should be used. Also, when centos-art.sh script ends because an error, the documentation entry related to the functionality being currently executed is used as vehicle to communicate the user what is the correct way of using the functionality. + Localizing the greet functionality + Now that greet functionality has been documented, it is time to localize its output messages. Localizing specific functionalities of centos-art.sh script takes place as part of centos-art.sh script localization itself which is performed by applying the path trunk/Scripts to the locale functionality of centos-art.sh script. + As the greet functionality added new translatable strings to the centos-art.sh script, it is required to update the translation messages firstly, to add the new translatable strings from greet functionality to centos-art.sh script translation messages and then, edit the translation messages of centos-art.sh script to localize the new translatable strings that have been added. To achieve this, execute the following two commands: - Warning To translate output messages in different languages, your system locale information —as in LANG environment variable— must be set to that locale you want to produce translated messages for. For example, if you want to produce translated messages for Spanish language, your system locale information must be set to es_ES.UTF-8, or similar, first. + Warning To translate output messages in different languages, your system locale information —as in LANG environment variable— must be set to that locale you want to produce translated messages for. For example, if you want to produce translated messages for Spanish language, your system locale information must be set to es_ES.UTF-8, or similar, before executing the locale functionality of centos-art.sh script. Well, it seems that our example is rather complete by now. - In greet function example we've described so far, we only use cli_printMessage global function in action specific function definitions in order to print messages, but more interesting things can be achieved inside action specific function definitions. For example, if you pass a directory path as action value in second argument, you could retrive a list of files from therein, and process them. If the list of files turns too long or you just want to control which files to process, you could add the third argument in the form and reduce the amount of files to process using a regular expression pattern. - The greet function described in this section may serve you as an introduction to understand how specific functionalities work inside centos-art.sh script. With some of luck this introduction will also serve you as motivation to create your own centos-art.sh script specific functionalities. + Extending the greet functionality + In the greet functionality we've described so far, we only use cli_printMessage function in action specific function definitions in order to print messages, but more interesting things can be achieved inside action specific function definitions. For example, if you pass a directory path as argument, you could use it to retrive a list of files from therein and process them. If the list of files turns too long or you just want to control which files to process, so you could add another argument in the form and reduce the list of files to process using a regular expression pattern. + In case you consider to extend the greet functionality to do something different but print out grettings, consider changing the function name from greet to something more appropriate, as well. The name change must be coherent with the actions the new function is designed to perform. + If you doubt what name is better for your functionality, write to centos-devel@centos.org mailing list, explain what your functionality intends to do and request suggestion about what name would be more appropriate for it. That would be also very convenient for you, in order to evaluate the purposes of your function and what the community thinks about it. It is a way for you to gather ideas that help you to write using the community feeling as base. + If your function passes the community evaluation, that is a good sign for you to start/keep writing it. However, if it doesn't, it is time for you to rethink what you are doing and ask again until it passes the community evaluation. You can considered you've passed the community evaluation when after proposing your idea, you get a considerable amount of possitve responses for what you are doing, specially if those responses come from community leaders. + It is very hard to do something useful for a community of people without any point of contact with that community you are trying to do things for. How could you know you are doing something that is needed if you don't know what the needs are? So, explore the community needs first, define them, work them out and repeat the process time after time, even when you might think the need has been already satisfied. At that point, surely, you'll find smaller needs that need to be satisfied, as well. + Conclusions + The greet functionality described in this section may serve as introduction for you to understand how specific functionalities are created inside centos-art.sh script. With some of luck this introduction will also serve you as motivation to create your own specific functionalities for centos-art.sh script. By the way, the greet functionality doesn't exist inside centos-art.sh script yet. Would you like to create it? Usage - Global variables - The following global variables of centos-art.sh script, are available for you to use inside specific functions: - - TEXTDOMAIN - Variable - TEXTDOMAIN - - - Default domain used to retrieve translated messages. This value is set in initFunctions.sh and shouldn't be changed. - - - - TEXTDOMAINDIR - Variable - TEXTDOMAINDIR - - - Default directory used to retrieve translated messages. This value is set in initFunctions.sh and shouldn't be changed. - - - - FUNCNAM - Variable - FUNCNAM - - - Define function name. - Function names associate sets of actions. There is one set of actions for each unique function name inside centos-art.sh script. - Dunction names are passed as first argument in centos-art.sh command-line interface. For example, in the command centos-art render --entry=path/to/dir --filter=regex, the ACTION passed to centos-art.sh script is . - When first argument is not provided, the centos-art.sh script immediatly ends its execution. - - - - FUNCDIR - Variable - FUNCDIR - - - - FUNCDIRNAME - Variable - FUNCDIRNAME - - - - FUNCSCRIPT - Variable - FUNCSCRIPT - - - - FUNCCONFIG - Variable - FUNCCONFIG - - - - ACTIONNAM - Variable - ACTIONNAM - - - Define action name. - Each action name identifies an specific action to perform, inside an specific function. - Action name names aare passed as second argument in centos-art.sh command-line interface. For example, in the command centos-art render --entry=path/to/dir --filter=regex, the ACTIONNAM passed to centos-art.sh script is . - When second argument is not provided, the centos-art.sh script immediatly ends its execution. - - - - ACTIONVAL - Variable - ACTIONVAL - - - Define action value. - Action values are associated to just one action name. Action values contain the working copy entry over which its associated action will be performed in. Working copy entries can be files or directories inside the working copy. - - - - REGEX - Variable - REGEX - - - Define regular expression used as pattern to build the list of files to process. - By default, REGEX variable is set to .+ to match all files. - Functions that need to build a list of files to process use the option to redefine REGEX variable default value, and so, control the amount of files to process. - - - - ARGUMENTS - Variable - ARGUMENTS - - - Define optional arguments. - Optional arguments, inside centos-art.sh script, are considered as all command-line arguments passed to centos-art.sh script, from third argument position on. For example, in the command centos-art render --entry=path/to/dir --filter=regex , the optional arguments are from --filter=regex argument on. - Optional arguments are parsed using getopt command through the following base construction: - - Optional arguments provide support to command options inside centos-art.sh script. For instance, consider the Subversion (svn) command, where there are many options (e.g., , , , etc), and inside each option there are several modifiers (e.g., --revision, --message, --username, etc.) that can be combined one another in their short or long variants. - The ARGUMENTS variable is used to store arguments passed from command-line for later use inside centos-art.sh script. Storing arguments is specially useful when we want to run a command with some specific options from them. Consider the following command: - - In the above command, the , and options are specific to svn copy command. In such cases, options are not interpreted by centos-art.sh script itself. Instead, the centos-art.sh script uses getopt to retrive them and store them in the ARGUMENTS variable for later use, as described in the following command: - - When getopt parses ARGUMENTS, we may use short options (e.g., ) or long options (e.g., ). When we use short options, arguments are separated by one space from the option (e.g., ). When we use long options arguments are separated by an equal sign (=) (e.g., ). - In order for getopt to parse ARGUMENTS correctly, it is required to provide the short and long definition of options that will be passed or at least supported by the command performing the final action the function script exists for. - As convenction, inside centos-art.sh script, short option definitions are set in the ARGSS variable; and long option definitions are set in the ARGSL variable. - When you define short and long options, it may be needed to define which of these option arguments are required and which not. To define an option argument as required, you need to set one colon : after the option definition (e.g., ). On the other hand, to define an option argument as not required, you need to set two colons :: after the option definition (e.g., ). - - - - EDITOR - Variable - EDITOR - - - Default text editor. - The centos-art.sh script uses default text EDITOR to edit pre-commit subversion messages, translation files, configuration files, script files, and similar text-based files. - If EDITOR environment variable is not set, centos-art.sh script uses /usr/bin/vim as default text editor. Otherwise, the following values are recognized by centos-art.sh script: - - • - - /usr/bin/vim - - - /usr/bin/emacs - - - /usr/bin/nano - - - If no one of these values is set in EDITOR environment variable, centos-art.sh uses /usr/bin/vim text editor by default. - - - Global functions - Function scripts stored directly under trunk/Scripts/Bash/Functions/ directory are used to define global functions. Global functions can be used inside action specific functionalities and or even be reused inside themselves. This section provides introductory information to global functions you can use inside centos-art.sh script. - - cli_checkActionArguments - Function - cli_checkActionArguments - - - Validate action value (ACTIONVAL) variable. - The action value variable can take one of the following values: - - - Path to one directory inside the local working copy, - - - Path to one file inside the local working copy, - - - If another value different from that specified above is passed to action value variable, the centos-art.sh script prints an error message and ends script execution. - - - - cli_checkFiles - Function - cli_checkFiles - FILE - [ - TYPE - ] - - - Verify file existence. - cli_checkFiles receives a FILE absolute path and performs file verification as specified in TYPE. When TYPE is not specified, cli_checkFiles verifies FILE existence, no matter what kind of file it be. If TYPE is specified, use one of the following values: - - - - - - Ends script execution if FILE is not a directory. - When you verify directories with cli_checkFiles, if directory doesn't exist, centos-art.sh script asks you for confirmation in order to create that directory. If you answer positively, centos-art.sh script creates that directory and continues script flows normally. Otherwise, if you answer negatively, centos-art.sh ends script execution with an error and documentation message. - - - - - - - Ends script execution if FILE is not a regular file. - - - - - - - Ends script execution if FILE is not a symbolic link. - - - - - - - Ends script execution if FILE is not executable. - - - - - - Ends script execution if FILE is neither a regular file nor a symbolic link. - - - - - - Ends script execution if FILE is neither a regular file nor a directory. - - - - - - Ends script execution if FILE is not inside the working copy. - - -
- As default behaviour, if FILE passes all verifications, centos-art.sh script continues with its normal flow. - - - - cli_commitRepoChanges - Function - cli_commitRepoChanges - [ - LOCATION - ] - - - Syncronize changes between repository and working copy. - The cli_commitRepoChanges function brings changes from the central repository down to the working copy—using svn update—, checks the working copy changes—using svn status command—, prints status report—using both svn update and svn status commands output, and finally, commits recent changes from the working copy up to the repository—using svn commit command—. - Previous to commit the working copy changes up to the central repository, the cli_commitRepoChanges function asks you to verify changes—using svn diff command—, and later, another confirmation question is shown to be sure you really want to commit changes up to central repository. - If LOCATION argument is not specified, the value of ACTIONVAL variable is used as reference instead. - - Figure - - Bringing changes from the repository into the working copy ---> Checking changes in the working copy ----------------------------------------------------------------------- -Added 0 file from the repository. -Deleted 0 file from the repository. -Updated 0 file from the repository. -Conflicted 0 file from the repository. -Merged 0 file from the repository. -Modified 4 files from the working copy. -Unversioned 0 file from the working copy. -Deleted 0 file from the working copy. -Added 0 file from the working copy. ----------------------------------------------------------------------- -]]> - The cli_commitRepoChanges function output. - - Call the cli_commitRepoChanges function before or/and after calling functions that modify files or directories inside the working copy as you may need to. - - - - cli_doParseArguments - Function - cli_doParseArguments - - - Redefine arguments (ARGUMENTS) global variable using getopt command output. For more information about how to use cli_doParseArguments function, see ARGUMENTS variable description above. - - - - cli_doParseArgumentsReDef - Function - cli_doParseArgumentsReDef - $ - @ - - - Initialize/reset arguments (ARGUMENTS) global variable using positional parameters variable ($@) as reference. - When we work inside function definitions, positional parameters are reset to the last function definition positional parameters. If you need to redefine positional parameters from one specific function, you need to call cli_doParseArgumentsReDef with the positional parameters variable ($@), set as first argument, to that specific function you want to redefine positional parameters at. - - - - cli_getArguments - Function - cli_getArguments - - - Initialize function name (FUNCNAM), action name (ACTIONNAM), and action value (ACTIONVAL) global variables, using positional parameters passed in $@ variable. - The cli_getArguments function is called from cli.sh function script, using cli function positional parameters (i.e., the positional parameters passed as arguments in the command-line) as first function argument. - Once command-line positional parameters are accesible to centos-art.sh script execution evironment, cli_getArguments uses regular expression to retrive action variables from first and second argument. The first argument defines the value used as function name (FUNCNAM), and the second argument defines both values used as action name (ACTIONNAM) and action value (ACTIONVAL), respectively. - The first argument is a word in lower case. This word specifies the name of the functionality you want to use (e.g., render to render images, manual to work on documentation, and so on.) - The second argument has a long option style (e.g., --option=value). The --option represents the action name (ACTIONNAM), and the characters inbetween the equal sign (=) and the first space character, are considered as the action value (ACTIONVAL). In order to provide action values with space characters inbetween you need to enclose action value with quotes like in --option='This is long value with spaces inbetween'. Generally, action values are used to specify paths over which the action name acts on. - Once action related variables (i.e., FUNCNAM, ACTIONNAM, and ACTIONVAL) are defined and validated, cli_getArguments shifts the positional arguments to remove the first two arguments passed (i.e., those used to retrive action related variables) and redefine the arguments (ARGUMENTS) global variable with the new positional parameters information. - - - - cli_getFunctions - Function - cli_getFunctions - - - Initialize funtionalities supported by centos-art.sh script. - Functionalities supported by centos-art.sh script are organized in functionality directories under trunk/Scripts/Bash/Functions/ directory. Each functionality directory stores function scripts to the functionality such directory was created for. Function scripts contain function definitions. Function definitions contain several commands focused on achieving one specific task only (i.e., the one such functionality was created for). - In order for centos-art.sh script to recognize a functionality, such functionality needs to be stored under trunk/Scripts/Bash/Functions/ in a directory written capitalized (i.e., the whole name is written in lowercase except the first character which is in uppercase). The directory where one specific functionality is stored is known as the functionality directory. - Inside each functionality directory, the functionalty itself is implemented through function scripts. Function scripts are organized in files independently one another and written in camelCase format with the function name as prefix. Separation between prefix and description is done using underscore (_) character. - In order for centos-art.sh script to load functionalities correctly, function definition inside function scripts should be set using the function reserved word, just as in the following example: - - The above function definition is just a convenction we use, in order to make identification of function names easier read and automate by centos-art.sh script initialization commands, once centos-art.sh script determines which functionality directory to use. Specifically, in order to initialize and export functions, centos-art.sh script executes all function scripts inside the functionality directory, and later grep on them using a regular expression pattern, where the function reserved word is used as reference to retrive the function names and export them to centos-art.sh script execution environment, and so, make function definitions —from function scripts inside the functionality directory— available for further calls. - If the functionality specified in the command-line first argument doesn't have a functionality directory, centos-art.sh script considers the functionality provided in the command-line as invalid functionality and immediatly stops script execution with an error message. - In order to keep visual consistency among function scripts, please consider using the following function script design model as template for your own function scripts: - - - - - cli_getCountryCodes - Function - cli_getCountryCodes - [ - FILTER - ] - - - Output country codes supported by centos-art.sh script. - The cli_getCountryCodes function outputs a list with country codes as defined in ISO3166 standard. When FILTER is provided, cli_getCountryCodes outputs country codes that match FILTER regular expression pattern. - - - - cli_getCountryName - Function - cli_getCountryName - [ - FILTER - ] - - - Outputs country name supported by centos-art.sh script. - The cli_getCountryName function reads one language locale code in the format LL_CC and outputs the name of its related country as in ISO3166. If filter is specified, cli_getCountryName returns the country name that matches the locale code specified in FILTER, exactly. - - - - cli_getCurrentLocale - Function - cli_getCurrentLocale - - - Output current locale used by centos-art.sh script. - The cli_getCurrentLocale function uses LANG environment variable to build a locale pattern that is later applied to cli_getLocales function output in order to return the current locale that centos-art.sh script works with. - The current locale information, returned by cli_getCurrentLocale, is output from more specific to less specific. For example, if en_GB locale exists in cli_getLocales function output, the en_GB locale would take precedence before en locale. - Locale precedence selection is quite important in order to define the locale type we use for message translations. For example, if en_GB is used, we are also saying that the common language specification for English language (i.e., en) is no longer used. Instead, we are using English non-common country-specific language specifications like en_AU, en_BW, en_GB, en_US, etc., for message translations. - Use cli_getCurrentLocale function to know what current locale information to use inside centos-art.sh script. - - - - cli_getFilesList - Function - cli_getFilesList - [ - LOCATION - ] - - - Output list of files to process. - The cli_getFilesList function uses LOCATION variable as source location to build a list of files just as specified by regular expression (REGEX) global variable. Essentially, what the cli_getFilesList function does is using find command to look for files in the location (LOCATION) just as posix-egrep regular expression (REGEX) specifies. - If LOCATION is not specified when cli_getFilesList function is called, the action value (ACTIONVAL) global variable is used as location value instead. - By default, if the regular expression (REGEX) global variable is not redefined after its first definition in the cli function, all files that match default regular expression value (i.e., .+) will be added to the list of files to process. Otherwise, if you redefine the regular expression global variable after its first definition in the cli function and before calling cli_getFilesList function, the last value you specifed is used instead. - When you need to customize the regular expression (REGEX) global variable value inside a function, do not redefine the global variable (at least you be absolutly convinced you need to). Instead, set the regular expression global variable as local to the function you need a customized regular expression value for. If we don't redefine the regular expression global variable as local to the function, or use another name for the regular expression variable (which is not very convenient in order to keep the amount of names to remember low), you may experiment undesired concantenation issues that make your regular expression to be something different from that you expect them to be, specially if the function where you are doing the variable redefinition is called several times during the same script execution. - As result, the cli_getFilesList re-defines the value of FILES variable with the list of files the find command returned. As example, consider the following construction: - - - - - cli_getLangCodes - Function - cli_getLangCodes - [ - FILTER - ] - - - Outputs language codes supported by centos-art.sh script. - cli_getLangCodes function outputs a list of language codes as defined in ISO639 standard. When FILTER is provided, cli_getLangCodes outputs language codes that match FILTER regular expression pattern. - - - - cli_getLangName - Function - cli_getLangName - [ - FILTER - ] - - - Outputs language names supported by centos-art.sh script. - cli_getLangName function reads one language locale code in the format LL_CC and outputs the language related name as in ISO639. If filter is specified, cli_getLangName returns the language name that matches the locale code specified in FILTER, exactly. - - - - cli_getLocales - Function - cli_getLocales - - - Output locale codes supported by centos-art.sh script. - Occasionally, you use cli_getLocales function to add locale information in non-common country-specific language (LL_CC) format for those languages (e.g., bn_IN, pt_BR, etc.) which locale differences cannot be solved using common language specifications (LL) into one unique common locale specification (e.g., bn, pt, etc.). - - - - cli_getRepoName - Function - cli_getRepoName - NAME - TYPE - - - Sanitate file names. - Inside centos-art.sh script, specific functionalities rely both in cli_getRepoName and repository file system organization to achieve their goals. Consider cli_getRepoName function as central place to manage file name convenctions for other functions inside centos-art.sh script. - - Important cli_getRepoName function doesn't verify file or directory existence, for that purpose use cli_checkFiles function instead. - - The NAME variable contains the file name or directory name you want to sanitate. - The TYPE variable specifies what type of sanitation you want to perform on NAME. The TYPE can be one of the following values: - - - - - - Sanitate directory NAMEs. - - - - - - - Sanitate regular file NAMEs. - - -
- Use cli_getRepoName function to sanitate file names and directory names before their utilization. - Use cli_getRepoName when you need to change file name convenctions inside centos-art.sh script. - When we change file name convenctions inside cli_getRepoName what we are really changing is the way functions interpret repository file system organization. Notice that when we change a file name (e.g., a function name), it is necessary to update all files where such file name is placed on. This may require a massive substitution inside the repository, each time we change name convenctions in the repository (— Removed(pxref:trunk Scripts Bash Functions Path) —, for more information). - - - - cli_getRepoStatus - Function - cli_getRepoStatus - [ - LOCATION - ] - - - Request repository status. - This function requests the status of a LOCATION inside the working copy using the svn status command and returns the first character in the output line, just as described in svn help status. If LOCATION is not a regular file or a directory, inside the working copy, the centos-art.sh script prints a message and ends its execution. - Use this function to perform verifications based a repository LOCATION status. - - - - cli_getTemporalFile - Function - cli_getTemporalFile - NAME - - - Output absolute path to temporal file NAME. - The cli_getTemporalFile function uses /tmp directory as source location to store temporal files, the centos-art.sh script name, and a random identification string to let you run more than one centos-art.sh script simultaneously on the same user session. For example, due the following temporal file defintion: - - If FILE name is instance.svg and the unique random string is f16f7b51-ac12-4b7f-9e66-72df847f12de, the final temporal file, built from previous temporal file definition, would be: - - When you use the cli_getTemporalFile function to create temporal files, be sure to remove temporal files created once you've ended up with them. For example, consider the following construction: - - Use the cli_getTemporalFile function whenever you need to create temporal files inside centos-art.sh script. - - - - cli_getThemeName - Function - cli_getThemeName - - - Output theme name. - In order for cli_getThemeName function to extract theme name correctly, the ACTIONVAL variable must contain a directory path under trunk/Identity/Themes/Motifs/ directory structure. Otherwise, cli_getThemeName returns an empty string. - - - - cli_printMessage - Function - cli_printMessage - MESSAGE - [ - FORMAT - ] - - - Define standard output message definition supported by centos-art.sh script. - When FORMAT is not specified, cli_printMessage outputs information just as it was passed in MESSAGE variable. Otherwise, FORMAT can take one of the following values: - - - - - To print heading messages. - - - - - - - To print warning messages. - - - - - - - To print note messages. - - - - - - - To print Updating messages on two-columns format. - - - - - - - To print Removing messages on two-columns format. - - - - - - - To print Checking messages on two-columns format. - - - - - - - To print Creating messages on two-columns format. - - - - - - - To print Saved as messages on two-columns format. - - - - - - - To print Linked to messages on two-columns format. - - - - - - - To print Moved to messages on two-columns format. - - - - - - - To print Translation messages on two-columns format. - - - - - - - To print Configuration messages on two-columns format. - - - - - - - To print response messages on one-column format. - $MESSAGE -]]> - - - - - - To print request messages on one-column format. Request messages output messages with one colon (:) and without trailing newline (\n) at message end. - - - - - - - To print yes or no request messages on one-column format. If something different from y is answered (when using en_US.UTF-8 locale), script execution ends immediatly. - - When we use centos-art.sh script in a locale different from en_US.UTF-8, confirmation answer may be different from y. For example, if you use es_ES.UTF-8 locale, the confirmation question would look like: - - and the confirmation answer would be s, as it is on Spanish sí word. - Definition of which confirmation word to use is set on translation messages for your specific locale information. — Removed(xref:trunk Scripts Bash Functions Locale) —, for more information about locale-specific translation messages. - - - - - - To standardize to know more, run the following command: messages. When the option is used, the MESSAGE value should be set to "$(caller)". caller is a Bash builtin that returns the context of the current subroutine call. option uses caller builtin output to build documentation entries dynamically. - - Use option after errors and for intentional script termination. - - - - - - To standardize regular messages on one-column format. - When MESSAGE contains a colon inside (e.g., description: message), the cli_printMessage function outputs MESSAGE on two-columns format. - - -
- Use cli_printMessage function whenever you need to output information from centos-art.sh script. - - Tip To improve two-columns format, change the following file: - - - - - Specific functions The following specific functions of centos-art.sh script, are available for you to use: - - - - Directories trunk Scripts Functions Locale - Directories trunk Scripts Functions Locale - - - - - Directories trunk Scripts Functions Path - Directories trunk Scripts Functions Path - - - - Directories trunk Scripts Functions Render - Directories trunk Scripts Functions Render - - - - Directories trunk Scripts Functions Render Config - Directories trunk Scripts Functions Render Config - - - - - - Directories trunk Scripts Functions Prepare - Directories trunk Scripts Functions Prepare - - - + + • + + See Directories trunk Scripts Functions Prepare. + + + See Directories trunk Scripts Functions Render. + + + See Directories trunk Scripts Functions Locale. + + + See Directories trunk Scripts Functions Help. + + + See Directories trunk Scripts Functions Path. + + + See Directories trunk Scripts Functions Tuneup. + + See also - - - Directories trunk Scripts - Directories trunk Scripts - - - - + + • + + Directories trunk Scripts + + + Directories trunk + + @@ -3743,7 +2980,7 @@ centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/ /usr/bin/nano - + If no one of these values is set in EDITOR environment variable, centos-art.sh uses /usr/bin/vim text editor by default. @@ -3849,9 +3086,9 @@ GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1989, 1991 Free Software Foundation, Inc. -59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + 675 Mass Ave, Cambridge, MA 02139, USA ]]> - Do not change the license information under which centos-art.sh script is released. Instead, if you think a different license must be used, please share your reasons at centos-devel@centos-art.shCentOS Developers mailing list. + Do not change the license information under which centos-art.sh script is released. Instead, if you think a different license must be used, please share your reasons at centos-devel@centos-art.sh mailing list. See file file:///home/centos/artwork/trunk/Scripts/COPYINGtrunk/Scripts/COPYING, for a complete license description. SVG Files @@ -4263,6 +3500,7 @@ function render_loadConfig { Directories trunk Scripts Functions Render Config + Directories trunk Scripts Functions Tuneup Directories trunk Scripts Functions Render Directories
@@ -4379,6 +3617,43 @@ ACTIONS[2]='LAST:groupByformat: png xpm jpg tif' +
+ + + Directories trunk Scripts Functions Tuneup + Directories trunk Scripts Functions Render Config + Directories +
+ The <file>trunk/Scripts/Functions/Tuneup</file> Directory + Directories trunk Scripts Functions Tuneup + Goals + + • + + ... + + + Description + + • + + ... + + + Usage + + • + + ... + + + See also + + • + + ... + +