Goals
-----

This section exists to organize files related to centos-art.sh script prepare functionality.  The prepare functionality of centos-art.sh script helps you to prepare the workstation configuration you are planning to use as host for your working copy of CentOS Artwork Repository.

Description
-----------

The first time you download CentOS Artwork Repository you need to configure your workstation in order to use centos-art.sh script.  These preliminar configurations are based mainly on auxiliar RPM packages installation, symbolic links creations, and environment variables definitions.  The prepare functionality of centos-art.sh script guides you through this preliminar configuration process.

If this is the first time you run centos-art.sh script, the appropriate way to use its prepare functionality is not using the centos-art.sh script directly, but the absolute path to centos-art.sh script instead (i.e., ~/artwork/trunk/Scripts/Bash/centos-art.sh).  This is necessary because centos-art symbolic link, under ~/bin/ directory, has not been created yet.

Packages
........

Installation of auxiliar RPM packages provides the software required to manipulate files inside the repository (e.g., image files, documentation files, translation files, script files, etc.). Most of RPM packages centos-art.sh script uses are shipped with CentOS distribution, and can be installed from CentOS base repository. The only exception is inkscape, the package we use to manipulate SVG files.  The inkscape package is not inside CentOS distribution so it needs to be installed from third party repositories.

     Note Configuration of third party repositories inside CentOS distribution is described in CentOS wiki, specifically in the following URL: http://wiki.centos.org/AdditionalResources/Repositories

Before installing packages, the centos-art.sh script uses sudo to request root privileges to execute yum installation functionality.  If your user isn't defined as a privileged user---at least to run yum commands--- inside /etc/sudoers configuration file, you will not be able to perform package installation tasks as set in centos-art.sh script prepare functionality.

Setting sudo privileges to users is an administrative task you have to do by yourself. If you don't have experience with sudo command, please read its man page running the command: man sudo. This reading will be very useful, and with some practice, you will be able to configure your users to have sudo privileges.

Links
.....

Creation of symbolic links helps us to alternate between different implementations of centos-art.sh script-line (e.g., centos-art.sh, for Bash implementation; centos-art.py, for Python implementation; centos-art.pl, for Perl implementation; and so on for other implementations). The centos-art.sh script-line definition takes place inside your personal binary (~/bin/) directory in order to make the script implementation ---the one that centos-art links to--- available to PATH environment variable.

Creation of symbolic links helps us to reuse components from repository working copy. For example, color information files maintained inside your working copy must never be duplicated inside program-specific configuration directories that uses them in your workstation (e.g., Gimp, Inkscape, etc.).  Instead, a symbolic link must be created for each one of them, from program-specific configuration directories to files in the working copy.  In this configuration, when someone commits changes to color information files up to central repository, they---the changes committed--- will be immediatly available to your programs the next time you update your working copy ---the place inside your workstation those color information files are stored---.

Creation of symbolic links helps us to make centos-art.sh script functionalities available outside trunk/ repository directory structure, but at its same level in repository tree. This is useful if you need to use the ``render'' functionality of centos-art.sh under branches/ repository directory structure as you usually do inside trunk/ repository directory structure. As consequence of this configuration, automation scripts cannot be branched under branches/Scripts directory structure.

Environment variables
.....................

Definition of environemnt variables helps us to set default values to our user session life. The user session environment variable defintion takes place in the user's ~/.bash_profile file.  The prepare functionality of centos-art.sh script doesn't modify your ~/.bash_profile file.

The prepare functionality of centos-art.sh script evaluates the following environment variables:

EDITOR
     Default text editor.

     The centos-art.sh script uses default text EDITOR to edit pre-commit subversion messages, translation files, configuration files, script files, and similar text-based files.

     If EDITOR environment variable is not set, centos-art.sh script uses /usr/bin/vim as default text editor. Otherwise, the following values are recognized by centos-art.sh script:

       * /usr/bin/vim

       * /usr/bin/emacs

       * /usr/bin/nano

     If no one of these values is set in EDITOR environment variable, centos-art.sh uses /usr/bin/vim text editor by default.

TEXTDOMAIN

     Default domain used to retrieve translated messages.  This variable is set in initFunctions.sh and shouldn't be changed.

TEXTDOMAINDIR

     Default directory used to retrieve translated messages.  This variable is set in initFunctions.sh and shouldn't be changed.

