|
|
87b0e4 |
@emph{''CentOS like trees, has roots, trunk, branches, leaves and
|
|
|
87b0e4 |
flowers. Day by day they work together in freedom, ruled by the laws
|
|
|
87b0e4 |
of nature and open standards, to show the beauty of its existence.''}
|
|
|
87b0e4 |
|
|
|
87b0e4 |
This section describes the organization of files and directories
|
|
|
87b0e4 |
inside the CentOS Artwork Repository. The repository layout provides
|
|
|
87b0e4 |
the standard backend required for automation scripts to work
|
|
|
87b0e4 |
correctly. If such layout changes unexpectedly, automation scripts may
|
|
|
87b0e4 |
confuse themselves and stop doing what you may expect from them to do.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
As convenction, inside CentOS Artwork Repository, files and
|
|
|
87b0e4 |
directories related to CentOS corporate visual identity are organized
|
|
|
87b0e4 |
under three top level directories named: @file{trunk/},
|
|
|
87b0e4 |
@file{branches/}, and @file{tags/}.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
The @file{trunk/} directory (@pxref{Directories trunk}) organizes the main
|
|
|
87b0e4 |
development line of CentOS corporate visual identity. Inside
|
|
|
87b0e4 |
@file{trunk/} directory structure, the CentOS corporate visual
|
|
|
87b0e4 |
identity concepts are implemented using directories. There is one
|
|
|
87b0e4 |
directory level for each relevant concept inside the repository. The
|
|
|
87b0e4 |
@file{trunk/} directory structure is mainly used to perform
|
|
|
87b0e4 |
development tasks related to CentOS corporate visual identity.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
The @file{branches/} directory (@pxref{Directories branches}) oranizes
|
|
|
87b0e4 |
parallel development lines to @file{trunk/} directory. The
|
|
|
87b0e4 |
@file{branches/} directory is used to set points in time where
|
|
|
87b0e4 |
develpment lines are devided one from another taking separte and
|
|
|
87b0e4 |
idependent lives that share a common past from the point they were
|
|
|
87b0e4 |
devided on. The @file{branches/} directory is mainly used to perform
|
|
|
87b0e4 |
quality assurance tasks related to CentOS corporate visual identity.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
The @file{tags/} directory (@pxref{Directories tags}) organizes parallel frozen
|
|
|
87b0e4 |
lines to @file{branches/} directory. The parallel frozen lines are
|
|
|
87b0e4 |
immutable, nothing change inside them once they has been created. The
|
|
|
87b0e4 |
@file{tags/} directory is mainly used to publish final releases of
|
|
|
87b0e4 |
CentOS corporate visual identity.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
The CentOS Artwork Repository layout is firmly grounded on a
|
|
|
87b0e4 |
Subversion base. Subversion (@url{http://subversion.tigris.org}) is a
|
|
|
87b0e4 |
version control system, which allows you to keep old versions of files
|
|
|
87b0e4 |
and directories (usually source code), keep a log of who, when, and
|
|
|
87b0e4 |
why changes occurred, etc., like CVS, RCS or SCCS. Subversion keeps a
|
|
|
87b0e4 |
single copy of the master sources. This copy is called the source
|
|
|
87b0e4 |
``repository''; it contains all the information to permit extracting
|
|
|
87b0e4 |
previous versions of those files at any time.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
@subsection Repository file names
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Repository name convenctions are applied to files and directories
|
|
|
87b0e4 |
inside the repository layout. As convenction, file names are all
|
|
|
87b0e4 |
written in lowercase (@samp{01-welcome.png}, @samp{splash.png},
|
|
|
87b0e4 |
@samp{anaconda_header.png}, etc.) and directory names are all written
|
|
|
87b0e4 |
capitalized (e.g., @samp{Identity}, @samp{Themes}, @samp{Motifs},
|
|
|
87b0e4 |
@samp{TreeFlower}, etc.).
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Repository name convenctions are implemented inside the
|
|
|
87b0e4 |
@code{cli_getRepoName} function of @file{centos-art.sh} script. With
|
|
|
87b0e4 |
@code{cli_getRepoName} function the amount of commands and
|
|
|
87b0e4 |
convenctions to remember are reduced and concentrated in just one
|
|
|
87b0e4 |
single place to look for fixes and improvements.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
@subsection Repository work flow
|
|
|
87b0e4 |
|
|
|
87b0e4 |
As repository work flow we understand a serie of normalized steps used
|
|
|
87b0e4 |
to produce contents inside CentOS Artwork Repository. There are two
|
|
|
87b0e4 |
relevant components inside the repository that we need to normalize
|
|
|
87b0e4 |
work flow for, they are: @emph{content rendition}, @emph{content
|
|
|
87b0e4 |
localization} and @emph{programming}.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
@subsubsection Content rendition
|
|
|
87b0e4 |
|
|
|
87b0e4 |
The CentOS Project Corporate Identity, in part, is made of several
|
|
|
87b0e4 |
visual manifestations. These visual manifestations implement the
|
|
|
87b0e4 |
Corporate Identity by means of images placed in key visible areas of
|
|
|
87b0e4 |
each manifestation visual space. As work flow to produce these images,
|
|
|
87b0e4 |
we decompose images in design models and artistic motifs. Design
|
|
|
87b0e4 |
models provide the image structure (i.e., dimension, translation
|
|
|
87b0e4 |
markers, common designs, etc.) and artistic motifs the visual style
|
|
|
87b0e4 |
(i.e., the background information provide the look and feel).
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Design models are created for each visual manifestation the CentOS
|
|
|
87b0e4 |
Project is made of. This way we describe the visual manifestation and
|
|
|
87b0e4 |
provide a template system for it where several artistic motifs can be
|
|
|
87b0e4 |
applied. Artistic motifs are created with design models in mind, not
|
|
|
87b0e4 |
the visual manifestation such design models are applied to.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
The combination of both design models and artistic motifs is what we
|
|
|
87b0e4 |
know as @emph{Theme}. Themes let us create several design models and
|
|
|
87b0e4 |
several background images apart one another that can be later combined
|
|
|
87b0e4 |
albitrarily one another to provide a flexible way of producing images
|
|
|
87b0e4 |
for different visual manifestations.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
In addition to themes, you can find another way of image production, a
|
|
|
87b0e4 |
more direct way of image production where there is no artistic motif
|
|
|
87b0e4 |
at all, but design models only. This configuration is useful to
|
|
|
87b0e4 |
produce content that don't need specific background information like
|
|
|
87b0e4 |
icons and illustrations used in documentation.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
@subsubsection Content localization
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Whatever content rendition you perform, sometimes you need to produce
|
|
|
87b0e4 |
the content in different languages. Production of content in different
|
|
|
87b0e4 |
languages is known as localization or l10n for short. Inside CentOS
|
|
|
87b0e4 |
Artwork Repository, content localization is performed using the
|
|
|
87b0e4 |
@command{gettext} standard internationalization process as base.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Basically, the @command{gettext} standard internationalization process
|
|
|
87b0e4 |
consists on retriving translatable strings from source files and
|
|
|
87b0e4 |
create Portable Objects and Machine Objects. Portable Objects contain
|
|
|
87b0e4 |
the information translators used to do their work, it is file that can
|
|
|
87b0e4 |
be edited by any convenctional text editor like Vim, Emacs or Nano. On
|
|
|
87b0e4 |
the other hand, Machine Objects are produced to be machine-redable as
|
|
|
87b0e4 |
its name implies, and are produced from Portable Objects.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Since @command{gettext} needs to extract translatable strings form
|
|
|
87b0e4 |
source files in order to let translators to localize them, the types
|
|
|
87b0e4 |
of source files we use inside the repository are limitted to the file
|
|
|
87b0e4 |
types supported by @command{gettext} program. Most of source files
|
|
|
87b0e4 |
supported by @command{gettext} are those from programming languages
|
|
|
87b0e4 |
like C, C++, Bash, Python and Perl just to mention a few from the long
|
|
|
87b0e4 |
list of supported formats. However, formats like SVG, XHTML and
|
|
|
87b0e4 |
Docbook don't figure as supported in the long list of
|
|
|
87b0e4 |
@command{gettext} supported source files. For these formats we use the
|
|
|
87b0e4 |
@command{xml2po} program that come in @file{gnome-doc-utils} package
|
|
|
87b0e4 |
instead. The @command{xml2po} program reads one XML based file and
|
|
|
87b0e4 |
extracts translatable strings from it and creates one Portable Object
|
|
|
87b0e4 |
that is use to create a translated XML based file with the same
|
|
|
87b0e4 |
definition of the source file translatable strings were taken from
|
|
|
87b0e4 |
(e.g., if we extract translatable strings from a SVG file, as result
|
|
|
87b0e4 |
we get the same SVG file but with translatable strings already
|
|
|
87b0e4 |
localized ---obviously, for this to happen translators need to
|
|
|
87b0e4 |
localize translatable strings inside the Portable Object first,
|
|
|
87b0e4 |
localization don't appear as art of magic---). When using
|
|
|
87b0e4 |
@command{xml2po}, the Machine Object file is used just temporally to
|
|
|
87b0e4 |
produce the final translated XML based file.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
@quotation
|
|
|
87b0e4 |
@strong{Tip} If you want to have your content localized inside CentOS
|
|
|
87b0e4 |
Artwork Repository be sure to use source files supported by
|
|
|
87b0e4 |
@command{gettext} and @command{xml2po} programs.
|
|
|
87b0e4 |
@end quotation
|
|
|
87b0e4 |
|
|
|
87b0e4 |
@subsubsection Programming
|
|
|
87b0e4 |
|
|
|
87b0e4 |
So far, we've seen a conceptual view of how image production inside
|
|
|
87b0e4 |
CentOS Artwork Repository is performed, but how all this is
|
|
|
87b0e4 |
implemented, what is the practical view?
|
|
|
87b0e4 |
|
|
|
87b0e4 |
The practical view can be found through @command{centos-art.sh}
|
|
|
87b0e4 |
script, a bash script specially designed to automate most frequent
|
|
|
87b0e4 |
tasks inside CentOS Artwork Repository. The @command{centos-art.sh}
|
|
|
87b0e4 |
script is stored in @file{trunk/Scripts} directory structure and is
|
|
|
87b0e4 |
there where the main development for @command{centos-art.sh} script
|
|
|
87b0e4 |
takes place. Basically, the @command{centos-art.sh} script is divided
|
|
|
87b0e4 |
in several functionalities that perform specific tasks inside the
|
|
|
87b0e4 |
repository. Such functionalities relay on repository organization to
|
|
|
87b0e4 |
work as expected.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Maiking the @command{centos-art.sh} script to automate tasks is the
|
|
|
87b0e4 |
only possible work flow that I can think about right now. If you are a
|
|
|
87b0e4 |
programmer, take a functionality from @command{centos-art.sh} script,
|
|
|
87b0e4 |
study it, look how to improve it and share your ideas at
|
|
|
87b0e4 |
@email{centos-devel@@centos.org} mailing list.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
@quotation
|
|
|
87b0e4 |
@strong{Note} As default configuration, everyone is denied from
|
|
|
87b0e4 |
committing changes up to CentOS Artwork Repository. In order to gain
|
|
|
87b0e4 |
commit rights, you need to prove your interest in contributing and
|
|
|
87b0e4 |
maintaining that contribution. Otherwise, if you only want to comment
|
|
|
87b0e4 |
your ideas, the @email{centos-devel@@centos.org} mailing list exists
|
|
|
87b0e4 |
for you to manifest yourself. This restrictions are necessary to
|
|
|
87b0e4 |
protect our work from spammers.
|
|
|
87b0e4 |
@end quotation
|
|
|
87b0e4 |
|
|
|
87b0e4 |
@subsection Parallel directories
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Inside CentOS Artwork Repository, parallel directories are simple
|
|
|
87b0e4 |
directory entries built from a common parent directory and placed in a
|
|
|
87b0e4 |
location different to that, the common parent directory is placed on.
|
|
|
87b0e4 |
Parallel directories are useful to create branches, tags,
|
|
|
87b0e4 |
translations, documentation, pre-rendering configuration script, and
|
|
|
87b0e4 |
similar directory structures.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Parallel directories take their structure from one unique parent
|
|
|
87b0e4 |
directory. Inside CentOS Artwork Repository, this unique parent
|
|
|
87b0e4 |
directory is under @file{trunk/Identity} location. The
|
|
|
87b0e4 |
@file{trunk/Identity} location must be considered the reference for
|
|
|
87b0e4 |
whatever information you plan to create inside the repository.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
In some circumstances, parallel directories may be created removing
|
|
|
87b0e4 |
uncommon information from their paths. Uncommon path information
|
|
|
87b0e4 |
refers to those directory levels in the path which are not common for
|
|
|
87b0e4 |
other parallel directories. For example, when rendering
|
|
|
87b0e4 |
@file{trunk/Identity/Themes/Motifs/TreeFlower/Distro} directory
|
|
|
87b0e4 |
structure, the @file{centos-art.sh} script removes the
|
|
|
87b0e4 |
@file{Motifs/TreeFlower/} directory levels from path, in order to
|
|
|
87b0e4 |
build the parallel directory used to retrived translations, and
|
|
|
87b0e4 |
pre-rendering configuration scripts required by @code{render}
|
|
|
87b0e4 |
functionality.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Another example of parallel directory is the documentation structure
|
|
|
87b0e4 |
created by @code{manual} functionality. This time,
|
|
|
87b0e4 |
@file{centos-art.sh} script uses parallel directory information with
|
|
|
87b0e4 |
uncommon directory levels to build the documentation entry required by
|
|
|
87b0e4 |
Texinfo documentation system, inside the repository.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Othertimes, parallel directories may add uncommon information to their
|
|
|
87b0e4 |
paths. This is the case we use to create branches and tags. When we
|
|
|
87b0e4 |
create branches and tags, a numerical identifier is added to parallel
|
|
|
87b0e4 |
directory structure path. The place where the numerical identifier is
|
|
|
87b0e4 |
set on is relevant to corporate visual identity structure and should
|
|
|
87b0e4 |
be carefully considered where it will be.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
When one parent directory changes, all their related parallel
|
|
|
87b0e4 |
directories need to be changed too. This is required in order for
|
|
|
87b0e4 |
parallel directories to retain their relation with the parent
|
|
|
87b0e4 |
directory structure. In the other hand, parallel directories should
|
|
|
87b0e4 |
never be modified under no reason but to satisfy the relation to their
|
|
|
87b0e4 |
parent directory structure. Liberal change of parallel directories
|
|
|
87b0e4 |
may suppresses the conceptual idea they were initially created for;
|
|
|
87b0e4 |
and certainly, things may stop working the way they should do.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
@subsection Syncronizing path information
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Parallel directories are very useful to keep repository organized but
|
|
|
87b0e4 |
introduce some complications. For instance, consider what would
|
|
|
87b0e4 |
happen to functionalities like @code{manual} (@samp{trunk Scripts Bash
|
|
|
87b0e4 |
Functions Manual}) that rely on parent directory structures to create
|
|
|
87b0e4 |
documentation entries (using parallel directory structures) if one of
|
|
|
87b0e4 |
those parent directory structures suddenly changes after the
|
|
|
87b0e4 |
documentation entry has been already created for it?
|
|
|
87b0e4 |
|
|
|
87b0e4 |
In such cases, functionalities like @code{manual} may confuse
|
|
|
87b0e4 |
themselves if path information is not updated to reflect the relation
|
|
|
87b0e4 |
with its parent directory. Such functionalities work with parent
|
|
|
87b0e4 |
directory structure as reference; if a parent directory changes, the
|
|
|
87b0e4 |
functionalities dont't even note it because they work with the last
|
|
|
87b0e4 |
parent directory structure available in the repository, no matter what
|
|
|
87b0e4 |
it is.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
In the specific case of documentation (the @code{manual}
|
|
|
87b0e4 |
functionality), the problem mentioned above provokes that older parent
|
|
|
87b0e4 |
directories, already documented, remain inside documentation directory
|
|
|
87b0e4 |
structures as long as you get your hands into the documentation
|
|
|
87b0e4 |
directory structure (@file{trunk/Manuals}) and change what must be
|
|
|
87b0e4 |
changed to match the new parent directory structure.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
There is no immediate way for @code{manual}, and similar
|
|
|
87b0e4 |
functionalities that use parent directories as reference, to know when
|
|
|
87b0e4 |
and how directory movements take place inside the repository. Such
|
|
|
87b0e4 |
information is available only when the file movement itself takes
|
|
|
87b0e4 |
place inside the repository. So, is there, at the moment of moving
|
|
|
87b0e4 |
files, when we need to syncronize parallel directories with their
|
|
|
87b0e4 |
unique parent directory structure.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
@quotation
|
|
|
87b0e4 |
@strong{Warning} There is not support for URL reference inside
|
|
|
87b0e4 |
@file{centos-art.sh} script. The @file{centos-art.sh} script is
|
|
|
87b0e4 |
designed to work with local files inside the working copy only.
|
|
|
87b0e4 |
@end quotation
|
|
|
87b0e4 |
|
|
|
87b0e4 |
As CentOS Artwork Repository is built over a version control system,
|
|
|
87b0e4 |
file movements inside the repository are considered repository
|
|
|
87b0e4 |
changes. In order for these repository changes to be versioned, we
|
|
|
87b0e4 |
need to, firstly, add changes into the version control system, commit
|
|
|
87b0e4 |
them, and later, perform movement actions using version control system
|
|
|
87b0e4 |
commands. This configuration makes possible for everyone to know about
|
|
|
87b0e4 |
changes details inside the repository; and if needed, revert or update
|
|
|
87b0e4 |
them back to a previous revision.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Finally, once all path information has been corrected, it is time to
|
|
|
87b0e4 |
take care of information inside the files. For instance, considere
|
|
|
87b0e4 |
what would happen if you make a reference to a documentation node, and
|
|
|
87b0e4 |
later the documentation node you refere to is deleted. That would make
|
|
|
87b0e4 |
Texinfo to produce error messages at export time. So, the
|
|
|
87b0e4 |
@file{centos-art.sh} script needs to know when such changes happen, in
|
|
|
87b0e4 |
a way they could be noted and handled without producing errors.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
@subsection What is the right place to store it?
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Occasionly, you may find that new corporate visual identity components
|
|
|
87b0e4 |
need to be added to the repository. If that is your case, the first
|
|
|
87b0e4 |
question you need to ask yourself, before start to create directories
|
|
|
87b0e4 |
blindly all over, is: What is the right place to store it?
|
|
|
87b0e4 |
|
|
|
87b0e4 |
The CentOS Community different free support vains (see:
|
|
|
87b0e4 |
@url{http://wiki.centos.org/GettingHelp}) are the best place to find
|
|
|
87b0e4 |
answers to your question, but going there with hands empty is not good
|
|
|
87b0e4 |
idea. It may give the impression you don't really care about. Instead,
|
|
|
87b0e4 |
consider the following suggestions to find your own comprehension and
|
|
|
87b0e4 |
so, make your propositions based on it.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
When we are looking for the correct place to store new files, to bear
|
|
|
87b0e4 |
in mind the corporate visual identity structure used inside the CentOS
|
|
|
87b0e4 |
Artwork Repository (@pxref{Directories trunk Identity}) would be probaly the best
|
|
|
87b0e4 |
advice we could offer, the rest is just matter of choosing appropriate
|
|
|
87b0e4 |
names. To illustrate this desition process let's consider the
|
|
|
87b0e4 |
@file{trunk/Identity/Themes/Motifs/TreeFlower} directory as example.
|
|
|
87b0e4 |
It is the trunk development line of @emph{TreeFlower} artistic motif.
|
|
|
87b0e4 |
Artistic motifs are considered part of themes, which in turn are
|
|
|
87b0e4 |
considered part of CentOS corporate visual identity.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
When building parent directory structures, you may find that reaching
|
|
|
87b0e4 |
an acceptable location may take some time, and as it uses to happen
|
|
|
87b0e4 |
most of time; once you've find it, that may be not a definite
|
|
|
87b0e4 |
solution. There are many concepts that you need to play with, in
|
|
|
87b0e4 |
order to find a result that match the conceptual idea you try to
|
|
|
87b0e4 |
implement in the new directory location. To know which these concepts
|
|
|
87b0e4 |
are, split the location in words and read its documentation entry from
|
|
|
87b0e4 |
less specific to more specific.
|
|
|
87b0e4 |
|
|
|
87b0e4 |
For example, the @file{trunk/Identity/Themes/Motifs/TreeFlower}
|
|
|
87b0e4 |
location evolved through several months of contant work and there is
|
|
|
87b0e4 |
no certain it won't change in the future, even it fixes quite well the
|
|
|
87b0e4 |
concept we are trying to implement. The concepts used in
|
|
|
87b0e4 |
@file{trunk/Identity/Themes/Distro/Motifs/TreeFlower} location are
|
|
|
87b0e4 |
described in the following commands, respectively:
|
|
|
87b0e4 |
|
|
|
87b0e4 |
@verbatim
|
|
|
87b0e4 |
centos-art manual --read=turnk/
|
|
|
87b0e4 |
centos-art manual --read=turnk/Identity/
|
|
|
87b0e4 |
centos-art manual --read=turnk/Identity/Themes/
|
|
|
87b0e4 |
centos-art manual --read=turnk/Identity/Themes/Motifs/
|
|
|
87b0e4 |
centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/
|
|
|
87b0e4 |
@end verbatim
|
|
|
87b0e4 |
|
|
|
87b0e4 |
Other location concepts can be found similary as we did above, just
|
|
|
87b0e4 |
change the location we used above by the one you are trying to know
|
|
|
87b0e4 |
concepts for.
|