diff --git a/Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/environment.docbook b/Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/environment.docbook index 45d81db..9592403 100644 --- a/Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/environment.docbook +++ b/Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/environment.docbook @@ -1,65 +1,78 @@ - Execution Environment - - - When you login in your computer you enter into a unique user - environment which you can customize by setting environment - variables in the ~/.bash_profile - file.To know more about environment variables, - see the bash(1) man page. This way different - users can benefit from their own environment variables to - customize the execution of centos-art.sh - script in a safe way. For example, users can use the - variables of their environments to set different locations for - their working copies of &TCAR;.See - - - - When you execute the centos-art.sh script, - you create a new environment inside the user environment which - we call the script environment. This environment inherits all - variables from the user environment and contains the variables - and functionalities defined by the script itself. If your only - interest is using the centos-art.sh script - to accomplish tasks inside the working copy, you don't need to - know the whole environment it uses, but the user environment - only. However, if your interest is improving it somehow, to - know the environment where it is run is a fundamental - knowledge you need to be armed with in order to understand - where to put the code you want to contribute inside the - script. - - - - The script environment + Execution Environments + + + This section describes both variables and functions used by + centos-art.sh script as well as the related + execution environments they take place on. + + + + The execution environment of centos-art.sh + script can be defined as the virtual boundery of memory in + which the script does what it was conceived to do once + executed by a command-line interpreter (e.g., Bash). When you + execute the centos-art.sh script in your + terminal, the interpreter behind it creates a new execution + environment for it which inherits all the variables and + functions set in the shell execution environment and those + exported to it through the + ~/.bash_profile file, as well. + + + + The centos-art.sh script uses the + ~/.bash_profile file to implement + per-user customizations. For example, you can use this file + to set the location of your working copy through the + TCAR_WORKDIR enviroment variable. By default + this variable is set to ${HOME}/artwork, but you can + reset to something different to fit your needs. See . + + + + Once the centos-art.sh script has been + executed, it creates different levels of execution + environments inside the one created by the script itself on + the shell. This different levels can be seen as a tree of + execution environments which inherit one another, as + illustrated in . + These different levels of execution evironments are where the + centos-art.sh script is developed in. + + + + Execution environments - The script environment + Execution environments -------------------------------------------------------- -User environment -----|-------------------|------------------------------ -. |-- TCAR_WORKDIR |-- EDITOR . -. |-- LANG |-- HOME . -. `-- centos-art.sh `-- ... . -. ----|---------------------------------------- . -. centos-art.sh script environment . -. ----|-----------------|---------------------- . -. . |-- CLI_NAME `-- init() . . -. . |-- CLI_VERSION |-- render() . . -. . |-- CLI_BASEDIR | |-- svg() . . -. . |-- CLI_FUNCDIR | `-- docbook() . . -. . |-- CLI_TEMPDIR |-- help() . . -. . `-- ... | |-- docbook() . . -. . | `-- texinfo() . . -. . |-- locale() . . -. . `-- ... . . -. ............................................. . -....................................................... +--------------------------------------------------------------- +Shell execution environment +----|-------------------|-------------------------------------- +. |-- TCAR_WORKDIR |-- EDITOR . +. |-- LANG |-- HOME . +. `-- centos-art.sh `-- ... . +. ----|------------------------------------------------ . +. centos-art.sh script execution environment . +. ----|--------------------|--------------------------- . +. . |-- CLI_NAME `-- cli() . . +. . |-- CLI_VERSION |-- render() . . +. . |-- CLI_BASEDIR | |-- svg() . . +. . |-- CLI_FUNCDIR | `-- docbook() . . +. . |-- TMPDIR |-- help() . . +. . `-- ... | |-- docbook() . . +. . | `-- texinfo() . . +. . |-- locale() . . +. . |-- cli_printMessage() . . +. . |-- cli_getFilesList() . . +. . `-- ... . . +. ..................................................... . +............................................................... @@ -67,76 +80,95 @@ User environment - To study the environment of centos-art.sh - script, you need to consider the directory structure under - trunk/Scripts/Bash/. In - this structure each directory under Functions/ creates a new function - environment inside the script environment. You can only - execute one function environment at a time for each script - environment. In some cases, it is possible to find a - sub-function environment which takes place inside the function - environment. Such is the case of the - render functionality which produces both - images and DocBook manuals. + The first file centos-art.sh script calls + is the + trunk/Scripts/Bash/Functions/Common/cli.sh + file. This file initializes variables and functions used along + the script execution environment. Such variables are for + internal use inside the centos-art.sh + script only and users shouldn't modify them to customize the + script in a per-user level. Instead, to customize the script + behaviour in a per-user level, users need to make use of + environment variables set in + ~/.bash_profile file. + + + + The functions initialized by + trunk/Scripts/Bash/Functions/Common/cli.sh + can be either common or specific. Common functionalities are + always loaded in each execution of centos-art.sh script. + Common functionalities are stored in the trunk/Scripts/Bash/Functions/Commons/ + directory and are made available for all specific + functionalities loaded later. Specific functionalities, on the + other hand, are loaded based in the first argument passed to + centos-art.sh script and are not available + for common functionalities. Specific functionalities are + stored in the trunk/Scripts/Bash/Functions/${CLI_FUNCDIRNAM} + directory. - - If you need more environment levels from sub-function - environment on, then it is a good time for you to consider the - creation of a new function environment at all. + In , + render, help and + locale are all specific functions while + cli_printMessage and + cli_getFilesList are common + functionality. - - - User's Profile (<filename>~/.bash_profile</filename>) + + Environment Variables - - Default working copy - TCAR_WORKDIR=${HOME}/artwork - The TCAR_WORKDIR environment variable is - specific to centos-art.sh script and - controls the working copy default location in the workstation. - This variable doesn't exist just after installing your - workstation. This variable appears inside the - ~/.bash_profile file (and so in the user - environment of yours) after configuring your workstation, as - described in . + The centos-art.sh script uses the following + system environment variables: - - - - Default execution path - PATH=$PATH:$HOME/bin + + + PATH + - This is the location where we store links to executable files - inside the working copy. + The PATH environment variable is specific to + the operating system and provides search paths for command + execution. By default, the centos-art.sh script links + executable scripts from the ~/bin directory which is one of + the locations used as search path in this variable. This is + how we create the centos-art command from + the centos-art.sh script inside your + working copy. - - - Default text editor - EDITOR=/usr/bin/vim - The default text editor information is controlled by the - EDITOR environment variable. The - centos-art.sh script uses the default text - editor to edit subversion pre-commit messages, translation - files, documentation files, script files, and similar - text-based files. + This variable is not initialized inside the + centos-art.sh script. Instead, the value + set in ~/.bash_profile file is used. + + + + + EDITOR + - 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: + The EDITOR environment variable is specific to + the operating system and provides the path to your default + text editor. The centos-art.sh script uses + the default text editor to edit subversion pre-commit + messages, translation files, documentation files, script + files, and similar text-based files. + + + + Possible values for this variable are: + - + /usr/bin/vim @@ -154,81 +186,209 @@ User environment /usr/bin/nano - + + + In case none of these values is set for the + EDITOR environment variable inside + ~/.bash_profile, the + centos-art.sh script uses /usr/bin/vim as default text + editor. This is the default text editor installed by default + in &TCD;. + + + + TEXTDOMAIN + - If none of these values is set in the EDITOR - environment variable, the centos-art.sh - script uses /usr/bin/vim text editor, the one - installed by default in &TCD;. + The TEXTDOMAIN environment variable is specific + to the operating system and provides the domain name of that + application we are producing translation messages for. This + variable, in combination with TEXTDOMAINDIR, is + used by gettext to find out the + location of translation messages. In the very specific case + of centos-art.sh script we use the + centos-art.sh name as domain name. - + + + This variable is initialized inside the + centos-art.sh script, so if you set it + outside it (e.g., in ~/.bash_profile) the + value you set there will be overwritten by that one set inside + centos-art.sh script, once it is executed. + + + - - Default locale information + + TEXTDOMAINDIR + - The default locale information is controlled by the - LANG environment variable. This variable is - initially set in the installation process of &TCD;, - specifically in the Language step. - Generally, there is no need to customize this variable in your - personal profile. If you need to change the value of this - environment variable do it through the login screen of GNOME - Desktop Environment or the - system-config-language command. + The TEXTDOMAINDIR environment variable is + specific to the operating system and provides the absolute + path to the directory containing the translation messages + related to that application specified by + TEXTDOMAIN environment variable. In the very + specific case of centos-art.sh script we + use the trunk/Locales/Scripts/Bash + path as default value. + + + This variable is initialized inside the + centos-art.sh script, so if you set it + outside it (e.g., in ~/.bash_profile) the + value you set there will be overwritten by that one set inside + centos-art.sh script, once it is executed. + + + + + + TMPDIR + + + The TMPDIR environment variable is specific to + the operating system and provides the absolute path to the + temporal directory the centos-art.sh script will use along its + execution. This variable is defined inside the + centos-art.sh script itself using the + mktemp command and will be unique on each + script execution. Thus, you should be able to run several + instances of centos-art.sh script + simultaneously without any problem. + + + + Each time you need to store temporal files, do it inside the + absolute path specified by this variable. + + + + This variable is initialized inside the + centos-art.sh script, so if you set it + outside it (e.g., in ~/.bash_profile) the + value you set there will be overwritten by that one set inside + centos-art.sh script, once it is executed. + + + + + + LANG + + + The LANG environment variable is specific to + the operating system and controls the default locale + information of it. The centos-art.sh + script use the LANG environment variable to + determine what language to use for printing output messages + from the script itself, as well as the portable objects + locations that need to be updated or edited when you localize + directory structures inside the working copy of &TCAR;. + + + + The LANG environment variable is initially set + in the installation process of &TCD;, specifically in the + Language step. Generally, there is no + need to customize this variable in your personal profile. If + you need to change the value of this environment variable do + it through the login screen of GNOME Desktop Environment or + the system-config-language command, or even + resetting the variable before executing the + centos-art.sh script. + + + + + + + + In addition to system environment variables described above, + the centos-art.sh script adds the following variables inside + the ~/.bash_profile file to control the + script behaviour in a per-user level: + + + TCAR_WORKDIR + - The centos-art.sh script use the - LANG environment variable to determine what - language to use for printing output messages from the script - itself, as well as the portable objects locations that need to - be updated or edited when you localize directory structures - inside the working copy of &TCAR;. + The TCAR_WORKDIR environment variable is + specific to centos-art.sh script and + controls the working copy default location in the workstation. + This variable doesn't exist just after installing your + workstation. In order for this variable to be customizable you + need to configure your workstation first, as described in + . + + + By default, when this variable hadn't been set, the + centos-art.sh script assumes the ${HOME}/artwork path as default + location for your working copy. - + + - - Default time zone representation + + TCAR_BRAND + - The time zone representation is a time correction applied to - the system time (stored in the BIOS clock) based on your - country location. This correction is specially useful to - distributed computers around the world that work together and - need to be syncronized in time to know when things happened. + ... + + + + + + + + Environment Functions + + + In addition to environment variables described above, the + centos-art.sh script makes available the following common + environment functions: + + + + + + cli_checkFiles FILE ... + - &TCAR; is made of one server and several workstations spread - around the world. In order for all these workstations to know - when changes in the server took place, it is required that - they all set their system clocks to use the same time - information (e.g., through UTC (Coordinated Universal Time)) - and set the time correction for their specific countries in - the operating system. Otherwise, it would be difficult to - know when something exactly happened. + ... + + + + cli_printMessage MESSAGE TYPE + - Generally, setting the time zone information is a - straight-forward task and configuration tools provided by - &TCD; do cover time correction for most of the countries - around the world, thus we don't include it to your personal - profile. + ... + + + + cli_exportFunctions PATH + - In case you need a time precision not provided by any of the - date and time configuration tools provided by &TCD; then, you - need to customize the TZ environment variable - in your personal profile to correct the time information by - yourself. The format of TZ environment - variable is described in tzset(3) manual page. + ... - + + + +