LANG

     Default locale information.

     This variable is initially set in the configuration process of CentOS distribution installer (i.e., Anaconda), specifically in the Language step; or once installed using the system-config-language tool.

     The centos-art.sh script uses the LANG environment variable to know in which language the script messages are printed out.

TZ

     Default time zone representation.

     This variable is initially set in the configuration process of CentOS distribution installer (i.e., Anaconda), specifically in the Date and time step; or once installed using the system-config-date tool.

     The centos-art.sh script doesn't use the TZ environment variable information at all. Instead, this variable is used by the system shell to show the time information according to your phisical location on planet Earth.

     Inside your computer, the time information is firstly set in the BIOS clock (which may need correction), and later in the configuration process of CentOS distribution installer (or later, by any of the related configuration tools inside CentOS distribution).  Generally, setting time information is a straight-forward task and configuration tools available do cover most relevant location. However, if you need a time precision not provided by the configuration tools available inside CentOS distribution then, using TZ variable may be necessary.

          Convenction In order to keep changes syncronized between central repository and its working copies: configure both repository server and workstations (i.e., the place where each working copy is set on) to use Coordinated Universal Time (UTC) as base time representation.  Later, correct the time information for your specific location using time zone correction.

     The format of TZ environment variable is described in tzset(3) manual page.

Shell Script Files
..................

The shell functionality of centos-art.sh script helps you to maintain bash scripts inside repository. For example, suppose you've created many functionalities for centos-art.sh script, and you want to use a common copyright and license note for consistency in all your script files. If you have a bunch of files, doing this one by one wouldn't be a big deal. In contrast, if the amount of files grows, updating the copyright and license note for all of them would be a task rather tedious. The shell functionality exists to solve maintainance tasks just as the one previously mentioned.

When you use shell functionality to update copyright inside script files, it is required that your script files contain (at least) the following top commentary structure:

 1| #!/bin/bash
 2| #
 3| # doSomething.sh -- The function description goes here.
 4| #
 5| # Copyright
 6| #
 7| # ...
 8| #
 9| # ----------------------------------------------------------------------
10| # $Id$
11| # ----------------------------------------------------------------------
12|
13| function doSomething {
14|
15| }

Relevant lines in the above structure are lines from 5 to 9. Everything else in the file is left immutable.

When you are updating copyright through shell functionality,  the centos-art.sh script replaces everything in-between line 5 ---the first one matching ^# Copyright .+$ string--- and line 9---the first long dash separator matching ^# -+$--- with the content of copyright template instance.

     Caution Be sure to add the long dash separator that matches ^# -+$ regular expression before the function definition. Otherwise, if the Copyright line is present but no long dash separator exists, centos-art.sh will remove anything in-between the Copyright line and the end of file. This way you may lost your function definitions entirely.

The copyright template instance is created from one copyright template stored in the Config/tpl_forCopyright.sed file.  The template instance is created once, and later removed when no longer needed. At this moment, when template instance is created, the centos-art.sh script takes advantage of automation in order to set copyright full name and date dynamically.

When you use shell functionality to update copyright, the first thing shell functionality does is requesting copyright information to user, and later, if values were left empty (i.e., no value was typed before pressing RET key), the shell functionality uses its own default values.

When shell functionality uses its own default values, the final copyright note looks like the following:

 1| #!/bin/bash
 2| #
 3| # doSomthing.sh -- The function description goes here.
 4| #
 5| # Copyright (C) 2003, 2010 The CentOS Project
 6| #
 7| # This program is free software; you can redistribute it and/or modify
 8| # it under the terms of the GNU General Public License as published by
 9| # the Free Software Foundation; either version 2 of the License, or
10| # (at your option) any later version.
11| #
12| # This program is distributed in the hope that it will be useful, but
13| # WITHOUT ANY WARRANTY; without even the implied warranty of
14| # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15| # General Public License for more details.
16| #
17| # You should have received a copy of the GNU General Public License
18| # along with this program; if not, write to the Free Software
19| # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
20| # USA.
21| #
22| # ----------------------------------------------------------------------
23| # $Id$
24| # ----------------------------------------------------------------------
25|
26| function doSomething {
27|
28| }

Relevant lines in the above structure are lines from 5 to 22.  Pay attention how the copyright line was built, and how the license was added into the top comment where previously was just three dots. Everything else in the file was left immutable.

To change copyright information (i.e., full name or year information), run the shell functionality over the root directory containing the script files you want to update copyright in and enter the appropriate information when it be requested. You can run the shell functionality as many times as you need to.

