<section id="scripts-bash-environment">

    <title>Execution Environment Reference</title>

    <para>

        The execution environment of <command>centos-art.sh</command>

        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 <command>centos-art.sh</command> 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

        <filename>~/.bash_profile</filename> file, as well.

    </para>

    <para>

        The <command>centos-art.sh</command> script uses the

        <filename>~/.bash_profile</filename> file to implement

        per-user customizations.  For example, you can use this file

        to set the location of your working copy through the

        <envar>TCAR_WORKDIR</envar> enviroment variable. By default

        this variable is set to 

        class="directory">${HOME}/artwork</filename>, but you can

        reset to something different to fit your needs. See 

        linkend="repo-ws-config-ChangeWorkingCopy" />.

    </para>

    <para>

        Once the <command>centos-art.sh</command> script has been

        executed, it creates different levels of execution

        environments inside the one created by the script itself on

        the shell.  These different environment levels can be seen as

        a tree of execution environments which inherit one another, as

        illustrated in 

        linkend="scripts-bash-environments-example1" />.  These

        different levels of execution evironments are where the

        <command>centos-art.sh</command> script is developed in.

    </para>

    <example id="scripts-bash-environments-example1">

    <title>The execution environment</title>

    <screenshot>

    <screeninfo>The execution environment</screeninfo>

    <mediaobject>

    <textobject>

<programlisting>

---------------------------------------------------------------

Shell execution environment

----|-------------------|-----------------|--------------------

.   |-- TCAR_WORKDIR    |-- TCAR_BRAND    |-- EDITOR          .

.   |-- LANG            |-- HOME          |-- PATH            .

.   `-- 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() . .

.       .                            `-- ...                . .

.       ..................................................... .

...............................................................

