Blob Blame History Raw
<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 <filename
        class="directory">/home/john/artwork/</filename> and I store
        mine under <filename
        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? &mdash; 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., <filename
        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., <filename
        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 <filename
        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 <filename
        class="directory">/usr/bin/vim</filename> text editor, the one
        installed by default in &TCD;. 
    </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 &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.
    </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 &TCD; 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 &TCD; 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 <code>tzset(3)</code>
        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 <filename
        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 <xref
        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>