To change copyright license (i.e., the text in-between lines 7 and 20), you need to edit the Config/tpl_forCopyright.sed file, set the appropriate information, and run the shell functionality once again for changes to take effect over the files you specify.

     Important The centos-art.sh script is released as:

     GNU GENERAL PUBLIC LICENSE
     Version 2, June 1991

     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
                              675 Mass Ave, Cambridge, MA 02139, USA

     Do not change the license information under which centos-art.sh script is released. Instead, if you think a different license must be used, please share your reasons at centos-devel@centos-art.sh mailing list.

     See file trunk/Scripts/COPYING (file:///home/centos/artwork/trunk/Scripts/COPYING), for a complete license description.

SVG Files
.........

The svg functionality of centos-art.sh script helps you to maintain scalable vector graphics (SVG) inside repository. For example, suppose you've been working in CentOS default design models under trunk/Identity/Themes/Models/, and you want to set common metadata to all of them, and later remove all unused SVG defintions from *.svg files. Doing so file by file may be a tedious task, so the centos-art.sh script provides the svg functionality to aid you maintain such actions.

The metadata used is defined by Inkscape 0.46 using the SVG standard markup. The centos-art.sh script replaces everything in-between <metadata and </metadata> tags with a predefined metadata template we've set for this purpose.

The metadata template was created using the metadata information of a file which, using Inkscape 0.46, all metadata fields were set. This created a complete markup representation of how SVG metadata would look like. Later, we replaced every single static value with a translation marker in the form =SOMETEXT=, where SOMETEXT is the name of its main opening tag. Later, we transform the metadata template into a sed replacement set of commads escaping new lines at the end of each line.

With metadata template in place, the centos-art.sh script uses it to create a metadata template instance for the file being processed currently.  The metadata template instance contains the metadata portion of sed replacement commands with translation markers already traduced.  In this action, instance creation, is where we take advantage of automation and generate metadata values like title, date, keywords, source, identifier, and relation dynamically, based on the file path centos-art.sh script is currently creating metadata information for.

With metadata template instance in place, the centos-art.sh script uses it to replace real values inside all .svg files under the current location you're running the centos-art.sh script on.  Default behaviour is to ask user to enter each metadatum required, one by one. If user leaves metadatum empty, by pressing RET key, centos-art.sh uses its default value.

Many of the no-longer-used gradients, patterns, and markers (more precisely, those which you edited manually) remain in the corresponding palettes and can be reused for new objects. However if you want to optimize your document, use the Vacuum Defs command in File menu. It will remove any gradients, patterns, or markers which are not used by anything in the document, making the file smaller.

If you have one or two couple of files, removing unused definitions using the graphical interface may be enough to you.  In contrast, if you have dozens or even houndreds of scalable vector graphics files to maintain it is not a fun task to use the graphical interface to remove unused definitions editing those files one by one.

To remove unused definitions from several scalable vector graphics files, the centos-art.sh script uses Inkscape command-line interface, specifically with the --vaccum-defs option.

XHTML Files
...........

Usage
-----

centos-art prepare --packages

     Verify required packages your workstation needs in order to run the centos-art.sh script correctly.  If there are missing packages, the centos-art.sh script asks you to confirm their installation. When installing packages, the centos-art.sh script uses the yum application in order to achieve the task.

     In case all packages required by centos-art.sh script are already installed in your workstation, the message The required packages are already installed. is output for you to know.

centos-art prepare --links

     Verify required links your workstation needs in order to run the centos-art command correctly.  If any required link is missing, the centos-art.sh script asks you to confirm their installation. To install required links, the centos-art.sh script uses the ln command.

     In case all links required by centos-art.sh script are already created in your workstation, the message The required links are already installed. is output for you to know.

     In case a regular file exists with the same name of a required link, the centos-art.sh script outputs the Already exists as regular file. message when listing required links that will be installed. Of course, as there is already a regular file where must be a link, no link is created. In such cases the centos-art.sh script will fall into a continue installation request for that missing link.  To end this continue request you can answer No, or remove the existent regular file to let centos-art.sh script install the link on its place.

centos-art prepare --environment
centos-art prepare --environment --filter='regex'

     Output a brief description of environment variables used by centos-art.sh script.

     If --filter option is provided, output is reduced as defined in the regex regular expression value. If --filter option is specified but regex value is not, the centos-art.sh script outputs information as if --filter option had not been provided at all.

See also
--------