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

    <title>The Execution Environment</title>

    <para>
        The execution environment of <command>centos-art.sh</command>
        script is organized in four levels.  The first level is the
        <quote>shell environment</quote>, the second level is the
        <quote>command environment</quote>, the third level is the
        <quote>common functions environment</quote> and, finally, the
        fourth level which contains the <quote>specific function
        environment</quote>, as described in <xref
        linkend="scripts-bash-environment-example1" />.  In this
        context, child environments inherit definitions (e.g.,
        variables and functions) from their parent environments making
        possible to logically organize the script in a way that needs
        can be isolated one another to follow the paradigm proposed by
        Unix developers at Bell Labs when felt that programs
        <quote>should do one thing well.</quote>
    </para>

    <example id="scripts-bash-environment-example1">
    <title>The execution environment</title>
    <screenshot>
    <screeninfo>The execution environment</screeninfo>
    <mediaobject>
    <textobject>
<programlisting>
+-----------------------------------------------------+
| Shell environment                                   |
+---|-------------------|-----------------|-----------+
.   |-- TCAR_WORKDIR    |-- TCAR_BRAND    |-- EDITOR  .
.   |-- LANG            |-- HOME          |-- PATH    .
.   `-- centos-art.sh   `-- TMPDIR        `-- ...     .
.   +---|-----------------------------------------+   .
.   | Command environment                         |   .
.   +---|---------------|----------------|--------+   .
.   .   |-- CLI_NAME    |-- CLI_VERSION  `-- ...  .   .
.   .   |-- CLI_FUNCDIR `-- CLI_BASEDIR           .   .
.   .   `-- cli()                                 .   .
.   .   +---|-----------------------------------+ .   .
.   .   | Common functions environment          | .   .
.   .   +---|------------------------|----------+ .   .
.   .   .   |-- cli_printMessage()   |-- ...    . .   .
.   .   .   |-- cli_getFilesList()   |-- ...    . .   .
.   .   .   `-- render()             `-- ...    . .   .
.   .   .   +---|---------------------------+   . .   .
.   .   .   | Specific function environment |   . .   .
.   .   .   +-------------------------------+   . .   .
.   .   ......................................... .   .
.   ...............................................   .
.......................................................
</programlisting>
    </textobject>
    </mediaobject>
    </screenshot>
    </example>

    <sect2>
    <title>The Shell Environment</title>

    <para>
        The <command>centos-art.sh</command> script uses the following
        shell 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 <command>centos-art.sh</command>
        script links executable scripts from the <filename
        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 <filename
        class="directory">/usr/bin/vim</filename> as default text
        editor. This is the text editor installed by default in &TCD;. 
    </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 <filename
        class="directory">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>
        When you contribute code to <command>centos-art.sh</command>
        script and need to create temporal files, do it inside the
        absolute path specified by this variable.
    </para>

    <para>
        This variable is redefined 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 &TCD;, 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 shell 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 of &TCAR;.  This is
        the place in your workstation where &TCAR; file system is
        stored for you to work with it.
    </para>

    <para>
        By default, just after installing your workstation, this
        variable will not be found in it and the
        <command>centos-art.sh</command> script will finish its
        execution with an error message if you try to execute it
        without any argument. This behaviour is OK because the
        <command>centos-art.sh</command> script doesn't know where you
        stored the working copy of &TCAR; in your workstation. In
        order for this variable to exist in your workstation you need
        to configure your workstation first, as described in <xref
        linkend="repo-ws-config" />.
    </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 <filename
        class="directory">Identity/Models/Brands</filename>
        directory).
    </para>
    <para>
        By default, this variable takes <quote>centos</quote> 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 <filename
        class="directory">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>

    </sect2>

    <sect2>
    <title>The Command Environment</title>

    <para>
        The first file the <command>centos-art.sh</command> script
        calls is the
        <filename>Scripts/Bash/Functions/Commons/cli.sh</filename>
        file. This file initializes all variables and functions you
        will be able to use 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, you need to make use of your personal
        environment variables set in the
        <filename>~/.bash_profile</filename> file.
    </para>

    <para>
        Once environment variables are initialized, the
        <command>centos-art.sh</command> script initializes common and
        specific environment functions, in that order.
    </para>

    <sect3>
    <title>Common Function Environment</title>
    
    <para>
        Common function environments are stored under <filename
        class="directory">Scripts/Bash/Functions/Commons</filename>
        directory and will be available always, both for common
        environment functions themselves and specific environment
        functions.
    </para>

    </sect3>

    <sect3>
    <title>Specific Function Environments</title>

    <para>
        Specific function environments, on the other hand, are stored
        in the <filename
        class="directory">Scripts/Bash/Functions/${CLI_FUNCDIRNAM}/${CLI_FUNCNAME}.sh</filename>
        file, where:
    </para>

    <variablelist>
    <varlistentry>
    <term><varname>CLI_FUNCDIRNAME</varname></term>
    <listitem>
    <para>
        Is the first argument passed to
        <command>centos-art.sh</command> script with the first letter
        in uppercase but the rest in lowercase. For example,
        <literal>Render</literal>, <literal>Locale</literal> and
        <literal>Help</literal> are all possible values to this
        variable.
     </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><varname>CLI_FUNCNAME</varname></term>
    <listitem>
    <para>
        Is the first argument passed to
        <command>centos-art.sh</command> script with all letters in
        lowercase. For example, <literal>render</literal>,
        <literal>locale</literal> and <literal>help</literal> are all
        possible values to this variable. 
    </para>
    </listitem>
    </varlistentry>
    </variablelist>
    
    <para>
        Specific functions environment can be written in just one file
        or in several files inside the same directory. Using one file
        to write specific functions environment is rarely seen inside
        the <command>centos-art.sh</command> script but it could
        happen in situations where the need you want to solve can be
        written in a few lines inside just one file. On the other
        hand, if you find yourself writing a too long file, it is
        convenient to logically divide it into several files. This
        logical division takes place using functions, which indeed
        create other environments where you can create and express
        your solutions.
    </para>

    <para>
        The order in which individual files are exported and executed
        inside the specific functions environments depends in the way
        each developer write the <filename
        class="directory">Scripts/Bash/Functions/${CLI_FUNCDIRNAM}/${CLI_FUNCNAME}.sh</filename>
        file. This is the main file inside the specific function
        environment and controls the kind of logical division you
        implement to organize the solution you need. As file name
        convention, the following structure for new specific functions
        environment is proposed:
    </para>

<programlisting>
Scripts/Bash/Functions/${CLI_FUNCDIRNAM}/
|-- ${CLI_FUNCNAME}.sh
`-- ${CLI_FUNCNAME}_verbSubject.sh
</programlisting>

    <para>
        Specific functions environment is exported after common
        functions environment does, so it is not possible for specific
        functions environment to be available inside the common
        functions environment, nor inside other specific functions
        environment, different to the one been passed as first
        argument to the <command>centos-art.sh</command> script
        command-line.<footnote>
            <para>
                Although, it is possible for you to call the
                <command>centos-art.sh</command> script to itself
                through the <function>cli_runFnEnvironment</function>
                common function environment.
            </para>
        </footnote> In <xref
        linkend="scripts-bash-environment-example1" />,
        <function>render</function> is a specific function environment
        while <function>cli_printMessage</function> and
        <function>cli_getFilesList</function> are common function
        environments.
    </para>

    <para>
        Both specific and common function environments 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 function
        environments.
    </para>
    </sect3>

    </sect2>

</sect1>