This section describes the organization of files and directories

inside the CentOS Artwork Repository, the names convenctions, how to

extend the current layout and the way content is produced, as well. 

The repository layout is used as standard backend for automation

scripts to work correctly. If repository layout changes unexpectedly,

automation scripts may get confuse themselves and stop doing what you

may expect from them to do.

As convenction, inside CentOS Artwork Repository, files and

directories related to CentOS corporate visual identity are organized

under three top level directories named: @file{trunk/},

@file{branches/}, and @file{tags/}. 

The @file{trunk/} directory (@pxref{Directories trunk}) organizes the main

development line of CentOS corporate visual identity. Inside

@file{trunk/} directory structure, the CentOS corporate visual

identity concepts are implemented using directories.  There is one

directory level for each relevant concept inside the repository. The

@file{trunk/} directory structure is mainly used to perform

development tasks related to CentOS corporate visual identity.

The @file{branches/} directory (@pxref{Directories branches}) oranizes

parallel development lines to @file{trunk/} directory. The

@file{branches/} directory is used to set points in time where

develpment lines are devided one from another taking separte and

idependent lives that share a common past from the point they were

devided on. The @file{branches/} directory is mainly used to perform

quality assurance tasks related to CentOS corporate visual identity.

The @file{tags/} directory (@pxref{Directories tags}) organizes parallel frozen

lines to @file{branches/} directory.  The parallel frozen lines are

immutable, nothing change inside them once they has been created.  The

@file{tags/} directory is mainly used to publish final releases of

CentOS corporate visual identity.

The CentOS Artwork Repository layout is firmly grounded on a

