@emph{''CentOS like trees, has roots, trunk, branches, leaves and
flowers.  Day by day they work together in freedom, ruled by the laws
of nature and open standards, to show the beauty of its existence.''}

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 Repository work flow

As repository work flow we understand a serie of normalized steps used
to produce contents inside CentOS Artwork Repository. There are three
remarkable actions inside the repository that we need to provide a
normalized work flow for, they are: @emph{Rendition},
@emph{Localization} and @emph{Programming}.

@subsubsection Rendition

Rendition is the action through which The CentOS Project Corporate
Identity is produced inside the repository. The CentOS Project
Corporate Identityis is made, in part, of several visual
manifestations.  These visual manifestations implement the Corporate
Identity by mean of images placed in key areas of their visual space. 

As work flow to produce these images, we decompose them in design
models and artistic motifs. Design models provide the image structure
(i.e., dimension, translation markers, common designs, etc.) and
artistic motifs the visual style (i.e., the background information
provide the look and feel). 

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 such design models is built for.

The combination of one design models with one artistic motifs is what
we know as one @emph{theme}. Inside themes directory structure, 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. Theme
rendition takes place in @file{trunk/Identity/Themes/Models} and
@file{trunk/Identity/Themes/Motifs} directory structures.

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 like icons
and illustrations used in documentation. Direct rendition takes place
in @file{trunk/Identity/Models} and @file{trunk/Identity/Images}
directory structures.

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

@subsubsection Localization

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
processed 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 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. For these formats we use the
@command{xml2po} program that come in the @file{gnome-doc-utils}
package instead.  The @command{xml2po} program reads one XML based
file and extracts translatable strings from it and creates one
Portable Object that is use 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 Programming

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. 

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

@subsection Work lines

The CentOS Artwork Repository is organized using the Rendition,
Localization and Programming concepts described above.  These concepts
suggest three different work lines to get focused in: 

@table @strong
@item Graphic design 

This work line exists to cover the corporate design (e.g., brand
design, typography design and theme design). Other areas that could be
included here are icon design and illustration design for
documentation.

@item Documentation

This work line exists to describe what each directory structure inside
the CentOS Artwork Repository is for and how to produce content inside
it.

@item Translation

This work line exists to localize corporate design and documentation
source files, so they can be produced in different languages.

@item Automation

This work line exists to standardize corporate design, documentation
and localization processes and automate their production. There is no
need to repeat several tasks time after time if they can be programmed
in just one for you to execute. If you need to improve the way content
is produced, look inside automation scripts and make your improvement
there for every one to benefit.
@end table

@subsection Parallel directories

Inside CentOS Artwork Repository, parallel directories are simple
directory entries built from a common parent directory and placed in a
location different to that, the common parent directory is placed on.
Parallel directories are useful to create branches, tags,
translations, documentation, pre-rendering configuration script, and
similar directory structures.

Parallel directories take their structure from one unique parent
directory. Inside CentOS Artwork Repository, this unique parent
directory is under @file{trunk/Identity} location.  The
@file{trunk/Identity} location must be considered the reference for
whatever information you plan to create inside the repository.

In some circumstances, parallel directories may be created removing
uncommon information from their paths. Uncommon path information
refers to those directory levels in the path which are not common for
other parallel directories.  For example, when rendering
@file{trunk/Identity/Themes/Motifs/TreeFlower/Distro} directory
structure, the @file{centos-art.sh} script removes the
@file{Motifs/TreeFlower/} directory levels from path, in order to
build the parallel directory used to retrived translations, and
pre-rendering configuration scripts required by @code{render}
functionality.

Another example of parallel directory is the documentation structure
created by @code{manual} functionality. This time,
@file{centos-art.sh} script uses parallel directory information with
uncommon directory levels to build the documentation entry required by
Texinfo documentation system, inside the repository.

Othertimes, parallel directories may add uncommon information to their
paths. This is the case we use to create branches and tags. When we
create branches and tags, a numerical identifier is added to parallel
directory structure path. The place where the numerical identifier is
set on is relevant to corporate visual identity structure and should
be carefully considered where it will be.

When one parent directory changes, all their related parallel
directories need to be changed too. This is required in order for
parallel directories to retain their relation with the parent
directory structure.  In the other hand, parallel directories should
never be modified under no reason but to satisfy the relation to their
parent directory structure.  Liberal change of parallel directories
may suppresses the conceptual idea they were initially created for;
and certainly, things may stop working the way they should do.

@subsection Syncronizing path information

Parallel directories are very useful to keep repository organized but
introduce some complications.  For instance, consider what would
happen to functionalities like @code{manual} (@samp{trunk Scripts Bash
Functions Manual}) that rely on parent directory structures to create
documentation entries (using parallel directory structures) if one of
those parent directory structures suddenly changes after the
documentation entry has been already created for it? 

In such cases, functionalities like @code{manual} may confuse
themselves if path information is not updated to reflect the relation
with its parent directory.  Such functionalities work with parent
directory structure as reference; if a parent directory changes, the
functionalities dont't even note it because they work with the last
parent directory structure available in the repository, no matter what
it is. 

In the specific case of documentation (the @code{manual}
functionality), the problem mentioned above provokes that older parent
directories, already documented, remain inside documentation directory
structures as long as you get your hands into the documentation
directory structure (@file{trunk/Manuals}) and change what must be
changed to match the new parent directory structure.

There is no immediate way for @code{manual}, and similar
functionalities that use parent directories as reference, to know when
and how directory movements take place inside the repository. Such
information is available only when the file movement itself takes
place inside the repository. So, is there, at the moment of moving
files, when we need to syncronize parallel directories with their
unique parent directory structure.

@quotation
@strong{Warning} There is not support for URL reference inside
@file{centos-art.sh} script.  The @file{centos-art.sh} script is
designed to work with local files inside the working copy only.
@end quotation

As CentOS Artwork Repository is built over a version control system,
file movements inside the repository are considered repository
changes. In order for these repository changes to be versioned, we
need to, firstly, add changes into the version control system, commit
them, and later, perform movement actions using version control system
commands. 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.

Finally, once all path information has been corrected, it is time to
take care of information inside the files. For instance, considere
what would happen if you make a reference to a documentation node, and
later the documentation node you refere to is deleted. That would make
Texinfo to produce error messages at export time. So, 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.

@subsection What is the right place to store it?

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 CentOS Community different free support vains (see:
@url{http://wiki.centos.org/GettingHelp}) are the best place to find
answers to your question, 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 and
so, make your propositions based on it.

When we are looking for the correct place to store new files, to bear
in mind the corporate visual identity structure used inside the CentOS
Artwork Repository (@pxref{Directories trunk Identity}) would be probaly the best
advice we could offer, 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 as example.
It is the trunk development line of @emph{TreeFlower} artistic motif.
Artistic motifs are considered part of themes, which in turn are
considered 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 it, that may be not a definite
solution.  There are many concepts that you need to play with, in
order to find a result that match the conceptual idea you try to
implement in the new directory location. To know which these concepts
are, split the location in words and read its documentation entry from
less specific to more specific.

For example, the @file{trunk/Identity/Themes/Motifs/TreeFlower}
location 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.  The concepts used in
@file{trunk/Identity/Themes/Distro/Motifs/TreeFlower} location are
described in the following commands, respectively:

@verbatim
centos-art manual --read=turnk/
centos-art manual --read=turnk/Identity/
centos-art manual --read=turnk/Identity/Themes/
centos-art manual --read=turnk/Identity/Themes/Motifs/
centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/
@end verbatim

Other location concepts can be found similary as we did above, just
change the location we used above by the one you are trying to know
concepts for.