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

    <title>Configuring Your Workstation</title>

    <para>

        Once your workstation 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 

        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 could

        be distributed.  Let's see some alternatives.

    </para>

    <sect3>

    <title>Different absolute paths</title>

    <para>

        Consider that you store your working copy under 

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

        I store mine under 

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

        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

        <quote>centos</quote> 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>

    <sect3>

    <title>Different absolute paths, dynamic expansion, symbolic

    links, relative links, and environment variables</title>

    <para>

        With this solution it is possible to store working copies of

        &TCAR; on different locations inside the same workstation

        without lose relation between files. Here we use the

        TCAR_WORKDIR environment variable to set the location of the

        working copy inside the workstation. Later the centos-art.sh

        scripts uses this value as reference to determine where the

        working copy is. This value is also the one used for dynamic

        expansion inside design models and other similar files. In the

        case of web projects where different components are required

        to produce the final content, we create symbolic links between

        them and use relative paths so it is possible to reuse them

        and retain the relation between them in different contexts.

    </para>

    <para>

        For example, lets consider the organization of XHTML manuals

        rendered from DocBook source files. When you render a DocBook

        manual inside &TCAR; it creates XHTML files.  This XHTML files

        use images and common style sheets for better presentation.

        Both of these images and styles components live outside the

        XHTML structure so, in order to make them available

        relatively to the XHTML structure, we created symbolic links

        from the XHTML structure to the outside location where they

        are in. The creation of symbolic links takes place

        automatically when each DockBook manual is rendered through

        <command>centos-art.sh</command>, which uses the value of

        TCAR_WORKDIR environment variable as reference to determine

        the absolute path of the working copy.

    </para>

    <para>

        Bacause absolute paths are no longer stored inside permanent

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

        TCAR_WORKDIR environment variable to determine where the

        working copy is stored in the workstation, it should be safe

        to download working copies of &TCAR; anywhere in the

        workstation. One just have to be sure that the value of

        TCAR_WORKDIR environment variable does match the location of

        the working copy you are using.

    </para>

    </sect3>

    </sect2>

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

    <title>Download Your Working Copy</title>

    <para>

        In order to use &TCAR; you need to download a working copy

        from the central repository into your workstation.  To

        download such working copy use the following command:

    </para>

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

    <para>

        This command will create your working copy inside your home

        directory, specifically in a directory named 

        class="directory">artwork</filename>. Inside this directory

        you will find all the files you need to work with inside

        &TCAR;. If you want to have your working copy in a location

        different to that one shown above, see 

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

    </para>

    <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 to render them in order 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 through 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 (e.g.,

        installing themes locally from the working copy for testing

        purposes.).

    </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 your 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.

al      ALL=(ALL)       SOFTWARE

</programlisting>

    </textobject>

    </mediaobject>

    </screenshot>

    </example>

    </sect2>

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

    <title>Run Preparation Tool</title>

    <para>

        Once you've both downloaded a working copy from &TCAR; 

        and configured the <command>sudo</command>'s configuration

        file successfully, run the <function>prepare</function>

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

        complete the configuration process using the following

        command:

    </para>

    <screen>~/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>

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

    <title>Changing Your Working Copy Default Path</title>

    <para>

        By default your working copy should be store in your home

        directory, specifically in the location 

        class="directory">~/artwork</filename>. This location may not

        be the final location where you want to have your working copy

        in situations where you are working on several projects at the

        same time or you already have a define location to organize

        your projects inside your home directory. Thus, you may need

        to change the default location of your working copy to a more

        appropriate location.

    </para>

    <para>

        The default path to your working copy is controlled by the

        <envar>TCAR_WORKDIR</envar> environment variable. This

        variable is firstly defined in your personal profile after

        running the prepare functionality of

        <command>centos-art.sh</command> script. So, to change the

        path of your working copy correctly, do the following:

    </para>

    <orderedlist>

    <listitem>

    <para>

        Create the parent directory you will use to store your working

        copy. For example: 

        <screen>mkdir -p ~/Projects/CentOS</screen>

    </para>

    </listitem>

    <listitem>

    <para>

        Move the currently downloaded working copy from ~/artwork to

        your new location. For example: 

        <screen>mv ~/artwork ~/Projects/CentOS/</screen>

    </para>

    </listitem>

    <listitem>

    <para>

       Edit <filename>~/.bash_profile</filename> file to set the new

       location (without trailing slash) of your working copy as value

       of TCAR_WORKDIR environment variable. For example:

       <screen>TCAR_WORKDIR=${HOME}/Projects/CentOS/artwork</screen>

    </para>

    </listitem>

    <listitem>

    <para>

        Do log out from your active user's seesion and do log in again

        so the environment changes take effect. Or just update the

        current environment information by running the following

        command:

        <screen>. ~/.bash_profile</screen>

    </para>

    </listitem>

    <listitem>

    <para>

        Update internal links by running the following command:

        <screen>${TCAR_WORKDIR}/trunk/Scripts/Bash/centos-art.sh prepare --links</screen>

    </para>

    </listitem>

    </orderedlist>

    </sect2>

</sect1>