Subversion base.  Subversion (@url{http://subversion.tigris.org}) is 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.  Subversion keeps a

single copy of the master sources.  This copy  is called the source

``repository''; it contains all the information to permit extracting

previous versions of those files at any time.

@subsection Repository file names

Repository name convenctions are applied to files and directories

inside the repository layout. As convenction, file names are all

written in lowercase (@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.).

Repository name convenctions are implemented inside the

@code{cli_getRepoName} function of @file{centos-art.sh} script. With

@code{cli_getRepoName} function the amount of commands and

convenctions to remember are reduced and concentrated in just one

single place to look for fixes and improvements.

@subsection Work lines

Work lines describe different areas of content production inside

CentOS Artwork Repository. 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. To produce content in a syncronized but descentralized

way, it is required to define a content production standard for each

work line that everyone uses as reference to realize their work.

The standard way of producing content inside CentOS Artwork Repository

is implemented through @command{centos-art.sh} script and described in

@command{centos-art.sh} script related documentation entry

(@pxref{Directories trunk Scripts}).

Inside CentOS Artwork Repository, work lines are organized in

@emph{Graphic design}, @emph{Documentation}, @emph{Localization} and

@emph{Automation}.

@subsubsection Graphic design

This work line exists to cover brand design, typography design and

theme design. Additionally, some auxiliar areas like icon design,

illustration design for documentation, brushes design, pattern designs

and palettes with color definitions could be included here for

completeness.

Inside CentOS Artwork Repository, graphic design is performed through

Inkscape and GIMP program.  Inkscape is used create and manipulate

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

provides a command-line interface that we use to automate the

exportation process so you can perform massive exportation of SVG

files to PNG files. On the other hand, GIMP is used to create and

manipulate rastered images, create brushes, patterns and palettes of

colors.  Notice that each program provides very specific

functionalities and posibilities that when combined can let you

produce very beautiful images.

The CentOS Project Corporate Identity is made of several visual

manifestations.  These visual manifestations implement the Corporate

Identity by mean of images placed in key areas of their visual space.

To produce these images, we decompose image production in @emph{design

models} and @emph{artistic motifs}. Design models provide the image

structure (i.e., dimension, translation markers, common designs, etc.)

and are generally produced as scalable vector graphics generally. On

the other hand, artistic motifs provide the visual style (i.e., the

background information, the look and feel) and are generally produced

as rastered images.

Design models are created for each visual manifestation the CentOS

Project is made of. This way we describe the visual manifestation and

provide a template system for it where several artistic motifs can be

applied. Artistic motifs are created with design models in mind, not

the visual manifestation that design models are built for.

The result produced by 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, apart one another,

that can be albitrarily combined one another through @emph{theme

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

manifestations inside CentOS Artwork Repository. Inside themes

directory structure, theme rendition is performed in

@file{trunk/Identity/Themes/Motifs} directory structures and takes

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

structure.

In addition to theme rendition, you can find another way of image

production, a more direct way of image production where there is no

artistic motif at all, but design models only. Such configuration is

named @emph{direct rendition} and is very useful to produce simple

content that doesn't need specific background information (e.g., icons

and illustrations for documentation). Direct rendition takes place in

@file{trunk/Identity/Models} and @file{trunk/Identity/Images}

directory structures.

@xref{Directories trunk Identity}, for more information on graphic

design.

@subsubsection Documentation

This work line exists to describe what each directory structure inside

the CentOS Artwork Repository is for and how to produce content inside

them.

Documentation is supported by Texinfo, a documentation system that

uses a single source file to produce both online information and

printed output.

Documentation is organized in the same way of CentOS Artwork

Repository directory structure. In the CentOS Artwork Repository we

use directories to store conceptual ideas of The CentOS Project

Corporate Visual Identity.  This way, each directory in CentOS Artwork

Repository has its own documentation section to describe the related

conceptual ideas it is based on. Documentation entries related to

repository directory structure are organized in sections under

@emph{Repository Directories} chapter (@pxref{Directories}).

The file structure of documentation related to the repository

directory structures is stored under @file{trunk/Manual/Directories}

directory structure and controlled by the @code{help} functionality of

@command{centos-art.sh} script.  Using this functionality you can

create, edit and remove documentation for each directory structure

inside the repository; so 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 directory structure (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

This work line exists to localize corporate design and documentation

source files, so they can be produced in different languages.

Whatever content rendition you perform, sometimes you need to produce

content in different languages. Production of content in different

languages is known as localization or l10n for short.  Inside CentOS

Artwork Repository, content localization is performed using the

processes provided by @command{gettext} internationalization standard.

Basically, the @command{gettext} internationalization standard

consists on retriving translatable strings from source files and

creating Portable Objects and Machine Objects. Portable Objects

contain the information used by translators to do their work, they are

files that can be edited by any convenctional text editor like Vim,

Emacs or Nano. On the other hand, Machine Objects are produced to be

machine-redable 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, the types

of source files we use inside the repository are limitted to the file

types supported by @command{gettext} program. Most of the source files

supported by @command{gettext} are those from programming languages

like C, C++, Bash, Python and Perl just to mention a few ones from the

long list of supported formats. However, formats like SVG, XHTML and

Docbook don't figure as supported in the long list of

@command{gettext} supported source files. 

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

the @command{xml2po} program. This program comes with

@file{gnome-doc-utils} package and reads one XML based file to extract

translatable strings from it. As result it creates one Portable Object

that is use by @command{xml2po} itself to create a translated XML

based file 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 file is used just

temporally to produce the final translated XML based file.

@quotation

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

Artwork Repository be sure to use source files supported by

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

@end quotation

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

@subsubsection Automation

This work line exists to standardize content production inside CentOS

Artwork Repository. There is no need to repeat several tasks time

after time if they can be programmed in just one.  If you need to

improve the way content is produced, look inside automation scripts

and make your improvement there for every one to benefit.

So far, we've seen a conceptual view of how image production inside

CentOS Artwork Repository is performed, but how all this is

implemented, what is the practical view?

The practical view can be found through @command{centos-art.sh}

script, a bash script specially designed to automate most frequent

tasks inside CentOS Artwork Repository. The @command{centos-art.sh}

script is stored in @file{trunk/Scripts} directory structure and is

there where the main development for @command{centos-art.sh} script

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

in several functionalities that perform specific tasks inside the

repository. Such functionalities relay on repository organization to

work as expected. 

Maiking the @command{centos-art.sh} script to automate tasks is the

only possible work flow that I can think about right now. If you are a

programmer, take a functionality from @command{centos-art.sh} script,

study it, look how to improve it and share your ideas at

@email{centos-devel@@centos.org} mailing list or create your own new

functionalities and propose them as well.

@quotation 

@strong{Note} As default configuration, everyone is denied from

committing changes up to CentOS Artwork Repository. In order to gain

commit rights, you need to prove your interest in contributing and

maintaining that contribution.  Otherwise, if you only want to comment

your ideas, the @email{centos-devel@@centos.org} mailing list exists

for you to manifest yourself. This restrictions are necessary to

protect our work from spammers.

@end quotation

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

@subsection Connection between directories

In order to produce content correctly inside CentOS Artwork

Repository, it is required that all work lines be connected somehow.

This way it could be possible to know what design models and

translation messages to use in order to produce a specific content.

This directory connection between work lines takes place through one

@emph{master path} that may have several @emph{auxiliar paths}.

Master paths are those whose contain source files used to produce base

content and auxiliar paths provide the files used to modify the

production of such base content. For example, when images are produced

from source files, the directory structure that holds source files is

considered the master path and all other directory structures are

considered auxiliar paths. There are auxiliar paths to store images,

translation messages and documentation.

Auxiliar paths take their structure from one unique parent path.

Inside CentOS Artwork Repository, this unique parent path is under

@file{trunk/Identity} directory structure.  The @file{trunk/Identity}

location must be considered as a reference for whatever information

you plan to create inside the repository. For example, all the

possible paths related to brands component production, are:

@table @file

@item trunk/Identity/Models/Brands

This is the master path where source files used to produce brands are

stored in.

@item trunk/Locales/Identity/Models/Brands

This is the auxiliar path where translation messages used to produce

brands, if there is any at all, are stored in.

@item trunk/Manual/Directories/trunk/Locales/Identity/Models/Brands.texi

This is the auxiliar path where documentation about translation

messages, used to produce brands are stored in.

@item trunk/Identity/Images/Brands

This is the auxiliar path where output images produced as result of

rendition are stored in.

@item trunk/Manual/Directories/trunk/Identity/Models/Brands.texi

This is the auxiliar path where documentation about brand design is

stored in. This is, how brands are constructed, the color information,

the proportions, etc. Notice that it points to a regular file, not a

directory as other auxilar path use to do.

@item trunk/Manual/Directories/trunk/Identity/Images/Brands.texi

This is the auxiliar path where documentation about brand

implementation. This is, how the brand is applied and how it cannot be

applied in each different visual manifestation. Notice that it points

to a regular file, not a directory as other auxiliar path use to do.

@end table

The configuration described above for organizing brand component

inside the repository is the one used by direct rendition and can be

used as reference to organize other components inside the repository

that are produced through direct rendition too. Just change the

component name from brands to that one you want to add without

changing the path structure around it.

The file organization used by theme rendition, however, is a bit

different from that used by direct rendition. In theme rendition, both

master paths and auxiliar paths are built dynamically based on the

design model and the artistic motifs you specify at rendition time. As

a mnemotechnic resource, consider theme rendition as two independent

lists, one list of design models and one list of artistic motifs,

which are arbitrary combined among themselves in order to render

images. For example, consider the organization used to produce

Anaconda images to CentOS distribution major release 5 from Default

design model and Flame artistic motif:

@table @file

@item trunk/Identity/Themes/Models/Default/Distro/5/Anaconda

This directory contains source files used to produce Anaconda images

for CentOS distribution major release 5 using Default design models.

Here is where you, as graphic designers, define Default design models for

Anaconda images used in CentOS distribution major release 5.

The path to this directory is considered master because it contains

the most critical information (i.e., the information that can't be

absent) required to produce Anaconda images used inside CentOS

distribution major release 5.

@item trunk/Manual/Directories/trunk/Identity/Themes/Models/Default/Distro/5/Anaconda.texi

This file contains documentation, in Texinfo format, for Default

design models used to produce the Anaconda images used inside CentOS

distribution major release 5. 

Here is where you, as documentor, describe construction of Default

desing models used to produce the Anaconda images for CentOS

distribution major release 5. In this description you can include

image dimensions, color information, image location inside

distribution filesystem, image packaging and similar things.

The path to this file is considered auxiliar for

@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda} master

path because provides the description required to let everyone know

how to build Default design models used to produce Anaconda images

required by CentOS distribution major release 5.

@item trunk/Locales/Identity/Themes/Models/Default/Distro/5/Anaconda

This directory contains translation files, as @command{gettext}

portable objects, for Default design models used to produce the

Anaconda images used inside CentOS distribution major release 5. 

Here is where you, as translator, localize translatable strings

retrived in English language from Default design models used to

produce the Anaconda images of CentOS distribution major release 5 to

your own language. If no portable object is found here, content is

produced in English language.

The path to this directory is considered auxiliar for

@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda} master

path because provides the language-specific information required to

produce Anaconda Default design models in different languages.

@item trunk/Manual/Directories/trunk/Locales/Identity/Themes/Models/Default/Distro/5/Anaconda.texi

This file contains documentation, in Texinfo format, for translation

messages retrived from Default design models used to produce the

Anaconda images used inside CentOS distribution major release 5. 

Here is where you, as documentor, describe localization of Default

desing models used to produce the Anaconda images used in CentOS

distribution major release 5. In this description you can include

image dimensions, color information, image location inside

distribution filesystem, image packaging and similar things.

The path to this file is considered auxiliar for

@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda} master

