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

This section describes the organization of files and directories inside the CentOS Artwork Repository. The repository layout provides the standard backend required for automation scripts to work correctly. If such layout changes unexpectedly, automation scripts may confuse themselves and stop doing what you may expect from them to do.

As convenction, inside CentOS Artwork Repository, files and directories related to CentOS corporate visual identity are organized under three top level directories named: trunk/, branches/, and tags/.

The trunk/ directory (see Directories trunk) organizes the main development line of CentOS corporate visual identity. Inside trunk/ directory structure, the CentOS corporate visual identity concepts are implemented using directories.  There is one directory level for each relevant concept inside the repository. The trunk/ directory structure is mainly used to perform development tasks related to CentOS corporate visual identity.

The branches/ directory (see Directories branches) oranizes parallel development lines to trunk/ directory. The branches/ directory is used to set points in time where develpment lines are devided one from another taking separte and idependent lives that share a common past from the point they were devided on. The branches/ directory is mainly used to perform quality assurance tasks related to CentOS corporate visual identity.

The tags/ directory (see Directories tags) organizes parallel frozen lines to branches/ directory.  The parallel frozen lines are immutable, nothing change inside them once they has been created.  The tags/ directory is mainly used to publish final releases of CentOS corporate visual identity.

The CentOS Artwork Repository layout is firmly grounded on a Subversion base.  Subversion (http://subversion.tigris.org) is a version control system, which allows you to keep old versions of files and directories (usually source code), keep a log of who, when, and why changes occurred, etc., like CVS, RCS or SCCS.  Subversion keeps a single copy of the master sources.  This copy  is called the source ``repository''; it contains all the information to permit extracting previous versions of those files at any time.

Repository file names
---------------------

Repository name convenctions are applied to files and directories inside the repository layout. As convenction, file names are all written in lowercase (01-welcome.png, splash.png, anaconda_header.png, etc.) and directory names are all written capitalized (e.g., Identity, Themes, Motifs, TreeFlower, etc.).

Repository name convenctions are implemented inside the cli_getRepoName function of centos-art.sh script. With cli_getRepoName function the amount of commands and convenctions to remember are reduced and concentrated in just one single place to look for fixes and improvements.

Repository work flow
--------------------

As repository work flow we understand a serie of normalized steps used to produce contents inside CentOS Artwork Repository. There are two relevant components inside the repository that we need to normalize work flow for, they are: content rendition, content localization and programming.

Content rendition
.................

The CentOS Project Corporate Identity, in part, is made of several visual manifestations. These visual manifestations implement the Corporate Identity by means of images placed in key visible areas of each manifestation visual space. As work flow to produce these images, we decompose images in design models and artistic motifs. Design models provide the image structure (i.e., dimension, translation markers, common designs, etc.) and artistic motifs the visual style (i.e., the background information provide the look and feel).

Design models are created for each visual manifestation the CentOS Project is made of. This way we describe the visual manifestation and provide a template system for it where several artistic motifs can be applied. Artistic motifs are created with design models in mind, not the visual manifestation such design models are applied to.

The combination of both design models and artistic motifs is what we know as Theme. Themes let us create several design models and several background images apart one another that can be later combined albitrarily one another to provide a flexible way of producing images for different visual manifestations.

In addition to themes, you can find another way of image production, a more direct way of image production where there is no artistic motif at all, but design models only. This configuration is useful to produce content that don't need specific background information like icons and illustrations used in documentation.

Content localization
....................

Whatever content rendition you perform, sometimes you need to produce the content in different languages. Production of content in different languages is known as localization or l10n for short.  Inside CentOS Artwork Repository, content localization is performed using the gettext standard internationalization process as base.

Basically, the gettext standard internationalization process consists on retriving translatable strings from source files and create Portable Objects and Machine Objects. Portable Objects contain the information translators used to do their work, it is file that can be edited by any convenctional text editor like Vim, Emacs or Nano. On the other hand, Machine Objects are produced to be machine-redable as its name implies, and are produced from Portable Objects.

Since gettext needs to extract translatable strings form source files in order to let translators to localize them, the types of source files we use inside the repository are limitted to the file types supported by gettext program. Most of source files supported by gettext are those from programming languages like C, C++, Bash, Python and Perl just to mention a few from the long list of supported formats. However, formats like SVG, XHTML and Docbook don't figure as supported in the long list of gettext supported source files. For these formats we use the xml2po program that come in gnome-doc-utils package instead.  The xml2po program reads one XML based file and extracts translatable strings from it and creates one Portable Object that is use to create a translated XML based file with the same definition of the source file 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 don't appear as art of magic---). When using xml2po, the Machine Object file is used just temporally to produce the final translated XML based file.

     Tip If you want to have your content localized inside CentOS Artwork Repository be sure to use source files supported by gettext and xml2po programs.

