diff --git a/Manuals/en/Html/Repository/repository_39.html b/Manuals/en/Html/Repository/repository_39.html index b2c05d0..f790fe7 100644 --- a/Manuals/en/Html/Repository/repository_39.html +++ b/Manuals/en/Html/Repository/repository_39.html @@ -92,11 +92,14 @@ working copy of CentOS Artwork Repository.

3.36.2 Description

The best way to understand `centos-art.sh' automation script is -studying its source code. The `centos-art.sh' script is splited -in several configuration and function files which are loaded when the -`centos-art.sh' script is executed. This section describes the -order in which `centos-art.sh' loads its configuration and -function files. +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 @@ -110,7 +113,7 @@ 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/initFunctions.sh' script to +executing the `trunk/Scripts/Bash/initEnvironment.sh' script to initialize global variables (e.g., gettext's variables) and global function scripts. Global function scripts are located inside `trunk/Scripts/Bash/Functions' directory and their file names @@ -130,55 +133,91 @@ the following format: 

centos-art arg1 --arg2=val2 --arg3=val3

In the above example, `centos-art' is the command you use to -invoke `centos-art.sh' script. The `arg1' represents the -action you want to do (e.g., `verify', `render', -`locale', `help', etc.). The remaining arguments are -modifiers to `arg1'. The `--arg2' definition is -required. The `--arg3' is optional. For example, if you want -to render all anaconda progress slides, for all major releases of -CentOS distribution, for all languages availabe using TreeFlower motif -as background, you use the following command: -

-
centos-art render --entry=trunk/Identity/Themes/Motifs/TreeFlower/Distro/Anaconda/Progress
-
-

