Blame Documentation/Manuals/Tcar-ug/Scripts/Bash/environment.docbook

a01c20
<sect1 id="scripts-bash-environment">
a01c20
ffbf51
    <title>Execution Environment</title>
a01c20
a01c20
    <para>
a01c20
        When you login in your computer you enter into a unique user
a01c20
        environment which you can customize by setting environment
a01c20
        variables in the <filename>~/.bash_profile</filename>
a01c20
        file.<footnote><para>To know more about environment variables,
a01c20
        see the bash(1) man page.</para></footnote> This way different
a01c20
        users can benefit from their own environment variables to
a01c20
        customize the execution of <command>centos-art.sh</command>
ffbf51
        script in a safe way.  For example, users can use the
ffbf51
        variables of their environments to set different locations for
ffbf51
        their working copies of &TCAR;.<footnote><para>See 
ffbf51
        linkend="repo-ws-config-ChangeWorkingCopy"
ffbf51
        /></para></footnote>
a01c20
    </para>
a01c20
a01c20
    <para>
a01c20
        When you execute the <command>centos-art.sh</command> script,
a01c20
        you create a new environment inside the user environment which
ffbf51
        we call the script environment. This environment inherits all
ffbf51
        variables from the user environment and contains the variables
ffbf51
        and functionalities defined by the script itself. If your only
ffbf51
        interest is using the <command>centos-art.sh</command> script
ffbf51
        to accomplish tasks inside the working copy, you don't need to
ffbf51
        know the whole environment it uses, but the user environment
ffbf51
        only. However, if your interest is improving it somehow, to
ffbf51
        know the environment where it is run is a fundamental
ffbf51
        knowledge you need to be armed with in order to understand
ffbf51
        where to put the code you want to contribute inside the
ffbf51
        script.
a01c20
    </para>
a01c20
a01c20
    <example id="scripts-bash-environment-1">
ffbf51
    <title>The script environment</title>
a01c20
    <screenshot>
ffbf51
    <screeninfo>The script environment</screeninfo>
a01c20
    <mediaobject>
a01c20
    <textobject>
