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

    <title>Configuring Your Workstation</title>

    <para>
        Once your worstation has been installed, it is time for you to
        configure it. The configuration of your workstation consists
        on defining your workplace, download a working copy from
        &TCAR; and finally, run the <function>prepare</function>
        functionality of <command>centos-art.sh</command> script to
        install/update the software needed, render images, create
        links, and anything else needed.
    </para>

    <sect2 id="repo-ws-config-wp">
    <title>Define Your Workplace</title>
    <para>
        Once you've installed the workstation and it is up and
        running, you need to register the user name you'll use for
        working. 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 <quote>root</quote>
        superuser for doing so. 
    </para>

    <caution>
    <para>
        Do not use the <quote>root</quote> username for regular
        tasks inside your working copy of &TCAR;.  This is dangerous
        and might provoke unreversable damages to your workstation.
    </para>
    </caution>

    <para>
        When you've registered your user name in the workstation, it
        provides an identifier for you to open a user's session in the
        workstation and a place to store the information you produce,
        as well. This place is known as your home directory and is
        unique for each user registered in the workstation. For
        example, if you register the user name john in your
        workstation, your home directory would be located at <filename
        class="directory">/home/john/</filename>.
    </para>
    
    <para>
        At this point it is important to define where to download the
        working copy of &TCAR; inside your home directory.  This
        desition deserves special attention and should be implemented
        carefully in order to grant a standard environment that can be
        distributed.  Let's see some alternatives.
    </para>

    <sect3>
    <title>Different Absolute Paths</title>
    <para>
        Consider that you store your working copy under <filename
        class="directory">/home/john/Projects/artwork/</filename> and
        I store mine under <filename
        class="directory">/home/al/Projects/artwork/</filename>, we'll
        end up refering the same files inside our working copies
        through different absolute paths.  This alternative generates
        a contradiction when files which hold path information inside
        are committed up to the central repository from different
        working copies. The contradiction comes from the question:
        which is the correct absolute path to use inside such files,
        yours or mine? (None of them is, of course.)
    </para>

    </sect3>

    <sect3 id="repo-ws-config-wp-OneUniqueAbsolutePath">
    <title>One Unique Absolute Path</title>
    <para>
        Another case would be that where you and I ourselves use one
        unique home directory (e.g., <filename
        class="directory">/home/centos/Projects/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 alternative might be not so good in
        situations where you and I have to share the same workstation.
        In such cases, 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>
    </sect3>

    <sect3>
    <title>Different Absolute Paths Through Dynamic Expansion</title>
    <para>
        Most of the absolute paths we use inside the working copy are
        made of two parts, one dynamic and one relative 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 a matter of
        organization.  What we need here is to find a way to expand
        variables inside files that don't support variable expansion.
        This alternative had worked rather fine 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>
    </sect3>

    </sect2>

    <sect2 id="repo-ws-config-wc">
    <title>Download Your Working Copy</title>

    <para>
        As convenction, to use the &TCAR;, you must register the user
        name <emphasis>centos</emphasis> in your workstation, do login
        with it, and download the working copy from the central
        repository using the following command:
    </para>

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

    <para>
        The first time you download the working copy it contains 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>

    </sect2>

    <sect2 id="repo-ws-config-sudoers">
    <title>Configure Administrative Tasks</title>

    <para>
        Most of the administrative tasks you need to perform in your
        working copy of &TCAR; are standardized inside the
        <function>prepare</function> functionality of
        <command>centos-art.sh</command> script. Inside
        <command>centos-art.sh</command>
        script, all administrative task are invoked trough the
        <command>sudo</command> command. Thus, in order for the
        <command>centos-art.sh</command> script to perform
        administrative tasks, you need to update the
        <command>sudo</command>'s configuration in a way that such
        administrative actions be allowed.
    </para>

    <para>
        At time of this writing the <command>centos-art.sh</command>
        script implements just one administrative task, that is
        package management.  Nevertheless, in the future, other
        administrative tasks might be included as well.
    </para>

    <para>
       To update the <command>sudo</command>'s configuration, execute
       the <command>visudo</command> command as <quote>root</quote>.
       Later, uncoment the <varname>Cmnd_Alias</varname> related to
       <quote>SOFTWARE</quote> and add a line for
       <quote>centos</quote> username allowing software commands. This
       configuration is illustrated in <xref
       linkend="repo-ws-config-sudoers-example" />.
    </para>

    <example id="repo-ws-config-sudoers-example">
    <title>The <filename>/etc/sudoers</filename> configuration file</title>
    <screenshot>
    <screeninfo><filename>/etc/sudoers</filename> configuration file</screeninfo>
    <mediaobject>
    <textobject>
<programlisting>
## Installation and management of software
Cmnd_Alias SOFTWARE = /bin/rpm, /usr/bin/up2date, /usr/bin/yum

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

## Allow the centos user to run installation and management of
## software anywhere.
centos  ALL=(ALL)       SOFTWARE
</programlisting>
    </textobject>
    </mediaobject>
    </screenshot>
    </example>
    
    </sect2>

    <sect2 id="repo-ws-config-runout">
    <title>Run Automation Tool</title>
    <para>
        Once you've created the <quote>centos</quote> username, logged
        in with it, downloaded a working copy from &TCAR; and
        configured the <command>sudo</command>'s configuration file,
        run the <function>prepare</function> functionality of
        <command>centos-art.sh</command> script to complete the
        configuration process using the following command:
    </para>

    <screen>/home/centos/Projects/artwork/trunk/Scripts/Bash/centos-art.sh prepare</screen>

    <para>
        To know more about the <function>prepare</function>
        functionality of <command>centos-art.sh</command> script, see
        <xref linkend="scripts-bash-prepare" />.
    </para>
    </sect2>

</sect1>