<sect1 id="repo-ws-config">

    <title>Configuring Your Workstation</title>

    <para>

        Once your worstation is installed, it is time for you to

        configure it.  At this point you create a user for everyday's

        work, configure third party repositories, fix environment

        variables to fit your personal needs, download the working

        copy of &TCAR; and prepare it for start using it.

    </para>

    <sect2 id="repo-ws-config-wp">

    <title>Workplace</title>

    <para>

        Once you've installed the workstation and it is up and

        running, you need to create the user name you'll use for your

        everyday's work. In this task you need to use the commands

        <command>useradd</command> and <command>passwd</command> to

        create the user name and set a password for it, respectively.

        These commands require administrative privileges to be

        executed, so you need to login as <emphasis>root</emphasis>

        superuser for doing so. 

    </para>

    <caution>

    <para>

        Do not use the <emphasis>root</emphasis> username for your

        everyday's work inside your working copy of &TCAR;.  This is

        dangerous and might provoke unreversable damages on your

        workstation.

    </para>

    </caution>

    <para>

        When user names are created inside the workstation, it doesn't

        create only a user identifier for you to login, but a place

        for you to store your information, as well. This place is

        known as your home directory and is unique for each user

        inside the workstation.  At the moment, we face the following

        design problems related to handling absolute paths inside the

        working copies of &TCAR;:

    </para>

    <variablelist>

    <varlistentry>

    <term>Case 1: Different home directories</term>

    <listitem>

    <para>

        Assuming you store your working copy under 

        class="directory">/home/john/artwork/</filename> and I store

        mine under 

        class="directory">/home/al/artwork/</filename>, we'll end up

        refering the same files inside our working copies through

        different absolute paths. This generates a contradiction when

        files, holding path information inside, are committed up to

        the central repository. The contradiction comes from the

        question: which is the correct absolute path to use inside

        such files, yours or mine? — No one of them is, of

        course.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>Case 2: One unique home directory</term>

    <listitem>

    <para>

        Another case would be that you and I ourselves use one unique

        home directory (e.g., 

        class="directory">/home/centos/artwork/</filename>) to store

        the working copy of &TCAR; in our own workstations, but

        configure the subversion client to use different user names to

        commit changes up from the working copy to the central

        repository.  This configuration might be not so good for

        situations where you and I have to share the same workstation.

        In such case, it would be required that we both share the

        password information of the same system user (the

        <emphasis>centos</emphasis> user in our example) which, in

        addition, gives access to that user's subversion client

        configuration and this way provokes the whole sense of using

        different subversion credentials for committing changes to be

        lost.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>Case 3: Different home directories through dynamic expansion</term>

    <listitem>

    <para>

        Most of the absolute paths we use inside the working copy are

        made of two parts, one dynamic and one fixed. The dynamic part

        is the home directory of the current user and its value can be

        retrived from the <envar>$HOME</envar> environment variable.

        The fixed part of the path is the one we set inside the

        repositroy structure itself as organization matter.  What we

        need here is to find a way to expand variables inside files

        that don't support variable expansion.  So far we've been

        doing this through creation template instances which are

        temporal files with translation markers expanded inside.  This

        work rather fine with template files that are one-time-pass

        (e.g., when we produce produce PNG files from SVG files and

        XTHML from DocBook files), but the same is not true for

        absolute paths inside files that are used as in their

        permanent state inside the repository (e.g., CSS files and

        other files similar in purpose).

    </para>

    </listitem>

    </varlistentry>

    </variablelist>

    <para>

        From the three cases discussed above, the second one (i.e.,

        One unique home directory) seems to be the best candidate. It

        limits us from using more than one working copy in the same

        workstation, but gives us the chance of standardizing the use

        of absolute paths inside all the working copies of &TCAR;.

        Using absolute paths is very convenient because it is possible

        to reuse information from different locations inside the

        working copy, something that would be almost imposible to

        maintain if relative paths were used instead. Thus, lets

        assume the second case of handling home directories as default

        solution to relatively solve the problem of where to store

        working copies of &TCAR; until a better one shows itself up.

    </para>

    <para>

        The action of providing working copies of &TCAR; that permit

        to reuse files inside them unifies the way content is produced

        inside the working copy and provides a convenction for people

        working on different areas to get attached to in order to

        syncronize their works and still keep doing it decentralized

        one another.

    </para>

    </sect2>

    <sect2 id="repo-ws-config-envar">

    <title>Environment Variables</title>

    <para>

        Once you've created the <emphasis>centos</emphasis> user name

        for your everyday's work and you had done login with it, there

        are some environment variables that you can customize to fit

        your personal needs (e.g., default text editor, default locale

        information, default time zone representation, etc.).  To

        customize these variables you need to edit your personal

        profile (i.e., 

        class="directory">~/.bash_profile</filename>) and set the

        redefinition there.  Notice that you may need to logout and

        then do login again in order for the new variable values to

        take effect.

    </para>

    <variablelist>

    <varlistentry>

    <term>Default text editor</term>

    <listitem>

    <para>

        The default text editor information is controlled by the

        <envar>EDITOR</envar> environment variable. 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>

        If <envar>EDITOR</envar> environment variable is not set,

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

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

        editor. Otherwise, the following values are recognized by

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

        <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>

    <para>

        If no one of these values is set in the <envar>EDITOR</envar>

        environment variable, the <command>centos-art.sh</command>

        script uses 

        class="directory">/usr/bin/vim</filename> text editor, the one

        installed by default in &TC;;. 

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>Default locale information</term>

    <listitem>

    <para>

        The default locale information is controlled by the

        <envar>LANG</envar> environment variable. This 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.

    </para>

    <para>

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

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>Default time zone representation</term>

    <listitem>

    <para>

        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.

    </para>

    <para>

        &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.

    </para>

    <para>

        Generally, setting the time information is a straight-forward

        task and configuration tools provided by &TC;; do cover time

        correction for most of the countries around the world.

        However, if you need a time precision not provided by any of

        the date and time configuration tools provided by &TC;; then,

        you need to customize the <envar>TZ</envar> environment

        variable in your personal profile to correct the time

        information by yourself.  The format of <envar>TZ</envar>

        environment variable is described in tzset(3)

        manual page.  

    </para>

    </listitem>

    </varlistentry>

    </variablelist>

    </sect2>

    <sect2 id="repo-ws-config-sudo">

    <title>Administrative Tasks</title>

    <para>

        Sometimes it is necessary that you perform administrative

        tasks inside the workstation the working copy of &TCAR; is

        stored in. These tasks might demand you to type many commands

        (e.g., for configuring a third party repository) or just a

        one-line command (e.g., for installing a new package).  In

        both cases this kind of tasks require permissions that your

        user for everyday's work must not have under no mean. 

    </para>

    <para>

        To perform administrative tasks in your workstation, you need

        to login as <emphasis>root</emphasis> or configure the

        <command>sudo</command> program to temporarily granting the

        permissions your regular user needs to perform the

        administrative tasks. The configuration of

        <command>sudo</command> program is at

        <filename>/etc/sudoers</filename> file and you need to add the

        <emphasis>centos</emphasis> user to the list of privileged

        user as described in the section below:

    </para>