path because provides the language-specific information required to

produce Anaconda Default design models in different languages.

Each master path has its own auxiliar path to store their specific

documentation and whatever the artistic motifs used to produce images

be is somthing irrelevant.

@item trunk/Identity/Themes/Motifs/Flame/3/Distro/5/Anaconda

This directory contains Anaconda final images produced from Anaconda

Default design models used by CentOS distribution major release 5 and

Flame 3 artistic motif. 

Here is where you, as packager, can find the images you need to

rebrand Anaconda in CentOS distribution major release 5.

The path to this directory is considered auxiliar for

@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda} master

path because it provides the final images produced from Anaconda

Default design models.

@item trunk/Manual/Directories/trunk/Identity/Themes/Motifs/Flame/3/Distro/5/Anaconda.texi

This directory should contain documentation about how to implement

Anaconda component in CentOS distribution major release 5 would be.

However, since all artistic motifs are produced based on one design

model (@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda},

in this case) we may end up duplicating the same documentation in all

artistic motifs documentation entries and there is no need of that.

To avoid duplicating information, all documentation related to theme

components like Anaconda is put in design model documentation entires

(@file{trunk/Manual/Directories/trunk/Locales/Identity/Themes/Models/Default/Distro/5/Anaconda.texi}

in this case).  The only reason to create documentation entries inside

