Blame Manual/Introduction/repo-convenctions.texi

74c0c0
The CentOS Artwork Repository is supported by Subversion
74c0c0
(@url{http://subversion.tigris.org/}), a version control system which
74c0c0
allows you to keep old versions of files and directories (usually
74c0c0
source code), keep a log of who, when, and why changes occurred, etc.,
32f4f2
like CVS, RCS or SCCS.  When using Subversion there is one source
74c0c0
repository and many working copies of that source repository. The
74c0c0
working copies are independent one another, can be distributed all
74c0c0
around the world and provide a local place for designers, documentors,
74c0c0
translators and programmers to perform their works in a descentralized
74c0c0
way.  The source repository, on the other hand, provides a central
74c0c0
place for all independent working copies to interchange data and the
74c0c0
information required to permit extracting previous versions of files
74c0c0
at any time.
74c0c0
74c0c0
@subsection Repository policy
74c0c0
32f4f2
The CentOS Artwork Repository is a collaborative tool that anyone can
32f4f2
have access to. However, changing that tool in any form is something
32f4f2
that should be requested in @email{centos-devel@@centos.org} mailing
32f4f2
list.  Generally, people download working copies from CentOS Artwork
32f4f2
Repository, study the repository organization, make some changes in
32f4f2
their working copies, make some tests to verify such changes work the
32f4f2
way expected and request access to commit them up to the CentOS
32f4f2
Artwork Repository for others to benefit from them.
74c0c0
74c0c0
Once you've received access to commit your changes, there is no need
74c0c0
for you to request permission again to commit other changes from your
74c0c0
working copy to CentOS Artwork Repository as long as you behave as a
74c0c0
@emph{good community citizen}.
74c0c0
74c0c0
As a good community citizen one understand of a person whom respects
74c0c0
the work already done for others and share ideas with authors before
74c0c0
changing relevant parts of their work, specially in situations when
74c0c0
the access required to realize those changes has been granted already.
74c0c0
Of course, there is a time when conversation has taken place, the
74c0c0
paths has been traced and changing the work is so obvious that there
74c0c0
is no need to talk about it; that's because you already did, you
74c0c0
already built the trust to keep going. Anyway, the mailing list
74c0c0
mentioned above is available for sharing ideas in a way that good
74c0c0
relationship between community citizens could be constantly balanced.
74c0c0
74c0c0
The relationship between community citizens is monitored by repository
74c0c0
administrators. Repository administrators are responsible of granting
74c0c0
everything goes the way it needs to go in order for the CentOS Artwork
74c0c0
Repository to comply its mission which is: to provide a colaborative
74c0c0
tool for The CentOS Community where The CentOS Project Corporate
74c0c0
Identity is built and maintained from The CentOS Community itself.
74c0c0
74c0c0
It is also important to remember that all source files inside CentOS
74c0c0
Artwork Repository should comply the terms of GNU General Public
74c0c0
License in order for them to remain inside the repository. See file
74c0c0
@url{file:///home/centos/artwork/trunk/Scripts/COPYING,trunk/Scripts/COPYING},
74c0c0
for a complete license description.
74c0c0
74c0c0
@subsection Repository organization 
74c0c0
74c0c0
The CentOS Artwork Repository uses a @file{trunk}, @file{branches},
74c0c0
and @file{tags} organization.  
74c0c0
74c0c0
@table @file
74c0c0
@item trunk
74c0c0
74c0c0
The @file{trunk} directory organizes the main development line of
74c0c0
CentOS Artwork Repository. @xref{Directories trunk}, for more
74c0c0
information.
74c0c0
74c0c0
@item branches
74c0c0
74c0c0
The @file{branches} directory oranizes intermedaite development lines
74c0c0
taken from the main development line.  @xref{Directories branches},
74c0c0
for more information.
74c0c0
74c0c0
@item tags
74c0c0
74c0c0
The @file{tags} directory organizes frozen development lines taken
74c0c0
from the main or the intermediate lines of development.
74c0c0
@xref{Directories tags}, for more information.
74c0c0
@end table
87b0e4
87b0e4
@subsection Repository file names
87b0e4
74c0c0
For name concistency in CentOS Artwork Repository, 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
74c0c0
@subsection Repository work lines
c2929c
32f4f2
Inside CentOS Artwork Repository there are four major production work
32f4f2
lines which are: @emph{graphic design}, @emph{documentation},
32f4f2
@emph{localization} and @emph{automation}.  These work lines describe
32f4f2
different areas of content production. Content production inside these
32f4f2
specific areas may vary as much as persons be working on them.
32f4f2
Producing content in too many different ways may result innapropriate
32f4f2
in a collaborative environment like CentOS Artwork Repository where
32f4f2
content produced in one area depends somehow from content produced in
32f4f2
another different area. To produce content in a syncronized but
32f4f2
descentralized way, it is required to define a @emph{content
32f4f2
production standard} that lead everyone work in order for the content
32f4f2
produced in each different work line to gear correctly once it is put
32f4f2
together.
c2929c
c2929c
The standard way of producing content inside CentOS Artwork Repository
c2929c
is implemented through @command{centos-art.sh} script and described in
74c0c0
@file{trunk/Scripts} documentation entry (@pxref{Directories trunk
74c0c0
Scripts}).
c2929c
87b0e4
2b93ca
@subsubsection Graphic design
798844
74c0c0
The graphic design work line exists to cover brand design, typography
74c0c0
design and theme design. Additionally, some auxiliar areas like icon
74c0c0
design, illustration design for documentation, brushes design,
74c0c0
patterns designs and definition of palettes of colors could be
74c0c0
included here for completeness.
74c0c0
74c0c0
Inside CentOS Artwork Repository graphic design is performed through
74c0c0
Inkscape (@url{http://www.inkscape.org/}) and GIMP
74c0c0
(@url{http://www.gimp.org/}).  Inkscape is used to create and
74c0c0
manipulate scalable vector graphics and export them to PNG format; it
74c0c0
also provides a command-line interface that we use to perform massive
74c0c0
exportation from SVG files to PNG files through automation scripts. On
74c0c0
the other hand, GIMP is used to create and manipulate rastered images,
74c0c0
create brushes, patterns and palettes of colors.  
74c0c0
74c0c0
@quotation
74c0c0
@strong{Tip} You can combine both Inkscape and GIMP specific
74c0c0
functionalities and possibilities to produce very beautiful images.
74c0c0
@end quotation
74c0c0
74c0c0
Another area covered by graphic design is that related to visual
74c0c0
manifestations The CentOS Project Corporate Identity is made of.
74c0c0
Visual manifestations implement the corporate identity concepts by
74c0c0
mean of images placed in key areas of their visual space.  To produce
74c0c0
these images, we've decomposed image production in @emph{design
74c0c0
models} and @emph{artistic motifs}. 
74c0c0
74c0c0
Design models provide the structural information of images (i.e.,
74c0c0
dimension, position of common elements, translation markers, etc.) and
74c0c0
they are generally produced as scalable vector graphics to take
74c0c0
advantage of the inclusion feature supported by that standard which
74c0c0
let us load different background images for the same design model
74c0c0
changing path information. On the other hand, artistic motifs provide
74c0c0
the visual style (i.e., the background information, the look and feel)
74c0c0
and are generally produced as rastered images.  
87b0e4
87b0e4
Design models are created for each visual manifestation the CentOS
74c0c0
Project is made of. This way it is possible to describe the visual
74c0c0
manifestation and provide a template system for it.  
74c0c0
74c0c0
Artistic motifs are created with design models in mind, not the visual
74c0c0
manifestation those design models are built for.
c2929c
c2929c
The result produced by combining one design model with one artistic
c2929c
motif is what we know as a @emph{theme}. Inside themes directory
c2929c
structure (@pxref{Directories trunk Identity Themes}), you can find
c2929c
several design models and several artistic motifs, apart one another,
c2929c
that can be albitrarily combined one another through @emph{theme
c2929c
rendition}, a flexible way to produce images for different visual
c2929c
manifestations inside CentOS Artwork Repository. Inside themes
c2929c
directory structure, theme rendition is performed in
74c0c0
@file{trunk/Identity/Themes/Motifs} directory structures and required
74c0c0
design models are taken from @file{trunk/Identity/Themes/Models}
74c0c0
directory structure.
74c0c0
74c0c0
In addition to theme rendition you can find @emph{direct rendition},
74c0c0
another way of image production where there is no artistic motif at
74c0c0
all but design models only. Direct rendition is very useful to produce
74c0c0
simple content that doesn't need specific background information like
74c0c0
brands, icons and illustrations.  Direct rendition takes place in
74c0c0
@file{trunk/Identity/Images} and the required design models are taken
74c0c0
from @file{trunk/Identity/Models} directory structure.
798844
c2929c
@xref{Directories trunk Identity}, for more information on graphic
c2929c
design.
798844
2b93ca
@subsubsection Documentation
2b93ca
74c0c0
The documentation work line exists to describe what each directory
74c0c0
inside the CentOS Artwork Repository is for and how to produce content
74c0c0
inside them.
74c0c0
74c0c0
The CentOS Artwork Repository documentation is supported by Texinfo, a
74c0c0
documentation system that uses a single source file to produce both
74c0c0
online information and printed output. The repository documentation is
74c0c0
organized under @file{trunk/Manual} directory structure using
74c0c0
repository directories as reference. Directories inside CentOS Artwork
74c0c0
Repository are created based on conceptual idea, so one documentation
74c0c0
entry exists for each directory inside the repository in order to
32f4f2
describe the conceptual ideas such directory is based on.
74c0c0
74c0c0
Directory documentation entries are stored under
74c0c0
@file{trunk/Manual/Directories} directory structure and controlled by
74c0c0
the @code{help} functionality of @command{centos-art.sh} script.
32f4f2
Using the @code{help} functionality you can create, edit and remove
74c0c0
directory documentation in a way you don't need to take care of
74c0c0
updating menus, nodes and cross reference information inside the
74c0c0
manual structure; the functionality takes care of it for you.
74c0c0
However, if you need to write repository documentation that have
74c0c0
nothing to do with repository directories (e.g., Preface, Introduction
74c0c0
and similar) you need to do it manually, there is no functionality to
74c0c0
automate such process yet.
87b230
87b230
@xref{Directories trunk Manual}, for more information on
87b230
documentation.
2b93ca
8e4e50
@subsubsection Localization
87b0e4
74c0c0
The localization work line exists to provide the translation messages
74c0c0
required to produce content in different languages. Among these
74c0c0
contents are: image files, documentation and automation scripts.
2b93ca
74c0c0
Most of localization tasks have been grouped inside the @code{locale}
74c0c0
functionality of @command{centos-art.sh} script which make use of
74c0c0
@command{gettext} and @command{xml2po} programs.
87b0e4
74c0c0
The procedure used to localize content is taken from @command{gettext}
74c0c0
standard specification. Basically, translatable strings are retrived
74c0c0
from source files in order to create Portable Objects and Machine
74c0c0
Objects.  Portable Objects are editable files that contain the
74c0c0
information used by translators to do their work. On the other hand,
74c0c0
Machine Objects are produced to be machine-redable, as its name
74c0c0
implies, and are produced from Portable Objects.
87b0e4
87b0e4
Since @command{gettext} needs to extract translatable strings form
74c0c0
source files in order to let translators to localize them, the type of
74c0c0
source files we can use inside the repository is limitted to the file
87b230
types supported by @command{gettext} program. Most of the source files
74c0c0
supported by @command{gettext} are those of programming languages like
74c0c0
C, C++, Bash, Python and Perl just to mention a few ones from the long
74c0c0
list of supported formats. However, formats like SVG, XHTML and
87b0e4
Docbook don't figure as supported in the long list of
87b230
@command{gettext} supported source files. 
87b230
87b230
To translate XML based source files like SVG, XHTML and Docbook we use
74c0c0
the @command{xml2po} program instead. This program comes with
87b230
@file{gnome-doc-utils} package and reads one XML based file to extract
87b230
translatable strings from it. As result it creates one Portable Object
74c0c0
that is used by @command{xml2po} itself to create the translated XML
87b230
based file with the same definition of the source file where
87b230
translatable strings were taken from (e.g., if we extract translatable
87b230
strings from a SVG file, as result we get the same SVG file but with
87b230
translatable strings already localized ---obviously, for this to
87b230
happen translators need to localize translatable strings inside the
87b230
Portable Object first, localization won't appear as art of magic---).
87b230
When using @command{xml2po}, the Machine Object file is used just
87b230
temporally to produce the final translated XML based file.
87b0e4
87b0e4
@quotation
87b0e4
@strong{Tip} If you want to have your content localized inside CentOS
74c0c0
Artwork Repository be sure to use source files supported either by
74c0c0
@command{gettext} or @command{xml2po} programs.
87b0e4
@end quotation
87b0e4
8e4e50
@xref{Directories trunk Locales}, for more information.
87b0e4
2b93ca
@subsubsection Automation
2b93ca
74c0c0
The automation work line exists to standardize content production
32f4f2
inside CentOS Artwork Repository. There is no need to type several
74c0c0
tasks time after time if they can be programmed into just one script
74c0c0
that groups them all.  
87b0e4
32f4f2
The automation work line takes place under @file{trunk/Scripts}
74c0c0
directory structure. Here is developed the @command{centos-art.sh}
87b0e4
script, a bash script specially designed to automate most frequent
74c0c0
tasks inside CentOS Artwork Repository. Basically, the
74c0c0
@command{centos-art.sh} script is divided in several functionalities
74c0c0
that perform specific tasks inside the repository. Such
74c0c0
functionalities relay on repository organization to work as expected. 
74c0c0
74c0c0
@quotation
74c0c0
@strong{Tip} If you need to improve the way content is produced, look
32f4f2
inside automation scripts and make your improvement there for everyone
32f4f2
to benefit.
87b0e4
@end quotation
87b0e4
c2929c
@xref{Directories trunk Scripts}, for more information on automation.
8e4e50
87b230
@subsection Connection between directories
87b230
87b230
In order to produce content correctly inside CentOS Artwork
87b230
Repository, it is required that all work lines be connected somehow.
74c0c0
This is the way automation scripts can know what design model and what
74c0c0
translation files to use when specific contents are produced, also
74c0c0
where to save the content produced as result.  This connection between
32f4f2
directories takes place through two path constructions named @emph{The
32f4f2
Master Paths} and @emph{The Auxiliar Paths}.
32f4f2
32f4f2
The master paths point to directories which contain the source files
32f4f2
(e.g., SVG files) required to produce base content (e.g., PNG files).
32f4f2
Each master path inside the repository has several auxiliar paths
32f4f2
associated. 
32f4f2
32f4f2
The auxiliar paths can point either to directories or files. When an
32f4f2
auxiliar path points to a directory, that directory contains
32f4f2
information that modifies somehow the content produced from the master
32f4f2
path (e.g., through translation messages) or provides the output
32f4f2
information of where to store the content produced from master path.
32f4f2
When an auxiliar path points to a file, that file has no other purpose
32f4f2
but document the master path it refers to.
32f4f2
32f4f2
The relation between auxiliar paths and master paths is realized
32f4f2
taking one unique master path as reference.  Master paths define how
32f4f2
auxiliar paths are constructed.  Master paths can have several
74c0c0
auxiliar paths associated, but auxiliar paths can have only one master
32f4f2
path associated.  For example, consider the following path relation
32f4f2
and note how there are constant and variable values in them:
87b230
87b230
@table @file
87b230
@item trunk/Identity/Models/Brands
87b230
74c0c0
This directory contains source files (e.g., SVG, XCF, etc.) used to
74c0c0
produce the brand images of The CentOS Project.
74c0c0
74c0c0
Here is where you, as graphic designers, define design models used to
74c0c0
produce the brand images of The CentOS Project.
74c0c0
32f4f2
The path to this directory is considered a master path because it
32f4f2
contains the most critical information (i.e., the information that
32f4f2
can't be absent) required to produce the brand images of The CentOS
32f4f2
Project.
74c0c0
74c0c0
@item trunk/Manual/Directories/trunk/Identity/Models/Brands.texi
74c0c0
74c0c0
This file contains documentation, in Texinfo format, for design models
32f4f2
used to produce the brand images of The CentOS Project. The path to
32f4f2
this file is made of three parts:
32f4f2
32f4f2
@verbatim
32f4f2
            A                         B                C
32f4f2
|-----------------------|----------------------------|---|
32f4f2
trunk/Manual/Directories/trunk/Identity/Models/Brands.texi
32f4f2
|-----------------------|----------------------------|---|
32f4f2
32f4f2
A = The documentation manual source location.
32f4f2
B = The master path we are building documentation for.
32f4f2
C = The file extension used by Texinfo documentation files.
32f4f2
@end verbatim
74c0c0
74c0c0
Here is where you, as documentor, describe construction of desing
74c0c0
models used to produce the brand images of The CentOS Project. In this
74c0c0
description you can include image dimensions, color information, image
32f4f2
location inside CentOS Distribution filesystem, packaging and similar
32f4f2
things.
74c0c0
32f4f2
The path to this directory is considered auxiliar path of
32f4f2
@file{trunk/Identity/Models/Brands} master path.
87b230
87b230
@item trunk/Locales/Identity/Models/Brands
87b230
74c0c0
This directory contains translation files, as @command{gettext}
74c0c0
portable objects, for design models used to produce the brand images
32f4f2
of The CentOS Project. The path to this directory made of two parts: 
32f4f2
32f4f2
@verbatim
32f4f2
      A                 B
32f4f2
|------------|---------------------|
32f4f2
trunk/Locales/Identity/Models/Brands
32f4f2
|------------|---------------------|
32f4f2
32f4f2
A = The translation messages source location.
32f4f2
B = The master path we are building translation messages for.
32f4f2
@end verbatim
74c0c0
74c0c0
Here is where you, as translator, localize translatable strings
74c0c0
retrived in English language from design models used to produce the
74c0c0
brand images of The CentOS Project. If no portable object is found
74c0c0
here the translation tasks are skipped to produce no translation at
74c0c0
all, obviously there is no portable object to retrive translation
74c0c0
messages from.
74c0c0
32f4f2
The path to this directory is considered auxiliar path of
32f4f2
@file{trunk/Identity/Models/Brands} master path.
87b230
87b230
@item trunk/Manual/Directories/trunk/Locales/Identity/Models/Brands.texi
87b230
74c0c0
This file contains documentation, in Texinfo format, for translation
32f4f2
messages retrived from design models used to produce brand images
32f4f2
required by The CentOS Project. The path to this file is made of three
32f4f2
parts:
32f4f2
32f4f2
@verbatim
32f4f2
            A                              B                   C
32f4f2
|-----------------------|------------------------------------|---|
32f4f2
trunk/Manual/Directories/trunk/Locales/Identity/Models/Brands.texi
32f4f2
|-----------------------|------------------------------------|---|
32f4f2
32f4f2
A = The documentation manual source location.
32f4f2
B = The master path we are building documentation for.
32f4f2
C = The file extension used by Texinfo documentation files.
32f4f2
@end verbatim
32f4f2
32f4f2
Here is where you, as documentor, describe localization of those
32f4f2
desing models used to produce brand images required by The CentOS
74c0c0
Project. In this description you can include image dimensions, color
32f4f2
information, image location inside the file system of CentOS
32f4f2
Distribution, packaging and similar things.
74c0c0
32f4f2
The path to this file is considered auxiliar path of
32f4f2
@file{trunk/Identity/Models/Brands} master path.
87b230
87b230
@item trunk/Identity/Images/Brands
87b230
32f4f2
This directory contains the final brand images produced from brand
32f4f2
design models used by The CentOS Project.
87b230
32f4f2
Here is where you, as packager, can find the brand images you need to
32f4f2
rebrand the CentOS Distribution.
87b230
32f4f2
The path to this directory is considered auxiliar path of
74c0c0
@file{trunk/Identity/Models/Brands} master path.
87b230
87b230
@item trunk/Manual/Directories/trunk/Identity/Images/Brands.texi
87b230
74c0c0
This file should contains documentation, in Texinfo format, about how
74c0c0
to implement final brand images of The CentOS Project.  However, this
32f4f2
documentation entry is rarely used because the related design model
32f4f2
documentation entry already covers implementation of brand images.
32f4f2
The only reason to create this documentation entry is to put in an
32f4f2
admonition that redirect people up to the correct place (i.e., the
32f4f2
related design model coumentation entry).
87b230
@end table
87b230
87b230
The configuration described above for organizing brand component
87b230
inside the repository is the one used by direct rendition and can be
87b230
used as reference to organize other components inside the repository
87b230
that are produced through direct rendition too. Just change the
32f4f2
component name from @file{Brands} to a different one without changing
32f4f2
the path structure around it.
87b230
87b230
The file organization used by theme rendition, however, is a bit
87b230
different from that used by direct rendition. In theme rendition, both
32f4f2
the master paths and the auxiliar paths are built dynamically based on
32f4f2
one design model and one artistic motif specified by you at rendition
32f4f2
time.  As a mnemotechnic resource, you could consider theme rendition
32f4f2
as two independent lists, one of design models and one of artistic
32f4f2
motifs, which are arbitrary combined between themselves in order to
32f4f2
render images in specific ways. For example, consider the organization
32f4f2
used to produce Anaconda images; for CentOS distribution major release
32f4f2
5; using @file{Default} design models and version @file{3} of
32f4f2
@file{Flame} artistic motif:
87b230
87b230
@table @file
87b230
@item trunk/Identity/Themes/Models/Default/Distro/5/Anaconda
87b230
87b230
This directory contains source files used to produce Anaconda images
32f4f2
for CentOS distribution major release 5. This specific information has
32f4f2
been named the @file{Default} design model. The path to this directory
32f4f2
is made of three parts:
32f4f2
32f4f2
@verbatim
32f4f2
              A                 B           C
32f4f2
|---------------------------|-------|----------------|
32f4f2
trunk/Identity/Themes/Models/Default/Distro/5/Anaconda
32f4f2
|---------------------------|-------|----------------|
87b230
32f4f2
A = The theme model source location.
32f4f2
B = The theme model name.
32f4f2
C = The visual manifestation the theme model is created for.
32f4f2
@end verbatim
87b230
32f4f2
Here is where you, as graphic designers, define @file{Default} design
32f4f2
models for Anaconda images in major release 5 of CentOS distribution. 
32f4f2
32f4f2
The path to this directory is considered the master path because it
32f4f2
contains the most critical information (i.e., the information that
32f4f2
can't be absent) required to produce Anaconda images for major release
32f4f2
5 of CentOS distribution.
87b230
87b230
@item trunk/Manual/Directories/trunk/Identity/Themes/Models/Default/Distro/5/Anaconda.texi
87b230
32f4f2
This file contains documentation, in Texinfo format, for
32f4f2
@file{Default} design models used to produce the Anaconda images
32f4f2
required by major release 5 of CentOS distribution. 
87b230
32f4f2
@verbatim
32f4f2
             A                                     B                             C
32f4f2
|-----------------------|------------------------------------------------------|---|
32f4f2
trunk/Manual/Directories/trunk/Identity/Themes/Models/Default/Distro/5/Anaconda.texi
32f4f2
|-----------------------|------------------------------------------------------|---|
87b230
32f4f2
A = The documentation manual source location.
32f4f2
B = The master path we are building documentation for.
32f4f2
C = The file extension used by Texinfo documentation files.
32f4f2
@end verbatim
32f4f2
32f4f2
Here is where you, as documentor, describe construction of
32f4f2
@file{Default} design models used to produce the Anaconda images
32f4f2
required by major release 5 of CentOS distribution. In this
32f4f2
description you can include image dimensions, color information, image
32f4f2
location inside the file system of CentOS distribution, packaging and
32f4f2
similar things.
32f4f2
32f4f2
The path to this directory is considered auxiliar path of
32f4f2
@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda} master path.
87b230
87b230
@item trunk/Locales/Identity/Themes/Models/Default/Distro/5/Anaconda
87b230
87b230
This directory contains translation files, as @command{gettext}
87b230
portable objects, for Default design models used to produce the
87b230
Anaconda images used inside CentOS distribution major release 5. 
87b230
87b230
Here is where you, as translator, localize translatable strings
87b230
retrived in English language from Default design models used to
87b230
produce the Anaconda images of CentOS distribution major release 5 to
87b230
your own language. If no portable object is found here, content is
87b230
produced in English language.
87b230
74c0c0
The path to this directory is considered auxiliar to
87b230
@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda} master
87b230
path because provides the language-specific information required to
87b230
produce Anaconda Default design models in different languages.
87b230
87b230
@item trunk/Manual/Directories/trunk/Locales/Identity/Themes/Models/Default/Distro/5/Anaconda.texi
87b230
87b230
This file contains documentation, in Texinfo format, for translation
87b230
messages retrived from Default design models used to produce the
87b230
Anaconda images used inside CentOS distribution major release 5. 
87b230
87b230
Here is where you, as documentor, describe localization of Default
87b230
desing models used to produce the Anaconda images used in CentOS
87b230
distribution major release 5. In this description you can include
87b230
image dimensions, color information, image location inside
32f4f2
distribution filesystem, packaging and similar things.
87b230
74c0c0
The path to this file is considered auxiliar to
87b230
@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda} master
87b230
path because provides the language-specific information required to
87b230
produce Anaconda Default design models in different languages.
87b230
87b230
Each master path has its own auxiliar path to store their specific
87b230
documentation and whatever the artistic motifs used to produce images
87b230
be is somthing irrelevant.
87b230
87b230
@item trunk/Identity/Themes/Motifs/Flame/3/Distro/5/Anaconda
87b230
87b230
This directory contains Anaconda final images produced from Anaconda
87b230
Default design models used by CentOS distribution major release 5 and
87b230
Flame 3 artistic motif. 
87b230
87b230
Here is where you, as packager, can find the images you need to
87b230
rebrand Anaconda in CentOS distribution major release 5.
87b230
74c0c0
The path to this directory is considered auxiliar to
87b230
@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda} master
87b230
path because it provides the final images produced from Anaconda
87b230
Default design models.
87b230
87b230
@item trunk/Manual/Directories/trunk/Identity/Themes/Motifs/Flame/3/Distro/5/Anaconda.texi
87b230
87b230
This directory should contain documentation about how to implement
87b230
Anaconda component in CentOS distribution major release 5 would be.
87b230
However, since all artistic motifs are produced based on one design
87b230
model (@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda},
87b230
in this case) we may end up duplicating the same documentation in all
87b230
artistic motifs documentation entries and there is no need of that.
87b230
87b230
To avoid duplicating information, all documentation related to theme
87b230
components like Anaconda is put in design model documentation entires
87b230
(@file{trunk/Manual/Directories/trunk/Locales/Identity/Themes/Models/Default/Distro/5/Anaconda.texi}
87b230
in this case).  The only reason to create documentation entries inside
87b230
artistic motifs is to put a redirection admonition to link design
87b230
model related information.
87b230
@end table
87b230
87b230
The Anaconda component is part of CentOS Distribution visual
87b230
manifestation. Inside CentOS Distribution visual manifestation there
87b230
are other components Syslinux, Grub, Rhgb, Gdm, Kdm, Gsplash and
87b230
Ksplash that share a similar file organization to that described for
87b230
Anaconda component. The way each of these components is produced is
87b230
described in their own documentation entry.
87b230
87b230
When one master path is changed, it is required to change the related
87b230
auxiliar path related to it, too. This is required in order for master
87b230
paths to retain their relation with their auxiliar paths. This way,
87b230
automation script are able to know where to retrive translation
87b230
messages, where to store final output images and where to look for
87b230
documentation. If relation between master paths and auxiliar paths is
87b230
lost, there is no way for automation scripts to know where to retrive
87b230
the information required by for task automation.
87b230
87b230
The auxiliar paths should never be modified under no reason but to
87b230
satisfy the relation to their master paths.  Liberal change of
87b230
auxiliar paths may suppress the conceptual idea they were initially
87b230
created for; and certainly, things may stop working the way they
87b230
should.
87b0e4
87b0e4
@subsection Syncronizing path information
87b0e4
87b230
The master and auxiliar paths concept is very useful to keep
87b230
repository organized but introduce some complications.  For instance,
87b230
consider what would happen to functionalities like @code{help}, that
87b230
rely on master paths to create documentation entries, through auxiliar
87b230
paths, if one of those master paths suddenly change after the
87b230
documentation entry has been already created for it?
87b230
87b230
In such cases, functionalities like @code{help} may confuse themselves
87b230
if path information is not updated to reflect the appropriate path
87b230
relation.  Such functionalities work with master paths as reference;
87b230
if a master path is changed, the functionalities won't even note it
87b230
because they work with the last master path available in the
87b230
repository, no matter what it is. 
87b230
87b230
In the specific case of documentation (the @code{help} functionality),
87b230
the problem mentioned above provokes that older master paths, already
87b230
documented, remain inside documentation directory structures as long
87b230
as you get your hands into the documentation directory structure
87b230
(@file{trunk/Manual}) and change what must be changed to match the new
87b230
master path information.
87b230
87b230
There is no immediate way for @code{help} and similar functionalities
87b230
that use master paths as reference, to know when and how the path
87b230
information is changed inside the repository. Such information is
87b230
available only when files or directories are moved in the repository.
87b230
So, is there, at the moment of moving files, when we need to
87b230
syncronize paths information between master paths and auxiliar paths
87b230
and rename old paths to new paths inside all the files which includes
87b230
them (e.g., scalalble vector graphics, documentation files and
87b230
translation files files) and commit everything to keep the central
87b230
repository up to date.
87b0e4
87b0e4
@quotation
87b230
@strong{Warning} Even Subversion can perform some operations using
87b230
URLs, there is not support for URLs inside @command{centos-art.sh}
87b230
script.  The @command{centos-art.sh} script is designed to work with
87b230
local files inside the working copy only. If you need to work on URLs
87b230
directly, use Subversion command-line interface instead of
87b230
@command{centos-art.sh} script. 
87b0e4
@end quotation
87b0e4
87b230
File movement inside the repository is considered a repository change
87b230
and it should be recorded as such. In order for this to happen, we
87b230
need to add directories and files into the version control system to
87b230
make them part of it, commit them, perform the file movement using
87b230
version control system commands and finally commit all files related
87b230
in the operation. This configuration makes possible for everyone to
87b230
know about changes details inside the repository; and if needed,
87b230
revert or update them back to a previous revision.
87b230
87b230
Once all path information has been updated in the filesystem, it is
87b230
time to update path information inside all the files involved in the
87b230
operation. Considere what would happen to documentation entries
87b230
defined in the documentation manual when the target locations they
87b230
point to are removed from filesystem. Certainly, that would make
87b230
Texinfo to produce an error message when documentation manual is
87b230
exported to output files. Something similar could happen to scalable
87b230
vector graphics that include artistic motifs background images and
87b230
translation messages with path information inside.
87b230
87b230
So, in order to keep path information syncronized, the
87b0e4
@file{centos-art.sh} script needs to know when such changes happen, in
87b230
a way they could be noted and handled without producing errors (e.g.,
87b230
replacing old path information to new path information inside all the
87b230
files that may include any kind of path information inside).
87b0e4
74c0c0
@subsection Extending repository organization
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
87b230
The best place to find answers is in The CentOS Community (see page
87b230
@url{http://wiki.centos.org/GettingHelp}), but going there with hands
87b230
empty is not good idea. It may give the impression you don't really
87b230
care about. Instead, consider the following suggestions to find your
87b230
own comprehension in order to make your own propositions based on it.
87b230
87b230
The best advice we probably could offer you, when extending
87b230
respository structure, is to bear in mind The CentOS Project Corporate
87b230
Identity Structure (@pxref{Directories trunk Identity}). The rest is
87b230
just matter of choosing appropriate names.  
87b230
87b230
To illustrate this desition process let's consider the
87b230
@file{trunk/Identity/Themes/Motifs/TreeFlower} directory structure as
87b230
example.  It can be read as: the trunk development line of
87b230
@emph{TreeFlower} artistic motif; artistic motifs are part of themes;
87b230
and themes 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
87b230
most of time; once you've find one, that may be not a definite
87b230
solution.  There are many concepts you need to play with, in order to
87b230
find a result that match the conceptual idea you try to implement in
87b230
the new directory structure. To know which these concepts are, split
87b230
directory structures and read their documentation entry from less
87b230
specific to more specific.  The concepts used in
87b230
@file{trunk/Identity/Themes/Distro/Motifs/TreeFlower} directory
87b230
structure are described in the following documentation entries,
87b230
respectively:
87b0e4
87b0e4
@verbatim
74c0c0
centos-art help --read turnk
74c0c0
centos-art help --read turnk/Identity
74c0c0
centos-art help --read turnk/Identity/Themes
74c0c0
centos-art help --read turnk/Identity/Themes/Motifs
74c0c0
centos-art help --read turnk/Identity/Themes/Motifs/TreeFlower
87b0e4
@end verbatim
87b0e4
87b230
The @file{trunk/Identity/Themes/Motifs/TreeFlower} location has
87b230
evolved through several months of contant work and there is no certain
87b230
it won't change in the future, even it fixes quite well the concept we
87b230
are trying to implement.  Other location concepts can be found in the
87b230
same way described above, just change the directory structure to the
87b230
one you are trying to know concepts for.