<screen>

## Next comes the main part: which users can run what software on 

## which machines (the sudoers file can be shared between multiple

## systems).

## Syntax:

##

##      user    MACHINE=COMMANDS

##

## The COMMANDS section may have other options added to it.

##

## Allow root to run any commands anywhere 

root    ALL=(ALL)       ALL

centos  ALL=(ALL)       ALL

</screen>

    <para>

        This configuration is required in order for automation scripts

        to realize administrative tasks that otherwise you would need

        to type one by one.  It is worth to mention that all these

        tasks are organized in the <function>prepare</function>

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

        in the sake of reducing work and standardize the procedure of

        performing them. It is also worth to mention that, the

        <command>centos-art.sh</command> script is available for you

        to run, study, improve and share your changes as described in

        <xref linkend="licenses-gpl" />.

    </para>

    </sect2>

    <sect2 id="repo-ws-config-wc">

    <title>Working Copy</title>

    <para>

        Once you've installed and configured the workstation, it is

        ready to receive the working copy of &TCAR;. In this step, you

        use Subversion's client to communicate the source repository

        of &TCAR;  and download all the files that make a working copy

        of it.

    </para>

    <para>

        To download the working copy of &TCAR; you need to login as

        your everyday's work user (i.e., the

        <emphasis>centos</emphasis> user) and use the Subversion

        client installed in your workstation to bring all the files

        you need to work with from the source repository down to your

        workstation, just as the following command describes:

    </para>

    <screen>svn co https://projects.centos.org/svn/artwork ~/</screen>

    <para>

        This command will create your working copy of &TCAR; in your

        workstation, specifically in the 

        class="directory">/home/centos/artwork</filename> directory.

    </para>

    <note>

    <para>

        If the Subversion's client wasn't installed by default, you

        need to install it using the following command:

    </para>

    <screen>sudo yum install subversion</screen>

    </note>

    <para>

        Once your working copy of &TCAR; has been downloaded, you

        should notice that there is no image files, nor documentation,

        or localized content inside it. This is because all the files

        provided in the working copy are source files (e.g., the files

        needed to produce other files) and it is up to you the action

        of render them to produce the final files (e.g., images and

        documentation) used to implement &TCPCVI;. 

    </para>

    <para>

        Another consideration to be aware of at this point, is the

        need of verifying the software installed in the workstation,

        as well as the creation of symbolic links to connect the

        content produced inside the working copy to applications

        outside it (e.g., to make available patterns, brushes, and

        palettes produced inside the working copy in GIMP, the

        application used to manipulate images).

    </para>

    <para>

        This final preparation stuff is automated by the

        <function>prepare</function> functionality of the

        <command>centos-art.sh</command> script, as described in 

        linkend="scripts-bash-prepare" />. Execute it right now,

        to be sure your workstation and your working copy are both

        ready to be used.

    </para>

    </sect2>

</sect1>