Programming
...........

So far, we've seen a conceptual view of how image production inside CentOS Artwork Repository is performed, but how all this is implemented, what is the practical view?

The practical view can be found through centos-art.sh script, a bash script specially designed to automate most frequent tasks inside CentOS Artwork Repository. The centos-art.sh script is stored in trunk/Scripts directory structure and is there where the main development for centos-art.sh script takes place. Basically, the centos-art.sh script is divided in several functionalities that perform specific tasks inside the repository. Such functionalities relay on repository organization to work as expected.

Maiking the centos-art.sh script to automate tasks is the only possible work flow that I can think about right now. If you are a programmer, take a functionality from centos-art.sh script, study it, look how to improve it and share your ideas at centos-devel@centos.org mailing list.

     Note As default configuration, everyone is denied from committing changes up to CentOS Artwork Repository. In order to gain commit rights, you need to prove your interest in contributing and maintaining that contribution.  Otherwise, if you only want to comment your ideas, the centos-devel@centos.org mailing list exists for you to manifest yourself. This restrictions are necessary to protect our work from spammers.

Parallel directories
--------------------

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

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

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

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

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

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

Syncronizing path information
-----------------------------

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

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

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

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

     Warning There is not support for URL reference inside centos-art.sh script.  The centos-art.sh script is designed to work with local files inside the working copy only.

As CentOS Artwork Repository is built over a version control system, file movements inside the repository are considered repository changes. In order for these repository changes to be versioned, we need to, firstly, add changes into the version control system, commit them, and later, perform movement actions using version control system commands. This configuration makes possible for everyone to know about changes details inside the repository; and if needed, revert or update them back to a previous revision.

Finally, once all path information has been corrected, it is time to take care of information inside the files. For instance, considere what would happen if you make a reference to a documentation node, and later the documentation node you refere to is deleted. That would make Texinfo to produce error messages at export time. So, the centos-art.sh script needs to know when such changes happen, in a way they could be noted and handled without producing errors.

What is the right place to store it?
------------------------------------

Occasionly, you may find that new corporate visual identity components need to be added to the repository. If that is your case, the first question you need to ask yourself, before start to create directories blindly all over, is: What is the right place to store it?

The CentOS Community different free support vains (see: http://wiki.centos.org/GettingHelp) are the best place to find answers to your question, but going there with hands empty is not good idea. It may give the impression you don't really care about. Instead, consider the following suggestions to find your own comprehension and so, make your propositions based on it.

When we are looking for the correct place to store new files, to bear in mind the corporate visual identity structure used inside the CentOS Artwork Repository (see Directories trunk Identity) would be probaly the best advice we could offer, the rest is just matter of choosing appropriate names.  To illustrate this desition process let's consider the trunk/Identity/Themes/Motifs/TreeFlower directory as example. It is the trunk development line of TreeFlower artistic motif. Artistic motifs are considered part of themes, which in turn are considered part of CentOS corporate visual identity.

When building parent directory structures, you may find that reaching an acceptable location may take some time, and as it uses to happen most of time; once you've find it, that may be not a definite solution.  There are many concepts that you need to play with, in order to find a result that match the conceptual idea you try to implement in the new directory location. To know which these concepts are, split the location in words and read its documentation entry from less specific to more specific.

For example, the trunk/Identity/Themes/Motifs/TreeFlower location evolved through several months of contant work and there is no certain it won't change in the future, even it fixes quite well the concept we are trying to implement.  The concepts used in trunk/Identity/Themes/Distro/Motifs/TreeFlower location are described in the following commands, respectively:

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

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