a01c20
<programlisting>
ffbf51
-------------------------------------------------------
a01c20
User environment
ffbf51
----|-------------------|------------------------------
ffbf51
.   |-- TCAR_WORKDIR    |-- EDITOR                    .
ffbf51
.   |-- LANG            |-- HOME                      .
ffbf51
.   `-- centos-art.sh   `-- ...                       .
ffbf51
.       ----|---------------------------------------- .
ffbf51
.       centos-art.sh script environment              .
ffbf51
.       ----|-----------------|---------------------- .
ffbf51
.       .   |-- CLI_NAME      `-- init()            . .
ffbf51
.       .   |-- CLI_VERSION       |-- render()      . .
ffbf51
.       .   |-- CLI_BASEDIR       |   |-- svg()     . .
ffbf51
.       .   |-- CLI_FUNCDIR       |   `-- docbook() . .
ffbf51
.       .   |-- CLI_TEMPDIR       |-- help()        . .
ffbf51
.       .   `-- ...               |   |-- docbook() . .
ffbf51
.       .                         |   `-- texinfo() . .
ffbf51
.       .                         |-- locale()      . .
ffbf51
.       .                         `-- ...           . .
ffbf51
.       ............................................. .
ffbf51
.......................................................
a01c20
</programlisting>
a01c20
    </textobject>
a01c20
    </mediaobject>
a01c20
    </screenshot>
a01c20
    </example>
a01c20
a01c20
    <para>
a01c20
        To study the environment of <command>centos-art.sh</command>
ffbf51
        script, you need to consider the directory structure under
ffbf51
        <filename class="directory">trunk/Scripts/Bash/</filename>. In
ffbf51
        this structure each directory under 
ffbf51
        class="directory">Functions/</filename> creates a new function
ffbf51
        environment inside the script environment. You can only
ffbf51
        execute one function environment at a time for each script
ffbf51
        environment. In some cases, it is possible to find a
a01c20
        sub-function environment which takes place inside the function
ffbf51
        environment.  Such is the case of the
a01c20
        <function>render</function> functionality which produces both
ffbf51
        images and DocBook manuals.
a01c20
    </para>
a01c20
    
a01c20
    <note>
a01c20
    <para>
a01c20
        If you need more environment levels from sub-function
a01c20
        environment on, then it is a good time for you to consider the
a01c20
        creation of a new function environment at all.
a01c20
    </para>
a01c20
    </note>
a01c20
a01c20
    <sect2>
a01c20
    <title>User's Profile (<filename>~/.bash_profile</filename>)</title>
a01c20
a01c20
    <sect3>
a01c20
    <title>Default working copy</title>
a01c20
    <screen>TCAR_WORKDIR=${HOME}/artwork</screen>
a01c20
    <para>
a01c20
        The <envar>TCAR_WORKDIR</envar> environment variable is
a01c20
        specific to <command>centos-art.sh</command> script and
a01c20
        controls the working copy default location in the workstation.
a01c20
        This variable doesn't exist just after installing your
a01c20
        workstation. This variable appears inside the
a01c20
        <filename>~/.bash_profile</filename> file (and so in the user
a01c20
        environment of yours) after configuring your workstation, as
a01c20
        described in <xref linkend="repo-ws-config" />.
a01c20
    </para>
a01c20
a01c20
    </sect3>
a01c20
a01c20
    <sect3>
a01c20
    <title>Default execution path</title>
a01c20
    <screen>PATH=$PATH:$HOME/bin</screen>
a01c20
    <para>
a01c20
        This is the location where we store links to executable files
a01c20
        inside the working copy.
a01c20
    </para>
a01c20
    </sect3>
a01c20
a01c20
    <sect3>
a01c20
    <title>Default text editor</title>
a01c20
    <screen>EDITOR=/usr/bin/vim</screen>
a01c20
    <para>
a01c20
        The default text editor information is controlled by the
a01c20
        <envar>EDITOR</envar> environment variable. The
a01c20
        <command>centos-art.sh</command> script uses the default text
a01c20
        editor to edit subversion pre-commit messages, translation
a01c20
        files, documentation files, script files, and similar
a01c20
        text-based files.
a01c20
    </para>
a01c20
a01c20
    <para>
a01c20
        If <envar>EDITOR</envar> environment variable is not set,
a01c20
        <command>centos-art.sh</command> script uses 
a01c20
        class="directory">/usr/bin/vim</filename> as default text
a01c20
        editor. Otherwise, the following values are recognized by
a01c20
        <command>centos-art.sh</command> script:
a01c20
a01c20
        <itemizedlist>
a01c20
        <listitem>
a01c20
        <para>
a01c20
            <filename class="directory">/usr/bin/vim</filename>
a01c20
        </para>
a01c20
        </listitem>
a01c20
a01c20
        <listitem>
a01c20
        <para>
a01c20
        <filename class="directory">/usr/bin/emacs</filename>
a01c20
        </para>
a01c20
        </listitem>
a01c20
a01c20
        <listitem>
a01c20
        <para>
a01c20
            <filename class="directory">/usr/bin/nano</filename>
a01c20
        </para>
a01c20
        </listitem>
a01c20
        </itemizedlist>
a01c20
a01c20
    </para>
a01c20
a01c20
    <para>
a01c20
        If none of these values is set in the <envar>EDITOR</envar>
a01c20
        environment variable, the <command>centos-art.sh</command>
a01c20
        script uses 
a01c20
        class="directory">/usr/bin/vim</filename> text editor, the one
a01c20
        installed by default in &TC;;. 
a01c20
    </para>
a01c20
    </sect3>
a01c20
a01c20
    <sect3>
a01c20
    <title>Default locale information</title>
a01c20
    <para>
a01c20
        The default locale information is controlled by the
a01c20
        <envar>LANG</envar> environment variable. This variable is
a01c20
        initially set in the installation process of &TC;;,
a01c20
        specifically in the <emphasis>Language</emphasis> step.
a01c20
        Generally, there is no need to customize this variable in your
a01c20
        personal profile. If you need to change the value of this
a01c20
        environment variable do it through the login screen of GNOME
a01c20
        Desktop Environment or the
a01c20
        <command>system-config-language</command> command.
a01c20
    </para>
a01c20
a01c20
    <para>
ffbf51
        The <command>centos-art.sh</command> script use the
a01c20
        <envar>LANG</envar> environment variable to determine what
a01c20
        language to use for printing output messages from the script
a01c20
        itself, as well as the portable objects locations that need to
a01c20
        be updated or edited when you localize directory structures
a01c20
        inside the working copy of &TCAR;.
a01c20
    </para>
a01c20
    </sect3>
a01c20
a01c20
    <sect3>
a01c20
    <title>Default time zone representation</title>
a01c20
    <para>
a01c20
        The time zone representation is a time correction applied to
a01c20
        the system time (stored in the BIOS clock) based on your
a01c20
        country location.  This correction is specially useful to
a01c20
        distributed computers around the world that work together and
a01c20
        need to be syncronized in time to know when things happened.
a01c20
    </para>
a01c20
    <para>
a01c20
        &TCAR; is made of one server and several workstations spread
a01c20
        around the world. In order for all these workstations to know
a01c20
        when changes in the server took place, it is required that
a01c20
        they all set their system clocks to use the same time
a01c20
        information (e.g., through UTC (Coordinated Universal Time))
a01c20
        and set the time correction for their specific countries in
a01c20
        the operating system.  Otherwise, it would be difficult to
a01c20
        know when something exactly happened.
a01c20
    </para>
a01c20
a01c20
    <para>
a01c20
        Generally, setting the time zone information is a
a01c20
        straight-forward task and configuration tools provided by
a01c20
        &TC;; do cover time correction for most of the countries
a01c20
        around the world, thus we don't include it to your personal
a01c20
        profile.
a01c20
    </para>
a01c20
a01c20
    <para>
a01c20
        In case you need a time precision not provided by any of the
a01c20
        date and time configuration tools provided by &TC;; then, you
a01c20
        need to customize the <envar>TZ</envar> environment variable
a01c20
        in your personal profile to correct the time information by
a01c20
        yourself.  The format of <envar>TZ</envar> environment
a01c20
        variable is described in tzset(3) manual page.  
a01c20
    </para>
a01c20
    </sect3>
a01c20
a01c20
    </sect2>
a01c20
a01c20
</sect1>