</programlisting>

    </textobject>

    </mediaobject>

    </screenshot>

    </example>

    <para>

        The first file the <command>centos-art.sh</command> script

        calls is the

        <filename>trunk/Scripts/Bash/Functions/Common/cli.sh</filename>

        file. This file initializes variables and functions can be

        used along the script execution environment lifetime.  Such

        environment variables are for internal use inside the

        <command>centos-art.sh</command> 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 <filename>~/.bash_profile</filename> file.

    </para>

    <section id="scripts-bash-environment-varref">

    <title>Environment Variables</title>

    <para>

        The <command>centos-art.sh</command> script uses the following

        system environment variables:

    </para>

    <variablelist>

    <varlistentry>

    <term><envar>PATH</envar></term>

    <listitem>

    <para>

        The <envar>PATH</envar> 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 

        class="directory">~/bin</filename> directory which is one of

        the locations used as search path in this variable. This is

        how we create the <command>centos-art</command> command from

        the <command>centos-art.sh</command> script  inside your

        working copy.

    </para>

    <para>

        This variable is not initialized inside the

        <command>centos-art.sh</command> script. Instead, the value

        set in <filename>~/.bash_profile</filename> file is used. 

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><envar>EDITOR</envar></term>

    <listitem>

    <para>

        The <envar>EDITOR</envar> environment variable is specific to

        the operating system and provides the path to your default

        text editor. The <command>centos-art.sh</command> script uses

        the default text editor to edit subversion pre-commit

        messages, translation files, documentation files, script

        files, and similar text-based files.  

    </para>

    <para>

        Possible values for this variable are:

    </para>

    <itemizedlist>

        <listitem>

        <para>

            <filename class="directory">/usr/bin/vim</filename>

        </para>

        </listitem>

        <listitem>

        <para>

        <filename class="directory">/usr/bin/emacs</filename>

        </para>

        </listitem>

        <listitem>

        <para>

            <filename class="directory">/usr/bin/nano</filename>

        </para>

        </listitem>

    </itemizedlist>

    <para>

        In case none of these values is set for the

        <envar>EDITOR</envar> environment variable inside

        <filename>~/.bash_profile</filename>, the

        <command>centos-art.sh</command> script uses 

        class="directory">/usr/bin/vim</filename> as default text

        editor. This is the default text editor installed by default

        in &TC;;. 

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><varname>TEXTDOMAIN</varname></term>

    <listitem>

    <para>

        The <envar>TEXTDOMAIN</envar> 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 <envar>TEXTDOMAINDIR</envar>, is

        used by <application>gettext</application> to find out the

        location of translation messages.  In the very specific case

        of <command>centos-art.sh</command> script we use the

        <literal>centos-art.sh</literal> name as domain name.

    </para>

    <para>

        This variable is initialized inside the

        <command>centos-art.sh</command> script, so if you set it

        outside it (e.g., in <filename>~/.bash_profile</filename>) the

        value you set there will be overwritten by that one set inside

        <command>centos-art.sh</command> script, once it is executed.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><varname>TEXTDOMAINDIR</varname></term>

    <listitem>

    <para>

        The <envar>TEXTDOMAINDIR</envar> 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

        <envar>TEXTDOMAIN</envar> environment variable.  In the very

        specific case of <command>centos-art.sh</command> script we

        use the 

        class="directory">trunk/Locales/Scripts/Bash</filename>

        path as default value.

    </para>

    <para>

        This variable is initialized inside the

        <command>centos-art.sh</command> script, so if you set it

        outside it (e.g., in <filename>~/.bash_profile</filename>) the

        value you set there will be overwritten by that one set inside

        <command>centos-art.sh</command> script, once it is executed.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><envar>TMPDIR</envar></term>

    <listitem>

    <para>

        The <envar>TMPDIR</envar> 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

        <command>centos-art.sh</command> script itself using the

        <command>mktemp</command> command and will be unique on each

        script execution. Thus, you should be able to run several

        instances of <command>centos-art.sh</command> script

        simultaneously without any problem. 

    </para>

    <para>

        Each time you need to store temporal files, do it inside the

        absolute path specified by this variable.

    </para>

    <para>

        This variable is initialized inside the

        <command>centos-art.sh</command> script, so if you set it

        outside it (e.g., in <filename>~/.bash_profile</filename>) the

        value you set there will be overwritten by that one set inside

        <command>centos-art.sh</command> script, once it is executed.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><envar>LANG</envar></term>

    <listitem>

    <para>

        The <envar>LANG</envar> environment variable is specific to

        the operating system and controls the default locale

        information of it.  The <command>centos-art.sh</command>

        script use the <envar>LANG</envar> 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;.

    </para>

    <para>

        The <envar>LANG</envar> environment variable is initially set

        in the installation process of &TC;;, specifically in the

        <emphasis>Language</emphasis> 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 <command>system-config-language</command> command, or even

        resetting the variable before executing the

        <command>centos-art.sh</command> script.

    </para>

    </listitem>

    </varlistentry>

    </variablelist>

    <para>

        In addition to system environment variables described above,

        the <command>centos-art.sh</command> script adds the following

        variables inside the <filename>~/.bash_profile</filename> file

        to control the script behaviour in a per-user level:

    </para>

    <variablelist>

    <varlistentry>

    <term><varname>TCAR_WORKDIR</varname></term>

    <listitem>

    <para>

        The <envar>TCAR_WORKDIR</envar> environment variable is

        specific to <command>centos-art.sh</command> 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

        <xref linkend="repo-ws-config" />.

    </para>

    <para>

        By default, when this variable is not set, the

        <command>centos-art.sh</command> script assumes the 

        class="directory">${HOME}/artwork</filename> path as default

        location for your working copy.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><varname>TCAR_BRAND</varname></term>

    <listitem>

    <para>

        The <envar>TCAR_BRAND</envar> environment variable is specific

        to <command>centos-art.sh</command> script and controls the

        brand information that identifies the content produced inside

        &TCAR;. The brand information is used to give name to some

        files inside the repository (e.g., see files under 

        class="directory">trunk/Identity/Models/Brands</filename>

        directory).

    </para>

    <para>

        By default, this variable takes <literal>centos</literal> as

        value. In case you want to change it to something else, you

        should consider the following implications:

    </para>

    <itemizedlist>

    <listitem>

    <para>

        The <command>centos-art.sh</command> script will no longer be

        referred as such. Instead, the

        <filename>${TCAR_BRAND}-art.sh</filename> name will be used.

        This implies that you no longer are using the

        <command>centos-art.sh</command> file we provide as part of

        &TCAR; and won't be able to commit changes to it. However, if

        you retain the same logic from

        <command>centos-art.sh</command> script in

        <filename>${TCAR_WORKDIR}-art.sh</filename>, you can use

        common and specific functionalities provided by

        <command>centos-art.sh</command> script and commit changes to

        them.

    </para>

    </listitem>

    <listitem>

    <para>

        The files stored under 

        class="directory">trunk/Identity/Models/Brands</filename>

        should be named using the value of

        <literal>${TCAR_BRAND}</literal> as section. If you change

        the value of this variable, you need to be sure the new value

        set does coincide with the file names you use to store brand

        information.

    </para>

    </listitem>

    </itemizedlist>

    </listitem>

    </varlistentry>

    </variablelist>

    </section>

    <section id="scripts-bash-environment-func">

    <title>Environment Functions</title>

    <para>

        Once environment variables are initialized, the

        <command>centos-art.sh</command> script initializes common and

        specific environment functions.

    </para>

    <para>

        Common environment functions are stored under 

        class="directory">trunk/Scripts/Bash/Functions/Commons</filename>

        directory and will be available always, both for common

        environment functions themselves and specific environment

        functions.

    </para>

    <para>

        Specific environment functionalities, on the other hand, are

        stored in the 

        class="directory">trunk/Scripts/Bash/Functions/${CLI_FUNCDIRNAM}/${CLI_FUNCNAME}.sh</filename>

        file, where <varname>CLI_FUNCDIRNAME</varname> is the first

        argument passed to centos-art.sh script with the first letter

        in uppercase but the rest in lowercase and

        <varname>CLI_FUNCNAME</varname> is the first argument passed

        to centos-art.sh script with all letters in lowercase.

        Specific functionalities are exported after common

        functionalities, so specific environment functionalities

        aren't available inside common environment functionalities.

    </para>

    <para>

        In <xref linkend="scripts-bash-environments-example1" />,

        <function>render</function>, <function>help</function> and

        <function>locale</function> are all specific environment

        functions while <function>cli_printMessage</function> and

        <function>cli_getFilesList</function> are common environment

        functions.

    </para>

    <para>

        Both specific and common environment functions exist to

        standardize frequent tasks inside &TCAR;. The following

        sections will describe which these frequent tasks are and the

        way they are standardized using specific and common

        environment functions.

    </para>

    </section>

</section>