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.