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
@cindex 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 (@pxref{GNU General Public License}) in order for them to
remain inside the repository.
@subsection Repository organization
@cindex 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
@cindex 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 for each available work line.
@subsubsection Graphic design
@cindex Graphic design work line
@xref{Directories trunk Identity}, for more information about The
CentOS Corporate Identity and how graphic design fits on it.
@subsubsection Documentation
@cindex Documentation work line
@xref{Directories trunk Manuals}, for more information on
documentation.
@subsubsection Localization
@cindex Localization work line
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 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 localize the
translatable strings retrived from source files. 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 to produce portable objects for them.
@quotation
@strong{Note}
Portable objects produced by @command{xml2po} have the same format
that portable objects produced by @command{gettext}. This make the
localization process quite consistent from translators' point of view.
No matter what the source file be, the translator will always face the
same translation file format (i.e., the portable object format).
@end quotation
With the portable object in place, the @command{xml2po} program is
used 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
@cindex Automation work line
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 executable
script.
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 relay 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
@cindex Connection between directories
@cindex Master paths
@cindex Auxiliar paths
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., 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 to document the master path it refers to.
The relation between auxiliar paths and master paths is realized
combining two path informations which are: the master path itself and
one second level directory structure from the repository. Generally,
the master path is considered the path identifier and the second level
directory structure taken from the repository is considered the common
part of the path where the identifier is appended.
@float Figure, Path construction
@verbatim
-----+---------------+----------------------------+------+-----------
Path | Suffix | Identifier |Prefix| Type
-----+---------------+----------------------------+------+-----------
A | |trunk/Identity/Models/Brands| | Directory
-----+---------------+----------------------------+------+-----------
B | trunk/Manual/|trunk/Identity/Models/Brands|.texinfo | File
-----+---------------+----------------------------+------+-----------
C | trunk/Locales/|trunk/Identity/Models/Brands| | Directory
-----+---------------+----------------------------+------+-----------
D | |trunk/Identity/Images/Brands| | Directory
-----+---------------+----------------------------+------+-----------
E | trunk/Locales/|trunk/Identity/Images/Brands|.texinfo | 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{Path construction.}
@end float
The path information described above (@pxref{Path construction}) is
used by direct rendition and can be taken as reference to add other
components that are equally produced in the repository. To add 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, without changing the path structure around
it.
The file organization used by theme rendition extends direct rendition
by separating design models information from backgrounds information.
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 very well. For
example, consider the organization used to produce @file{Anaconda}
images; for CentOS distribution major release 5; using @file{Default}
design models and version @file{3} of @file{Flame} artistic motif:
@float Figure, Path construction extended
@verbatim
-----+---------------+------------------------------------------------------+------+-----------
Path | Suffix | Identifier |Prefix| Type
-----+---------------+------------------------------------------------------+------+-----------
A | |trunk/Identity/Models/Themes/Default/Distro/5/Anaconda| | Directory
-----+---------------+------------------------------------------------------+------+-----------
B | trunk/Manual/|trunk/Identity/Models/Themes/Default/Distro/5/Anaconda|.texinfo | File
-----+---------------+------------------------------------------------------+------+-----------
C | trunk/Locales/|trunk/Identity/Models/Themes/Default/Distro/5/Anaconda| | Directory
-----+---------------+------------------------------------------------------+------+-----------
D | |trunk/Identity/Images/Themes/Flame/3/Distro/5/Anaconda| | Directory
-----+---------------+------------------------------------------------------+------+-----------
E | trunk/Locales/|trunk/Identity/Images/Themes/Flame/3/Distro/5/Anaconda|.texinfo | 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{Path construction extended.}
@end float
The path information described above (@pxref{Path construction
extended}) is used by theme rendition and can be taken as reference to
add other components that are equally produced in the repository.
In this configuration we can change both design model name (e.g.,
@file{Default}) and artistic motif name (e.g., @file{Flame/3}) to
something else in order to achieve a different result. The only
limitations impossed are the storage space provided in the server
machine and your own creativeness as graphic designer.
@quotation
@strong{Note}
A theme ready for implementation may consume from 100 MB to 400 MB of
storage space. The exact space consumed by a theme depends on the
amount of screen resolutions the theme supports. The more screen
resolutions the theme supports, the more storage space demanded for
it.
@end quotation
In this configuration we saw how to build the path information for
@file{Anaconda} component as part of CentOS Distribution visual
manifestation, but that is not the only component we have 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 @file{Anaconda}
component.
@subsection Syncronizing path information
@cindex Syncronizing path information
Syncronizing path information is the action that keeps 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 related to duplicate, delete and
rename files and directories in the repository. File content
replacement is related to replace information, 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
perform file content replacement first because that would imply a
repository change which will immediatly demmand a commit in order for
actions like duplicate, delete or rename to take place. However, if we
perform file movement first, it is possible to commit both file moved
and file content replacements as if they were just one change. In this
case the file content replacement takes palce in the target location
that have been duplicated or renamed, not the one use as source
location. This configuration is specially useful when files are
renamed (i.e., one file is copied from a source location to a target
location and then the source location of it is 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
When one master path is changed it is required that all related
auxiliar paths be changed, too. This is required in order for master
paths to retain their relation with auxiliar paths. This way,
automation scripts are able to know where to retrive translation
messages from, where to store final output images to 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 they need.
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, automation scripts may stop working as
expected. The update direction to rename path information must be from
master path to auxiliar path and never the opposite.
The relation between master and auxiliar paths is 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. This is the case of repository documentation
manual source files where inclusions, menus, nodes and cross
references are built using master path information as reference. Now,
to see what kind of complication we are talking about, consider what
would happen to a structural definitions (i.e., inlusions, menus,
nodes and cross refereces) already set in the manual from one master
path that is suddenly renamed to something different. If the path
information is not syncronized, at this point, we lose connection
between the master path and the auxiliar path created to store the
related documentation entry, as well as the related structural
definitions that end up pointing to a master path that no longer
exist.
The syncronization of path information is aimed to solve these kind of
issues.
@subsection Extending repository organization
@cindex 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/Images/Themes} to store theme
artistic motifs, @file{trunk/Identity/Models/Themes} 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/Images/Themes/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/Images/Themes
centos-art help --read turnk/Identity/Images/Themes/TreeFlower
centos-art help --read turnk/Identity/Images/Themes/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.