Now, if you only want to render anaconda progress -`01-welcome.png' slide, for CentOS distribution major release 5, -in English language, you need to add the third argument as follows: +invoke `centos-art.sh' script. The `arg1' is required and +represents the functionality you want to perform (e.g., +`verify', `render', `locale', `manual', +etc.). The remaining arguments are modifiers to `arg1'. The +`--arg2' definition is required and represets, specifically, +the action inside the functionality you want to perform. The +`--arg3' and on, are optional.

-
centos-art render --entry=trunk/Identity/Themes/Motifs/TreeFlower/Distro/Anaconda/Progress --filter=5/en/01-welcome
-

Once command-line arguments have been retrived, the -`centos-art.sh' script loads specific functions using the -`cli_getActions.sh' function script. For example, if you run the -command centos-art render --entry, the `centos-art.sh' -script will look for `trunk/Scripts/Bash/Functions/Render' -directory and will load the render function from -`render.sh' function script; this, in order to achive the -rendering task as it defines. +`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.

-
+------------------------------------------------------------------+
-| [centos@host]$ centos-art action 'path/to/dir' --option='value'  |
-+------------------------------------------------------------------+
-| ~/bin/centos-art --> ~/artwork/trunk/Scripts/Bash/centos-art.sh  |
-+---v-----------------------------------------v--------------------+
+
+----------------------------------------------------------------------+
+| [centos@host]$ centos-art function --action='value' --option='value' |
++----------------------------------------------------------------------+
+| ~/bin/centos-art --> ~/artwork/trunk/Scripts/Bash/centos-art.sh      |
++---v-----------------------------------------v------------------------+
     | centos-art.sh                           |
     +---v---------------------------------v---+
-    .   | initFunctions.sh                |   .
+    .   | initEnvironment.sh              |   .
     .   +---------------------------------+   .
     .   | cli $@                          |   .
     .   +---v-------------------------v---+   .
-    .   .   | cli_getActions $@       |   .   .
+    .   .   | cli_getFunctions        |   .   .
     .   .   +---v-----------------v---+   .   .
-    .   .   .   | function call 1 |   .   .   .
-    .   .   .   | function call 2 |   .   .   .
-    .   .   .   | function call n |   .   .   .
+    .   .   .   | function1       |   .   .   .
+    .   .   .   | function2       |   .   .   .
+    .   .   .   | function3       |   .   .   .
     .   .   .   +-----------------+   .   .   .
     .   .   ...........................   .   .
     .   ...................................   .
     ...........................................
 

-

Figure 3.8: The `centos-art.sh' initialization environment. +

Figure 3.8: The 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. +

+
+
+--------------------------------------+
+| cli_getFunctions                     |
++---v------------------------------v---+
+.   | function1                    |   .
+.   +---v----------------------v---+   .
+.   .   | function1_getActions |   .   .
+.   .   +---v--------------v---+   .   .
+.   .   .   | action 1     |   .   .   .
+.   .   .   | action 2     |   .   .   .
+.   .   .   | action n     |   .   .   .
+.   .   .   +--------------+   .   .   .
+.   .   ........................   .   .
+.   ................................   .
+.   +------------------------------+   .
+.   | function2                    |   .
+.   +---v----------------------v---+   .
+.   .   | function_getActions  |   .   .
+.   .   +---v--------------v---+   .   .
+.   .   .   | action 1     |   .   .   .
+.   .   .   | action 2     |   .   .   .
+.   .   .   | action n     |   .   .   .
+.   .   .   +--------------+   .   .   .
+.   .   ........................   .   .
+.   ................................   .
+.   +------------------------------+   .
+.   | function3                    |   .
+.   +---v----------------------v---+   .
+.   .   | function3_getActions |   .   .
+.   .   +---v--------------v---+   .   .
+.   .   .   | action 1     |   .   .   .
+.   .   .   | action 2     |   .   .   .
+.   .   .   | action n     |   .   .   .
+.   .   .   +--------------+   .   .   .
+.   .   ........................   .   .
+.   ................................   .
+........................................
+
+

Figure 3.9: The actions initialization environment.

diff --git a/Manuals/en/Html/Repository/repository_40.html b/Manuals/en/Html/Repository/repository_40.html index 7830e2c..06c92a7 100644 --- a/Manuals/en/Html/Repository/repository_40.html +++ b/Manuals/en/Html/Repository/repository_40.html @@ -206,9 +206,9 @@ environment. This time we didn't use global variable definitions for empty.

Later, we call greet_getActions function to define the -command-line interface of greet functionality. The greet -functionality command-line interface defines what and how actions are -performed, based on arguments combination passed to +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. 

function greet_getActions {
@@ -248,7 +248,8 @@ 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.  
+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
@@ -309,13 +310,22 @@ Goodbye World
 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,
+time to document it.  To document greet specific functionality,
 we use its directory path and the manual functionality
 (see section trunk/Scripts/Bash/Functions/Manual) of `centos-art.sh'
 script, just as the following command illustrates: 
 

 
centos-art manual --edit=trunk/Scripts/Bash/Functions/Greet
 

+
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 let the user know which
+valid functions are. When no documentation entry exists for a
+funtcion, that user has provided an invalid action for, 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
@@ -329,17 +339,17 @@ 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.  
+`es_ES.UTF-8', or similar, first.
 

 
 
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 a message simply, but more interesting
-things can be achieved inside action specific function definitions.
-For example, if you pass a directory path as second argument option
-value, you could retrive a list of files from therein, and process
+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
 `--filter='regex'' and reduce the amount of files to process
@@ -715,7 +725,7 @@ Deleted         0 file from the working copy.
 Added           0 file from the working copy.
 ----------------------------------------------------------------------
-

Figure 3.9: The cli_commitRepoChanges function output. +

Figure 3.10: The cli_commitRepoChanges function output.

Call the cli_commitRepoChanges function before or/and after diff --git a/Manuals/en/Html/Repository/repository_44.html b/Manuals/en/Html/Repository/repository_44.html index 3aa8134..66c3c5b 100644 --- a/Manuals/en/Html/Repository/repository_44.html +++ b/Manuals/en/Html/Repository/repository_44.html @@ -115,7 +115,7 @@ three top level directories named `trunk/', `branches/', and

trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-6 -

Figure 3.10: The CentOS Artwork Repository layout. +

Figure 3.11: The CentOS Artwork Repository layout.

The `trunk/' directory (see section trunk) organizes the main @@ -209,7 +209,7 @@ the same branch development line.

trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-1 -

Figure 3.11: Name convention for tags and branches creation. +

Figure 3.12: Name convention for tags and branches creation.

As proposition, it would be convenient not to freeze trunk development @@ -283,7 +283,7 @@ repository.

trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-3 -

Figure 3.12: Parallel directories removing uncommon information. +

Figure 3.13: Parallel directories removing uncommon information.

Othertimes, parallel directories may add uncommon information to their @@ -296,7 +296,7 @@ be carefully considered where it will be.

trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-4 -

Figure 3.13: Parallel directories adding uncommon information. +

Figure 3.14: Parallel directories adding uncommon information.

When one parent directory changes, all their related parallel @@ -310,7 +310,7 @@ initially created for.

trunk/Identity/Models/Img/Scripts/Bash/Functions/Path/figure-5 -

Figure 3.14: Wrong construction of parallel directories. +

Figure 3.15: Wrong construction of parallel directories.

diff --git a/Manuals/en/Html/Repository/repository_53.html b/Manuals/en/Html/Repository/repository_53.html index 11b6d33..b213bfe 100644 --- a/Manuals/en/Html/Repository/repository_53.html +++ b/Manuals/en/Html/Repository/repository_53.html @@ -228,7 +228,7 @@ files should match markers in model designs exactly.

Translation Markers -

Figure 3.15: The image rendering flow. +

Figure 3.16: The image rendering flow.

Translation markers can be whatever text you want, but as convenction diff --git a/Manuals/en/Html/Repository/repository_65.html b/Manuals/en/Html/Repository/repository_65.html index 6d4f840..d423c8c 100644 --- a/Manuals/en/Html/Repository/repository_65.html +++ b/Manuals/en/Html/Repository/repository_65.html @@ -92,21 +92,23 @@ ul.toc {list-style: none}

Figure 3.7

The CentOS web navigation design model.

-
Figure 3.8

The `centos-art.sh' initialization environment. +

Figure 3.8

The functionalities initialization environment.

-
Figure 3.9

The cli_commitRepoChanges function output. +

Figure 3.9

The actions initialization environment.

-
Figure 3.10

The CentOS Artwork Repository layout. +

Figure 3.10

The cli_commitRepoChanges function output.

-
Figure 3.11

Name convention for tags and branches creation. +

Figure 3.11

The CentOS Artwork Repository layout.

-
Figure 3.12

Parallel directories removing uncommon information. +

Figure 3.12

Name convention for tags and branches creation.

-
Figure 3.13

Parallel directories adding uncommon information. +

Figure 3.13

Parallel directories removing uncommon information.

-
Figure 3.14

Wrong construction of parallel directories. +

Figure 3.14

Parallel directories adding uncommon information.

-
Figure 3.15

The image rendering flow. +

Figure 3.15

Wrong construction of parallel directories. +

+
Figure 3.16

The image rendering flow.

diff --git a/Manuals/en/Info/Repository/repository.info.bz2 b/Manuals/en/Info/Repository/repository.info.bz2 index 7188353..599fa0c 100644 Binary files a/Manuals/en/Info/Repository/repository.info.bz2 and b/Manuals/en/Info/Repository/repository.info.bz2 differ diff --git a/Manuals/en/Plaintext/Repository/repository.txt b/Manuals/en/Plaintext/Repository/repository.txt index a31bf95..8a7b578 100644 --- a/Manuals/en/Plaintext/Repository/repository.txt +++ b/Manuals/en/Plaintext/Repository/repository.txt @@ -2666,10 +2666,13 @@ copy of CentOS Artwork Repository. ------------------ The best way to understand `centos-art.sh' automation script is -studying its source code. The `centos-art.sh' script is splited in -several configuration and function files which are loaded when the -`centos-art.sh' script is executed. This section describes the order in -which `centos-art.sh' loads its configuration and function files. +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 @@ -2683,7 +2686,7 @@ 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/initFunctions.sh' script to +executing the `trunk/Scripts/Bash/initEnvironment.sh' script to initialize global variables (e.g., `gettext''s variables) and global function scripts. Global function scripts are located inside `trunk/Scripts/Bash/Functions' directory and their file names begin @@ -2704,55 +2707,89 @@ following format: centos-art arg1 --arg2=val2 --arg3=val3 In the above example, `centos-art' is the command you use to invoke -`centos-art.sh' script. The `arg1' represents the action you want to do -(e.g., `verify', `render', `locale', `help', etc.). The remaining -arguments are modifiers to `arg1'. The `--arg2' definition is required. -The `--arg3' is optional. For example, if you want to render all -anaconda progress slides, for all major releases of CentOS -distribution, for all languages availabe using TreeFlower motif as -background, you use the following command: - - -centos-art render --entry=trunk/Identity/Themes/Motifs/TreeFlower/Distro/Anaconda/Progress - - Now, if you only want to render anaconda progress `01-welcome.png' -slide, for CentOS distribution major release 5, in English language, -you need to add the third argument as follows: +`centos-art.sh' script. The `arg1' is required and represents the +functionality you want to perform (e.g., `verify', `render', `locale', +`manual', etc.). The remaining arguments are modifiers to `arg1'. The +`--arg2' definition is required and represets, specifically, the action +inside the functionality you want to perform. The `--arg3' 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. -centos-art render --entry=trunk/Identity/Themes/Motifs/TreeFlower/Distro/Anaconda/Progress --filter=5/en/01-welcome - Once command-line arguments have been retrived, the `centos-art.sh' -script loads specific functions using the `cli_getActions.sh' function -script. For example, if you run the command `centos-art render ---entry', the `centos-art.sh' script will look for -`trunk/Scripts/Bash/Functions/Render' directory and will load the -`render' function from `render.sh' function script; this, in order to -achive the rendering task as it defines. - - -+------------------------------------------------------------------+ -| [centos@host]$ centos-art action 'path/to/dir' --option='value' | -+------------------------------------------------------------------+ -| ~/bin/centos-art --> ~/artwork/trunk/Scripts/Bash/centos-art.sh | -+---v-----------------------------------------v--------------------+ ++----------------------------------------------------------------------+ +| [centos@host]$ centos-art function --action='value' --option='value' | ++----------------------------------------------------------------------+ +| ~/bin/centos-art --> ~/artwork/trunk/Scripts/Bash/centos-art.sh | ++---v-----------------------------------------v------------------------+ | centos-art.sh | +---v---------------------------------v---+ - . | initFunctions.sh | . + . | initEnvironment.sh | . . +---------------------------------+ . . | cli $@ | . . +---v-------------------------v---+ . - . . | cli_getActions $@ | . . + . . | cli_getFunctions | . . . . +---v-----------------v---+ . . - . . . | function call 1 | . . . - . . . | function call 2 | . . . - . . . | function call n | . . . + . . . | function1 | . . . + . . . | function2 | . . . + . . . | function3 | . . . . . . +-----------------+ . . . . . ........................... . . . ................................... . ........................................... -Figure 3.1: The `centos-art.sh' initialization environment. +Figure 3.1: The 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. + + ++--------------------------------------+ +| cli_getFunctions | ++---v------------------------------v---+ +. | function1 | . +. +---v----------------------v---+ . +. . | function1_getActions | . . +. . +---v--------------v---+ . . +. . . | action 1 | . . . +. . . | action 2 | . . . +. . . | action n | . . . +. . . +--------------+ . . . +. . ........................ . . +. ................................ . +. +------------------------------+ . +. | function2 | . +. +---v----------------------v---+ . +. . | function_getActions | . . +. . +---v--------------v---+ . . +. . . | action 1 | . . . +. . . | action 2 | . . . +. . . | action n | . . . +. . . +--------------+ . . . +. . ........................ . . +. ................................ . +. +------------------------------+ . +. | function3 | . +. +---v----------------------v---+ . +. . | function3_getActions | . . +. . +---v--------------v---+ . . +. . . | action 1 | . . . +. . . | action 2 | . . . +. . . | action n | . . . +. . . +--------------+ . . . +. . ........................ . . +. ................................ . +........................................ + +Figure 3.2: The actions initialization environment. 3.36.3 Usage ------------ @@ -2891,8 +2928,8 @@ 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 `greet' -functionality command-line interface defines what and how actions are +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. @@ -2932,7 +2969,8 @@ 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. +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 @@ -2996,14 +3034,23 @@ Goodbye World 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 (*note trunk Scripts -Bash Functions Manual::) of `centos-art.sh' script, just as the +time to document it. To document `greet' specific functionality, we +use its directory path and the `manual' functionality (*note trunk +Scripts Bash Functions Manual::) of `centos-art.sh' script, just as the following command illustrates: centos-art manual --edit=trunk/Scripts/Bash/Functions/Greet + 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 let the user know which valid +functions are. When no documentation entry exists for a funtcion, that +user has provided an invalid action for, 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 @@ -3018,18 +3065,18 @@ centos-art locale --edit 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. + information must be set to `es_ES.UTF-8', or similar, first. 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 a message simply, but more interesting -things can be achieved inside action specific function definitions. -For example, if you pass a directory path as second argument option -value, 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 +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 `--filter='regex'' and reduce the amount of files to process using a regular expression pattern. @@ -3353,7 +3400,7 @@ global functions you can use inside `centos-art.sh' script. Added 0 file from the working copy. ---------------------------------------------------------------------- - Figure 3.2: The `cli_commitRepoChanges' function output. + Figure 3.3: The `cli_commitRepoChanges' function output. Call the `cli_commitRepoChanges' function before or/and after calling functions that modify files or directories inside the @@ -4044,7 +4091,7 @@ and stop doing what we expect from them to do. and directories, related to CentOS corporate visual identity, under three top level directories named `trunk/', `branches/', and `tags/'. - Figure 3.3: The CentOS Artwork Repository layout. + Figure 3.4: The CentOS Artwork Repository layout. The `trunk/' directory (*note trunk::) organizes the main development line of CentOS corporate visual identity. Inside `trunk/' @@ -4130,7 +4177,7 @@ branch created from the same trunk development line. Tags start at zero (i.e., `0') and increment one unit for each tag created from the same branch development line. - Figure 3.4: Name convention for tags and branches creation. + Figure 3.5: Name convention for tags and branches creation. As proposition, it would be convenient not to freeze trunk development lines using tags or anything else. If you think you need @@ -4197,7 +4244,7 @@ information is when we use the `help' functionality. This time, uncommon directory levels) to build the documentation entry required by Texinfo to store documentation entries inside the repository. - Figure 3.5: Parallel directories removing uncommon information. + Figure 3.6: Parallel directories removing uncommon information. Othertimes, parallel directories may add uncommon information to their paths. This is the case we use to create branches and tags. When @@ -4206,7 +4253,7 @@ directory structure path. The place where the numerical identifier is set on is relevant to corporate visual identity structure and should be carefully considered where it will be. - Figure 3.6: Parallel directories adding uncommon information. + Figure 3.7: Parallel directories adding uncommon information. When one parent directory changes, all their related parallel directories need to be changed too. This is required in order for @@ -4216,7 +4263,7 @@ reason but to satisfy their parent directory structure. Liberal change of parallel directories may suppress the conceptual idea they were initially created for. - Figure 3.7: Wrong construction of parallel directories. + Figure 3.8: Wrong construction of parallel directories. 3.41.2.5 Syncronizing path information ...................................... @@ -6233,24 +6280,24 @@ Index ***** branches: See 1. (line 390) -Common translation files: See 3.50.2.5. (line 5662) -How to render brands' translation files: See 3.52.3. (line 5966) -How to render fonts' translation files: See 3.54.3. (line 6039) -How to render translation files: See 3.50.3. (line 5832) -Metadata maintainance: See 3.45.2. (line 4806) -Specific translation files: See 3.50.2.6. (line 5687) +Common translation files: See 3.50.2.5. (line 5709) +How to render brands' translation files: See 3.52.3. (line 6013) +How to render fonts' translation files: See 3.54.3. (line 6086) +How to render translation files: See 3.50.3. (line 5879) +Metadata maintainance: See 3.45.2. (line 4853) +Specific translation files: See 3.50.2.6. (line 5734) tags: See 2. (line 393) -Template translation files: See 3.50.2.4. (line 5492) -Translation brands file names: See 3.52.2.1. (line 5923) -Translation configuration scripts: See 3.50.2.8. (line 5721) -Translation entries: See 3.50.2.1. (line 5308) -Translation files: See 3.50.2.3. (line 5424) -Translation markers: See 3.50.2.2. (line 5389) -Translation paths: See 3.50.2.1. (line 5308) +Template translation files: See 3.50.2.4. (line 5539) +Translation brands file names: See 3.52.2.1. (line 5970) +Translation configuration scripts: See 3.50.2.8. (line 5768) +Translation entries: See 3.50.2.1. (line 5355) +Translation files: See 3.50.2.3. (line 5471) +Translation markers: See 3.50.2.2. (line 5436) +Translation paths: See 3.50.2.1. (line 5355) Translation pre-rendering configuration scripts:See 3.50.2.8. - (line 5721) -Translation rendering: See 3.50.2.7. (line 5710) -Translation rendering default functionality: See 3.50.2.9. (line 5807) + (line 5768) +Translation rendering: See 3.50.2.7. (line 5757) +Translation rendering default functionality: See 3.50.2.9. (line 5854) trunk: See 3. (line 396) trunk Identity: See 3.1. (line 399) trunk Identity Brands: See 3.2. (line 819) @@ -6294,32 +6341,32 @@ trunk Identity Widgets: See 3.33. (line 2562) trunk Manuals: See 3.34. (line 2579) trunk Scripts: See 3.35. (line 2633) trunk Scripts Bash: See 3.36. (line 2657) -trunk Scripts Bash Functions: See 3.37. (line 2769) -trunk Scripts Bash Functions Html: See 3.38. (line 3897) -trunk Scripts Bash Functions Locale: See 3.39. (line 3918) -trunk Scripts Bash Functions Manual: See 3.40. (line 3998) -trunk Scripts Bash Functions Path: See 3.41. (line 4019) -trunk Scripts Bash Functions Render: See 3.42. (line 4421) -trunk Scripts Bash Functions Render Config: See 3.43. (line 4442) -trunk Scripts Bash Functions Shell: See 3.44. (line 4620) -trunk Scripts Bash Functions Svg: See 3.45. (line 4788) -trunk Scripts Bash Functions Verify: See 3.46. (line 4976) -trunk Scripts Bash Locale: See 3.47. (line 5192) -trunk Scripts Perl: See 3.48. (line 5221) -trunk Scripts Python: See 3.49. (line 5238) -trunk Translations: See 3.50. (line 5259) -trunk Translations Identity: See 3.51. (line 5861) -trunk Translations Identity Brands: See 3.52. (line 5882) -trunk Translations Identity Brands Tpl: See 3.53. (line 5977) -trunk Translations Identity Fonts: See 3.54. (line 5992) -trunk Translations Identity Models: See 3.55. (line 6055) -trunk Translations Identity Release: See 3.56. (line 6070) -trunk Translations Identity Themes: See 3.57. (line 6085) -trunk Translations Identity Themes Backgrounds:See 3.58. (line 6100) +trunk Scripts Bash Functions: See 3.37. (line 2806) +trunk Scripts Bash Functions Html: See 3.38. (line 3944) +trunk Scripts Bash Functions Locale: See 3.39. (line 3965) +trunk Scripts Bash Functions Manual: See 3.40. (line 4045) +trunk Scripts Bash Functions Path: See 3.41. (line 4066) +trunk Scripts Bash Functions Render: See 3.42. (line 4468) +trunk Scripts Bash Functions Render Config: See 3.43. (line 4489) +trunk Scripts Bash Functions Shell: See 3.44. (line 4667) +trunk Scripts Bash Functions Svg: See 3.45. (line 4835) +trunk Scripts Bash Functions Verify: See 3.46. (line 5023) +trunk Scripts Bash Locale: See 3.47. (line 5239) +trunk Scripts Perl: See 3.48. (line 5268) +trunk Scripts Python: See 3.49. (line 5285) +trunk Translations: See 3.50. (line 5306) +trunk Translations Identity: See 3.51. (line 5908) +trunk Translations Identity Brands: See 3.52. (line 5929) +trunk Translations Identity Brands Tpl: See 3.53. (line 6024) +trunk Translations Identity Fonts: See 3.54. (line 6039) +trunk Translations Identity Models: See 3.55. (line 6102) +trunk Translations Identity Release: See 3.56. (line 6117) +trunk Translations Identity Themes: See 3.57. (line 6132) +trunk Translations Identity Themes Backgrounds:See 3.58. (line 6147) trunk Translations Identity Themes Distro Anaconda Progress:See 3.59. - (line 6121) -trunk Translations Identity Widgets: See 3.60. (line 6214) -Unused definitions: See 3.45.2.1. (line 4913) + (line 6168) +trunk Translations Identity Widgets: See 3.60. (line 6261) +Unused definitions: See 3.45.2.1. (line 4960) List of Figures *************** diff --git a/Manuals/en/Texinfo/Repository/trunk/Scripts/Bash.texi b/Manuals/en/Texinfo/Repository/trunk/Scripts/Bash.texi index 2849daa..c39e016 100644 --- a/Manuals/en/Texinfo/Repository/trunk/Scripts/Bash.texi +++ b/Manuals/en/Texinfo/Repository/trunk/Scripts/Bash.texi @@ -8,11 +8,14 @@ working copy of CentOS Artwork Repository. @subsection Description The best way to understand @file{centos-art.sh} automation script is -studying its source code. The @file{centos-art.sh} script is splited -in several configuration and function files which are loaded when the -@file{centos-art.sh} script is executed. This section describes the -order in which @file{centos-art.sh} loads its configuration and -function files. +studying its source code. However, as start point, you may prefer to +read an introductory resume before diving into the source code +details. + +The @file{centos-art.sh} script is written in Bash. Most tasks, inside +@file{centos-art.sh} script, have been organized in many specific +functionalities that you can invoke from the @command{centos-art} +command-line interface. When you type the @command{centos-art} command in your terminal, the operating system trys to execute that command. In order to execute the @@ -27,7 +30,7 @@ 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/initFunctions.sh} script to +executing the @file{trunk/Scripts/Bash/initEnvironment.sh} script to initialize global variables (e.g., @command{gettext}'s variables) and global function scripts. Global function scripts are located inside @file{trunk/Scripts/Bash/Functions} directory and their file names @@ -49,60 +52,93 @@ centos-art arg1 --arg2=val2 --arg3=val3 @end verbatim In the above example, @samp{centos-art} is the command you use to -invoke @file{centos-art.sh} script. The @samp{arg1} represents the -action you want to do (e.g., @option{verify}, @option{render}, -@option{locale}, @option{help}, etc.). The remaining arguments are -modifiers to @option{arg1}. The @option{--arg2} definition is -required. The @option{--arg3} is optional. For example, if you want -to render all anaconda progress slides, for all major releases of -CentOS distribution, for all languages availabe using TreeFlower motif -as background, you use the following command: - -@verbatim -centos-art render --entry=trunk/Identity/Themes/Motifs/TreeFlower/Distro/Anaconda/Progress -@end verbatim - -Now, if you only want to render anaconda progress -@file{01-welcome.png} slide, for CentOS distribution major release 5, -in English language, you need to add the third argument as follows: - -@verbatim -centos-art render --entry=trunk/Identity/Themes/Motifs/TreeFlower/Distro/Anaconda/Progress --filter=5/en/01-welcome -@end verbatim +invoke @file{centos-art.sh} script. The @samp{arg1} is required and +represents the functionality you want to perform (e.g., +@option{verify}, @option{render}, @option{locale}, @option{manual}, +etc.). The remaining arguments are modifiers to @option{arg1}. The +@option{--arg2} definition is required and represets, specifically, +the action inside the functionality you want to perform. The +@option{--arg3} and on, are optional. Once command-line arguments have been retrived, the -@file{centos-art.sh} script loads specific functions using the -@file{cli_getActions.sh} function script. For example, if you run the -command @command{centos-art render --entry}, the @file{centos-art.sh} -script will look for @file{trunk/Scripts/Bash/Functions/Render} -directory and will load the @command{render} function from -@file{render.sh} function script; this, in order to achive the -rendering task as it defines. +@file{centos-art.sh} script loads specific functionalities using the +@file{cli_getFunctions.sh} function script. Only one specific +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 @verbatim -+------------------------------------------------------------------+ -| [centos@host]$ centos-art action 'path/to/dir' --option='value' | -+------------------------------------------------------------------+ -| ~/bin/centos-art --> ~/artwork/trunk/Scripts/Bash/centos-art.sh | -+---v-----------------------------------------v--------------------+ ++----------------------------------------------------------------------+ +| [centos@host]$ centos-art function --action='value' --option='value' | ++----------------------------------------------------------------------+ +| ~/bin/centos-art --> ~/artwork/trunk/Scripts/Bash/centos-art.sh | ++---v-----------------------------------------v------------------------+ | centos-art.sh | +---v---------------------------------v---+ - . | initFunctions.sh | . + . | initEnvironment.sh | . . +---------------------------------+ . . | cli $@ | . . +---v-------------------------v---+ . - . . | cli_getActions $@ | . . + . . | cli_getFunctions | . . . . +---v-----------------v---+ . . - . . . | function call 1 | . . . - . . . | function call 2 | . . . - . . . | function call n | . . . + . . . | function1 | . . . + . . . | function2 | . . . + . . . | function3 | . . . . . . +-----------------+ . . . . . ........................... . . . ................................... . ........................................... @end verbatim -@caption{The @file{centos-art.sh} initialization environment.} +@caption{The functionalities initialization environment.} +@end float + +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. + +@float Figure,fig:trunk/Scripts/Bash/Functions:Initialization +@verbatim ++--------------------------------------+ +| cli_getFunctions | ++---v------------------------------v---+ +. | function1 | . +. +---v----------------------v---+ . +. . | function1_getActions | . . +. . +---v--------------v---+ . . +. . . | action 1 | . . . +. . . | action 2 | . . . +. . . | action n | . . . +. . . +--------------+ . . . +. . ........................ . . +. ................................ . +. +------------------------------+ . +. | function2 | . +. +---v----------------------v---+ . +. . | function_getActions | . . +. . +---v--------------v---+ . . +. . . | action 1 | . . . +. . . | action 2 | . . . +. . . | action n | . . . +. . . +--------------+ . . . +. . ........................ . . +. ................................ . +. +------------------------------+ . +. | function3 | . +. +---v----------------------v---+ . +. . | function3_getActions | . . +. . +---v--------------v---+ . . +. . . | action 1 | . . . +. . . | action 2 | . . . +. . . | action n | . . . +. . . +--------------+ . . . +. . ........................ . . +. ................................ . +........................................ +@end verbatim +@caption{The actions initialization environment.} @end float @subsection Usage diff --git a/Manuals/en/Texinfo/Repository/trunk/Scripts/Bash/Functions.texi b/Manuals/en/Texinfo/Repository/trunk/Scripts/Bash/Functions.texi index 28b4f8a..7680a50 100644 --- a/Manuals/en/Texinfo/Repository/trunk/Scripts/Bash/Functions.texi +++ b/Manuals/en/Texinfo/Repository/trunk/Scripts/Bash/Functions.texi @@ -130,9 +130,9 @@ environment. This time we didn't use global variable definitions for empty. Later, we call @code{greet_getActions} function to define the -command-line interface of @code{greet} functionality. The @code{greet} -functionality command-line interface defines what and how actions are -performed, based on arguments combination passed to +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 @@ -174,7 +174,8 @@ 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. +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 are the core of @code{greet} specific functionality. In such function @@ -243,7 +244,7 @@ The word @samp{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 @code{greet} specific functionality, +time to document it. To document @code{greet} specific functionality, we use its directory path and the @code{manual} functionality (@pxref{trunk Scripts Bash Functions Manual}) of @file{centos-art.sh} script, just as the following command illustrates: @@ -252,6 +253,15 @@ script, just as the following command illustrates: centos-art manual --edit=trunk/Scripts/Bash/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 let the user know which +valid functions are. When no documentation entry exists for a +funtcion, that user has provided an invalid action for, 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 @@ -269,17 +279,17 @@ 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. +@samp{es_ES.UTF-8}, or similar, first. @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 -definitions in order to print a message simply, but more interesting -things can be achieved inside action specific function definitions. -For example, if you pass a directory path as second argument option -value, you could retrive a list of files from therein, and process +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