artistic motifs is to put a redirection admonition to link design

model related information.

@end table

The Anaconda component is part of CentOS Distribution visual

manifestation. Inside CentOS Distribution visual manifestation there

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

Ksplash that share a similar file organization to that described 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 to change the related

auxiliar path related to it, 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 by for task automation.

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

satisfy the relation to their master paths.  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 concept is very useful to keep

repository organized but introduce some complications.  For instance,

consider what would happen to functionalities like @code{help}, that

rely on master paths to create documentation entries, through auxiliar

paths, if one of those master paths suddenly change after the

documentation entry has been already created for it?

In such cases, functionalities like @code{help} may confuse themselves

if path information is not updated to reflect the appropriate path

relation.  Such functionalities work with master paths as reference;

if a master path is changed, the functionalities won't even note it

because they work with the last master path available in the

repository, no matter what it is. 

In the specific case of documentation (the @code{help} functionality),

the problem mentioned above provokes that older master paths, already

documented, remain inside documentation directory structures as long

as you get your hands into the documentation directory structure

(@file{trunk/Manual}) and change what must be changed to match the new

master path information.

There is no immediate way for @code{help} and similar functionalities

that use master paths as reference, to know when and how the path

information is changed inside the repository. Such information is

available only when files or directories are moved in the repository.

So, is there, at the moment of moving files, when we need to

syncronize paths information between master paths and auxiliar paths

and rename old paths to new paths inside all the files which includes

them (e.g., scalalble vector graphics, documentation files and

translation files files) and commit everything to keep the central

repository up to date.

@quotation

@strong{Warning} Even Subversion can perform some operations using

URLs, there is not support for URLs 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 work on URLs

directly, use Subversion command-line interface instead of

@command{centos-art.sh} script. 

@end quotation

File movement inside the repository is considered a repository change

and it should be recorded as such. In order for this to happen, we

need to add directories and files into the version control system to

make them part of it, commit them, perform the file movement using

version control system commands and finally commit all files related

in the operation. This configuration makes possible for everyone to

know about changes details inside the repository; and if needed,

revert or update them back to a previous revision.

Once all path information has been updated in the filesystem, it is

time to update path information inside all the files involved in the

operation. Considere what would happen to documentation entries

defined in the documentation manual when the target locations they

point to are removed from filesystem. Certainly, that would make

Texinfo to produce an error message when documentation manual is

exported to output files. Something similar could happen to scalable

vector graphics that include artistic motifs background images and

translation messages with path information inside.

So, in order to keep path information syncronized, the

@file{centos-art.sh} script needs to know when such changes happen, in

a way they could be noted and handled without producing errors (e.g.,

replacing old path information to new path information inside all the

files that may include any kind of path information inside).

@subsection Extending repository structure

Occasionly, you may find that new corporate visual identity components

need to be added to the repository. If that is your case, the first

question you need to ask yourself, before start to create directories

blindly all over, is: 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.

The best advice we probably could offer you, when extending

respository structure, is to bear in mind The CentOS Project Corporate

Identity Structure (@pxref{Directories trunk Identity}). The rest is

just matter of choosing appropriate names.  

To illustrate this desition process let's consider the

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

example.  It can be read as: the trunk development line of

@emph{TreeFlower} artistic motif; artistic motifs are part of themes;

and themes part of CentOS corporate visual identity.

When building parent directory structures, you may find that reaching

an acceptable location may take some time, and as it uses to happen

most of time; once you've find one, that may be not a definite

solution.  There are many concepts you need to play with, in order to

find a result that match the conceptual idea you try to implement in

the new directory structure. To know which these concepts are, split

directory structures and read their documentation entry from less

specific to more specific.  The concepts used in

@file{trunk/Identity/Themes/Distro/Motifs/TreeFlower} directory

structure are described in the following documentation entries,

respectively:

@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/

@end verbatim

The @file{trunk/Identity/Themes/Motifs/TreeFlower} location has

evolved through several months of contant work and there is no certain

it won't change in the future, even it fixes quite well the concept we

are trying to implement.  Other location concepts can be found in the

same way described above, just change the directory structure to the

one you are trying to know concepts for.