The CentOS Artwork Repository is supported by Subversion

(@url{http://subversion.tigris.org/}), a version control system which

allows you to keep old versions of files and directories (usually

source code), keep a log of who, when, and why changes occurred, etc.,

like CVS, RCS or SCCS.  

When using Subversion there is one @emph{source repository} and many

@emph{working copies} of that source repository. The working copies

are independent one another, can be distributed all around the world

and provide a local place for designers, documentors, translators and

programmers to perform their works in a descentralized way.  The

source repository, on the other hand, provides a central place for all

independent working copies to interchange data and provides the

information required to permit extracting previous versions of files

at any time.

@subsection Repository policy

The CentOS Artwork Repository is a collaborative tool that anyone can

have access to. However, changing that tool in any form is something

that should be requested in @email{centos-devel@@centos.org} mailing

list.  Generally, people download working copies from CentOS Artwork

Repository, study the repository organization, make some changes in

their working copies, make some tests to verify such changes do work

the way expected and finally request access to commit them up to the

CentOS Artwork Repository (i.e., the source repository) for others to

benefit from them.

Once you've received access to commit your changes, there is no need

for you to request permission again to commit other changes from your

working copy to CentOS Artwork Repository as long as you behave as a

@emph{good community citizen}.

As a good community citizen one understand of a person who respects

the work already done for others and share ideas with authors before

changing relevant parts of their work, specially in situations when

the access required to realize the changes has been granted already.

Of course, there is a time when conversation has taken place, the

paths has been traced and changing the work is so obvious that there

is no need for you to talk about it; that's because you already did,

you already built the trust to keep going. Anyway, the mailing list

mentioned above is available for sharing ideas in a way that good

relationship between community citizens could be constantly balanced.

The relationship between community citizens is monitored by repository

administrators. Repository administrators are responsible of granting

everything goes the way it needs to go in order for the CentOS Artwork

Repository to comply its mission which is: to provide a colaborative

tool for The CentOS Community where The CentOS Project Corporate

Identity is built and maintained from The CentOS Community itself.

It is also important to remember that all source files inside CentOS

Artwork Repository should comply the terms of GNU General Public

License in order for them to remain inside the repository. See file

@url{file:///home/centos/artwork/trunk/Scripts/COPYING,trunk/Scripts/COPYING},

for a complete license description.

@subsection Repository organization 

The CentOS Artwork Repository uses a @file{trunk}, @file{branches},

and @file{tags} organization.  

@table @file

@item trunk

The @file{trunk} directory organizes the main development line of

CentOS Artwork Repository. @xref{Directories trunk}, for more

information.

@item branches

The @file{branches} directory oranizes intermediate development lines

taken from the main development line.  @xref{Directories branches},

for more information.

@item tags

The @file{tags} directory organizes frozen development lines taken

either from the main or the intermediate lines of development.

@xref{Directories tags}, for more information.

@end table

@subsection Repository file names

Inside the CentOS Artwork Repository, file names are all written in

lowercase (e.g., @samp{01-welcome.png}, @samp{splash.png},

@samp{anaconda_header.png}, etc.) and directory names are all written

capitalized (e.g., @samp{Identity}, @samp{Themes}, @samp{Motifs},

@samp{TreeFlower}, etc.).

@subsection Repository work lines

Inside CentOS Artwork Repository there are four major work lines of

production which are: @emph{graphic design}, @emph{documentation},

@emph{localization} and @emph{automation}.  These work lines describe

different areas of content production. Content production inside these

specific areas may vary as much as persons be working on them.

Producing content in too many different ways may result innapropriate

in a collaborative environment like CentOS Artwork Repository where

content produced in one area depends somehow from content produced in

another different area. So, a @emph{content production standard} is

required.

@subsubsection Graphic design

The graphic design work line exists to cover brand design, typography

design and themes design mainly. Additionally, some auxiliar areas

like icon design, illustration design (for documentation mainly),

brushes design, patterns designs and palettes of colors are also

included here for completeness.

Inside CentOS Artwork Repository graphic design is performed through

Inkscape (@url{http://www.inkscape.org/}) and GIMP

(@url{http://www.gimp.org/}).  The Inkscape tool is used to create and

manipulate scalable vector graphics and export them to PNG format; it

also provides a command-line interface that we use to perform massive

exportation from SVG files to PNG files in automation scripts. On the

other hand, GIMP is used to create and manipulate rastered images,

create brushes, patterns and palettes of colors.

@quotation

@strong{Tip} Combine both Inkscape and GIMP specific functionalities

and possibilities to produce very beautiful images.

@end quotation

The CentOS Project Corporate Visual Identity is made of different

visual manifestations (e.g., Distributions, Web sites, Stationery,

etc.).  Visual manifestations implement the corporate identity

concepts by mean of images.  To produce these images, we decompose

image production in @emph{design models} and @emph{artistic motifs}.

Design models provide the structural information of images (i.e.,

dimension, position of common elements in the visible area,

translation markers, etc.) and they are generally produced as scalable

vector graphics to take advantage of SVG standard, an XML-based

standard which describe scalable vector graphics. 

Artistic motifs provide the visual style (i.e., the background

information, the look and feel) some design models need to complete

the final image produced by automation scripts. Artistic motifs are

generally produced as rastered images.

The result produced from combining one design model with one artistic

motif is what we know as a @emph{theme}. Inside themes directory

structure (@pxref{Directories trunk Identity Themes}), you can find

several design models and several artistic motifs independently one

another that can be albitrarily combined through @emph{theme

rendition}, a flexible way to produce images for different visual

manifestations in very specific visual styles. Inside themes directory

structure, theme rendition is performed in

@file{trunk/Identity/Themes/Motifs} directory structure, the required

design models are taken from @file{trunk/Identity/Themes/Models}

directory structure and the action itself is controlled by the

@code{render} functionality of @command{centos-art.sh} script.

In addition to theme rendition you can find @emph{direct rendition},

too. Direct rendition is another way of image production where there

is no artistic motif at all but design models only. Direct rendition

is very useful to produce simple content that doesn't are in need of

specific background information. Some of these contents are brands,

icons and illustrations.  Direct rendition is performed in

@file{trunk/Identity/Images}, the required design models are taken

from @file{trunk/Identity/Models} directory structure and the action

itself is controlled by the @code{render} functionality of

@command{centos-art.sh} script.

@xref{Directories trunk Identity}, for more information about The

CentOS Corporate Identity and how graphic design fits on it.

@subsubsection Documentation

The documentation work line exists to describe what each directory

inside the CentOS Artwork Repository is for, the conceptual ideas

behind them and, if possible, how automation scripts make use of them.

The CentOS Artwork Repository documentation is supported by Texinfo, a

documentation system that uses a single source file to produce both

online information and printed output. 

The repository documentation is organized under @file{trunk/Manual}

directory structure and uses the repository directories as reference.

Each directory structure in the repository has a documentation entry

associated in the documentation manual.  Directory documentation

entries are stored under @file{trunk/Manual/Directories} directory

structure and the action itself is controlled by the @code{help}

functionality of @command{centos-art.sh} script.  

The @code{help} functionality let you create, edit and delete

documentation entries in a way that you don't need to take care of

updating menus, nodes and cross reference information inside the

manual structure; the functionality takes care of it for you.

However, if you need to write repository documentation that have

nothing to do with repository directories (e.g., Preface, Introduction

and similar) you need to do it manually, there is no functionality to

automate such process yet.

@xref{Directories trunk Manual}, for more information on

documentation.

@subsubsection Localization

The localization work line exists to provide the translation messages

required to produce content in different languages. Translation

messages inside the repository are stored as portable objects (e.g.,

.po, .pot) and machine objects (.mo) under @file{trunk/Locales}

directory structure.

The procedure used to localize content is taken from @command{gettext}

standard specification.  Basically, translatable strings are retrived

from source files (e.g., Bash scripts, SVG, XHTML, XML, etc.) in order

to create portable objects and machine objects for them.  These

portable objects are editable files that contain the information used

by translators to do their work. On the other hand, machine objects

are produced to be machine-redable only, as its name implies, and are

produced from portable objects.

Since @command{gettext} needs to extract translatable strings form

source files in order to let translators to localize them, we are

limitted to use source files supported by @command{gettext} program.

This is not a limitation at all since @command{gettext} supports most

popular programming laguages (e.g., C, C++, Java, Bash, Python, Perl,

PHP and GNU Awk just to mention a few ones. Nevertheless, formats like

SVG, XHTML and Docbook don't figure as supported formats in the list

of @command{gettext} supported source files.

To translate XML based source files like SVG, XHTML and Docbook we use

the @command{xml2po} program instead. The @command{xml2po} comes with

the @file{gnome-doc-utils} package and retrives translatable strings

from one XML file which are used to produce one portable object that

has the same format @command{gettext} portable objects have.  With the

portable object in place, we use @command{xml2po} again to create the

final translated XML, just with the same definition of the source file

where translatable strings were taken from (e.g., if we extract

translatable strings from a SVG file, as result we get the same SVG

file but with translatable strings already localized ---obviously, for

this to happen translators need to localize translatable strings

inside the portable object first, localization won't appear as art of

magic---).  When using @command{xml2po}, the machine object is used as

temporal file to produce the final translated XML file.

@quotation

@strong{Tip} If you want to have your content localized inside CentOS

Artwork Repository be sure to use source files supported either by

@command{gettext} or @command{xml2po} programs.

@end quotation

@xref{Directories trunk Locales}, for more information.

@subsubsection Automation

The automation work line exists to standardize content production in

CentOS Artwork Repository. There is no need to type several tasks,

time after time, if they can be programmed into just one script that

groups them all and then execute the script instead of all individual

tasks.

The automation work line takes place under @file{trunk/Scripts}

directory structure. Here is developed the @command{centos-art.sh}

script, a bash script specially designed to automate most frequent

tasks (e.g., rendition, documentation and localization) inside the

repository.  Basically, the @command{centos-art.sh} script is divided

in several functionalities independent one another that perform

specific tasks and relaying on repository organization to work as

expected.

@quotation

@strong{Tip} If you need to improve the way content is produced, look

inside automation scripts and make your improvement there for everyone

to benefit.

@end quotation

@xref{Directories trunk Scripts}, for more information on automation.

@subsection Connection between directories

In order to produce content in CentOS Artwork Repository, it is

required that all work lines be connected somehow.  This is the way

automation scripts can know where to retrive the information they need

to work with (e.g., design model, translation messages, output

location, etc.).  We build this kind of connection using two path

constructions named @emph{master paths} and @emph{auxiliar paths}.

The master path points only to directories that contain the source

files (e.g., SVG files) required to produce base content (e.g., PNG

files) through automation scripts.  Each master path inside the

repository may have several auxiliar paths associated, but auxiliar

paths can only have one master path associated.

The auxiliar paths can point either to directories or files. When an

auxiliar path points to a directory, that directory contains

information that modifies somehow the content produced from master

paths (e.g., through translation messages) or provides the output

information required to know where to store the content produced from

master path.  When an auxiliar path points to a file, that file has no

other purpose but document the master path it refers to.

The relation between auxiliar paths and master paths is realized using

one unique master path and path information from repository second

level directory structure.  Generally, the master path is used like a

path identifier and the second level directory structure taken from

the repository organization is considered the common part where the

path identifier is append in. For example, consider we want to know

what the auxiliar path are for @file{trunk/Identity/Models/Brands}

master path.

@float Figure, fig:Introduction/repo-convenctions:1

@verbatim

-----+---------------+----------------------------+------+-----------

Path | Suffix        | Identifier                 |Prefix| Type 

-----+---------------+----------------------------+------+-----------

  A  |               |trunk/Identity/Models/Brands|      | Directory 

-----+---------------+----------------------------+------+-----------

  B  |  trunk/Manual/|trunk/Identity/Models/Brands|.texi | File      

-----+---------------+----------------------------+------+-----------

  C  | trunk/Locales/|trunk/Identity/Models/Brands|      | Directory 

-----+---------------+----------------------------+------+-----------

  D  |               |trunk/Identity/Images/Brands|      | Directory 

-----+---------------+----------------------------+------+-----------

  E  | trunk/Locales/|trunk/Identity/Images/Brands|.texi | File      

-----+---------------+----------------------------+------+-----------

 A = Master path.

 B = Auxiliar path to documentation entry.

 C = Auxiliar path to translation messages.

 D = Auxiliar path to final content output.

 E = Auxiliar path to documentation entry.

@end verbatim

@caption{Base path construction.}

@end float

The configuration described above is used by direct rendition and can

be used as reference to organize other components that are equally

produced through direct rendition in the repository. To create new

components that make use of direct rendition inside the repository,

change just the component name used above (e.g., @file{Brands}) to

that one you want to add/create/use without changing the path

structure around it (e.g., suffix and prefix information).

The file organization used by theme rendition is extends direct

rendition by separating design models from background information.  As

a mnemotechnic resource helpful to better understand this

configuration, you can consider it as two independent lists, one of

design models and one of artistic motifs, which are arbitrary combined

between themselves in order to render images in specific ways. The

possibilities of this configuration are endless and let us describe

visual manifestations with a very high level of details.  For example,

consider the organization used to produce Anaconda images; for CentOS

distribution major release 5; using @file{Default} design models and

version @file{3} of @file{Flame} artistic motif:

@float Figure, fig:Introduction/repo-convenctions:2

@verbatim

-----+---------------+------------------------------------------------------+------+-----------

Path | Suffix        | Identifier                                           |Prefix| Type 

-----+---------------+------------------------------------------------------+------+-----------

  A  |               |trunk/Identity/Themes/Models/Default/Distro/5/Anaconda|      | Directory 

-----+---------------+------------------------------------------------------+------+-----------

  B  |  trunk/Manual/|trunk/Identity/Themes/Models/Default/Distro/5/Anaconda|.texi | File      

-----+---------------+------------------------------------------------------+------+-----------

  C  | trunk/Locales/|trunk/Identity/Themes/Models/Default/Distro/5/Anaconda|      | Directory 

-----+---------------+------------------------------------------------------+------+-----------

  D  |               |trunk/Identity/Themes/Motifs/Flame/3/Distro/5/Anaconda|      | Directory 

-----+---------------+------------------------------------------------------+------+-----------

  E  | trunk/Locales/|trunk/Identity/Themes/Motifs/Flame/3/Distro/5/Anaconda|.texi | File      

-----+---------------+------------------------------------------------------+------+-----------

 A = Master path.

 B = Auxiliar path to documentation entry.

 C = Auxiliar path to translation messages.

 D = Auxiliar path to final content output.

 E = Auxiliar path to documentation entry.

@end verbatim

@caption{Base path construction extended.}

@end float

The Anaconda component is part of CentOS Distribution visual

manifestation. Inside CentOS Distribution visual manifestation there

are other components like Syslinux, Grub, Rhgb, Gdm, Kdm, Gsplash and

Ksplash that share a similar file organization to that described above

for Anaconda component. The way each of these components is produced

is described in their own documentation entry.

When one master path is changed, it is required that all related

auxiliar path to it, change too. This is required in order for master

paths to retain their relation with their auxiliar paths. This way,

automation script are able to know where to retrive translation

messages, where to store final output images and where to look for

documentation. If relation between master paths and auxiliar paths is

lost, there is no way for automation scripts to know where to retrive

the information required to automate tasks.

The auxiliar paths should never be modified under any reason but to

satisfy the relationship with the master path.  Liberal change of

auxiliar paths may suppress the conceptual idea they were initially

created for; and certainly, things may stop working the way they

should.

@subsection Syncronizing path information

The master and auxiliar paths are useful to keep repository organized

but introduce some complications when we work with files that use

master path information as reference to build structural information.

In such cases, when a file is created, duplicated, deleted or removed,

we use the master path information to update documentation structure,

update inclusions, menus, nodes and cross reference information as

well. To see the kind of complication we are talking about, consider

what would happen if one master path is changed once it already has a

documentation entry inside the documentation structure. What would

happen with document structure definitions like file inclusion, menus,

nodes and cross references?

Syncronizing path information is the action we use to keep all path

information up to date in the repository. This action implies both

@emph{file movement} and @emph{file content replacement} in this very

specific order. File movement is the action we use to duplicate,

delete and rename files and directories in the repository.  File

content replacement is the action we use to replace content, path

information in this case, inside files in the repository.

The order followed to syncronize path information is relevant because

the versioned nature of the files we are working with. We don't change

path information first in files because that implies a repository

change we need to commit first before duplicate, delete or rename the

file where that change takes place. However, if we first perform the

file movement, it is possible to commit both file movement and file

content replacement changes as if they were just one change. In this

case the file content replacement takes palce in the target location

of file that have been duplicated or renamed, not the one use as

source location. This configuration is specially useful when files are

renamed (i.e., source file is copied to target location and then

removed from repository).

@quotation

@strong{Warning} There is no support for URLs actions inside

@command{centos-art.sh} script.  The @command{centos-art.sh} script is

designed to work with local files inside the working copy only. If you

need to perform URL actions directly, use Subversion commands instead.

@end quotation

@subsection Extending repository organization

Occasionly, you may find that new components of The CentOS Project

Corporate Identity need to be added to the repository in order to work

them out. If that is the case, the first question we need to ask

ourselves, before start to create directories blindly all over, is:

@emph{What is the right place to store it?}

The best place to find answers is in The CentOS Community (see page

@url{http://wiki.centos.org/GettingHelp}), but going there with hands

empty is not good idea. It may give the impression you don't really

care about. Instead, consider the following suggestions to find your

own comprehension in order to make your own propositions based on it.

When extending respository structure it is very useful to bear in mind

The CentOS Project Corporate Identity Structure (@pxref{Directories

trunk Identity}) The CentOS Mission and The CentOS Release Schema. The

rest is just matter of choosing appropriate names. It is also worth to

know that each directory in the repository responds to a conceptual

idea that justifies its existence.

To build a directory structure, you need to define the conceptual idea

first and later create the directory. There are some locations inside

the repository that already define some concepts you probably want to

reuse. For example, @file{trunk/Identity/Themes/Motifs} to store theme

artistic motifs, @file{trunk/Identity/Themes/Models} to store theme

design models, @file{trunk/Manual} to store documentation files,

@file{trunk/Locales} to store translation messages,

@file{trunk/Scripts} to store automation scripts and so on.

To illustrate this desition process let's consider the

@file{trunk/Identity/Themes/Motifs/TreeFlower/3} directory structure

as example.  This directory can be read as: the theme development line

of version @file{3} of @file{TreeFlower} artistic motif. Additional,

we can identify that artistic motifs are part of themes as well as

themes are part of The CentOS Project Corporate Identity. These

concepts are better described independently in each documentation

entry related to the directory structure as it is respectively shown

in the list of commands bellow.

@verbatim

centos-art help --read turnk

centos-art help --read turnk/Identity

centos-art help --read turnk/Identity/Themes

centos-art help --read turnk/Identity/Themes/Motifs

centos-art help --read turnk/Identity/Themes/Motifs/TreeFlower

centos-art help --read turnk/Identity/Themes/Motifs/TreeFlower/3

@end verbatim

The concepts behind other location can be found in the same way

described above, just change the path information used above to the

one you are trying to know concepts for.