diff --git a/Manual/Introduction/chapter-intro.texi b/Manual/Introduction/chapter-intro.texi index 148c82f..96fb6b2 100644 --- a/Manual/Introduction/chapter-intro.texi +++ b/Manual/Introduction/chapter-intro.texi @@ -15,21 +15,6 @@ This manual discusses the following intermedite topics: @item The CentOS Corporate Visual Style @end itemize -This manual is organized in the same way of CentOS Artwork Repository -directory structure. In the CentOS Artwork Repository we use -directories to store conceptual ideas of The CentOS Project Corporate -Visual Identity. For this manual sake, each directory in CentOS -Artwork Repository has its own documentation section to describe the -related conceptual ideas it is based on. - -This manual uses Texinfo as base documentation system. The Texinfo -documentation structure is controlled by the @code{help} functionality -of @command{centos-art.sh} script. Through this functionality you can -create documentation sections for each directory structure inside the -repository and edit those already created, as well. @xref{Directories -trunk Scripts Functions Help}, for more information on how to use the -@command{help} functionality of @command{centos-art.sh} script. - This guide assumes you have a basic understanding of your CentOS system. If you need help with CentOS, refer to the help page on the CentOS Wiki (@url{http://wiki.centos.org/Help}) for a list of diff --git a/Manual/Introduction/repo-convenctions.texi b/Manual/Introduction/repo-convenctions.texi index a36e3ba..594a977 100644 --- a/Manual/Introduction/repo-convenctions.texi +++ b/Manual/Introduction/repo-convenctions.texi @@ -143,9 +143,36 @@ design. This work line exists to describe what each directory structure inside the CentOS Artwork Repository is for and how to produce content inside -it. - -@xref{Directories trunk Manual}, for more information on documentation. +them. + +Documentation is supported by Texinfo, a documentation system that +uses a single source file to produce both online information and +printed output. + +Documentation is organized in the same way of CentOS Artwork +Repository directory structure. In the CentOS Artwork Repository we +use directories to store conceptual ideas of The CentOS Project +Corporate Visual Identity. This way, each directory in CentOS Artwork +Repository has its own documentation section to describe the related +conceptual ideas it is based on. Documentation entries related to +repository directory structure are organized in sections under +@emph{Repository Directories} chapter (@pxref{Directories}). + +The file structure of documentation related to the repository +directory structures is stored under @file{trunk/Manual/Directories} +directory structure and controlled by the @code{help} functionality of +@command{centos-art.sh} script. Using this functionality you can +create, edit and remove documentation for each directory structure +inside the repository; so 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 directory structure (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 @@ -156,7 +183,7 @@ Whatever content rendition you perform, sometimes you need to produce 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 -processed provided by @command{gettext} internationalization standard. +processes provided by @command{gettext} internationalization standard. Basically, the @command{gettext} internationalization standard consists on retriving translatable strings from source files and @@ -170,24 +197,26 @@ Objects. Since @command{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 @command{gettext} program. Most of source files +types supported by @command{gettext} program. Most of the source files supported by @command{gettext} are those from programming languages like C, C++, Bash, Python and Perl just to mention a few ones from the long list of supported formats. However, formats like SVG, XHTML and Docbook don't figure as supported in the long list of -@command{gettext} supported source files. For these formats we use the -@command{xml2po} program that come in the @file{gnome-doc-utils} -package instead. The @command{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 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 file is used just temporally to -produce the final translated XML based file. +@command{gettext} supported source files. + +To translate XML based source files like SVG, XHTML and Docbook we use +the @command{xml2po} program. This program comes with +@file{gnome-doc-utils} package and reads one XML based file to extract +translatable strings from it. As result it creates one Portable Object +that is use by @command{xml2po} itself to create a translated XML +based file 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 file is used just +temporally to produce the final translated XML based file. @quotation @strong{Tip} If you want to have your content localized inside CentOS @@ -199,12 +228,11 @@ Artwork Repository be sure to use source files supported by @subsubsection Automation -This work line exists to standardize corporate design, documentation -and localization processes and automate their production. There is no -need to repeat several tasks time after time if they can be programmed -in just one for you to execute. If you need to improve the way content -is produced, look inside automation scripts and make your improvement -there for every one to benefit. +This work line exists to standardize content production inside CentOS +Artwork Repository. There is no need to repeat several tasks time +after time if they can be programmed in just one. If you need to +improve the way content is produced, look inside automation scripts +and make your improvement there for every one to benefit. So far, we've seen a conceptual view of how image production inside CentOS Artwork Repository is performed, but how all this is @@ -224,7 +252,8 @@ Maiking the @command{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 @command{centos-art.sh} script, study it, look how to improve it and share your ideas at -@email{centos-devel@@centos.org} mailing list. +@email{centos-devel@@centos.org} mailing list or create your own new +functionalities and propose them as well. @quotation @strong{Note} As default configuration, everyone is denied from @@ -238,158 +267,322 @@ protect our work from spammers. @xref{Directories trunk Scripts}, for more information on automation. -@subsection 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 @file{trunk/Identity} location. The -@file{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 -@file{trunk/Identity/Themes/Motifs/TreeFlower/Distro} directory -structure, the @file{centos-art.sh} script removes the -@file{Motifs/TreeFlower/} directory levels from path, in order to -build the parallel directory used to retrived translations, and -pre-rendering configuration scripts required by @code{render} -functionality. - -Another example of parallel directory is the documentation structure -created by @code{manual} functionality. This time, -@file{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. +@subsection Connection between directories + +In order to produce content correctly inside CentOS Artwork +Repository, it is required that all work lines be connected somehow. +This way it could be possible to know what design models and +translation messages to use in order to produce a specific content. +This directory connection between work lines takes place through one +@emph{master path} that may have several @emph{auxiliar paths}. + +Master paths are those whose contain source files used to produce base +content and auxiliar paths provide the files used to modify the +production of such base content. For example, when images are produced +from source files, the directory structure that holds source files is +considered the master path and all other directory structures are +considered auxiliar paths. There are auxiliar paths to store images, +translation messages and documentation. + +Auxiliar paths take their structure from one unique parent path. +Inside CentOS Artwork Repository, this unique parent path is under +@file{trunk/Identity} directory structure. The @file{trunk/Identity} +location must be considered as a reference for whatever information +you plan to create inside the repository. For example, all the +possible paths related to brands component production, are: + +@table @file +@item trunk/Identity/Models/Brands + +This is the master path where source files used to produce brands are +stored in. + +@item trunk/Locales/Identity/Models/Brands + +This is the auxiliar path where translation messages used to produce +brands, if there is any at all, are stored in. + +@item trunk/Manual/Directories/trunk/Locales/Identity/Models/Brands.texi + +This is the auxiliar path where documentation about translation +messages, used to produce brands are stored in. + +@item trunk/Identity/Images/Brands + +This is the auxiliar path where output images produced as result of +rendition are stored in. + +@item trunk/Manual/Directories/trunk/Identity/Models/Brands.texi + +This is the auxiliar path where documentation about brand design is +stored in. This is, how brands are constructed, the color information, +the proportions, etc. Notice that it points to a regular file, not a +directory as other auxilar path use to do. + +@item trunk/Manual/Directories/trunk/Identity/Images/Brands.texi + +This is the auxiliar path where documentation about brand +implementation. This is, how the brand is applied and how it cannot be +applied in each different visual manifestation. Notice that it points +to a regular file, not a directory as other auxiliar path use to do. +@end table + +The configuration described above for organizing brand component +inside the repository is the one used by direct rendition and can be +used as reference to organize other components inside the repository +that are produced through direct rendition too. Just change the +component name from brands to that one you want to add without +changing the path structure around it. + +The file organization used by theme rendition, however, is a bit +different from that used by direct rendition. In theme rendition, both +master paths and auxiliar paths are built dynamically based on the +design model and the artistic motifs you specify at rendition time. As +a mnemotechnic resource, consider theme rendition as two independent +lists, one list of design models and one list of artistic motifs, +which are arbitrary combined among themselves in order to render +images. For example, consider the organization used to produce +Anaconda images to CentOS distribution major release 5 from Default +design model and Flame artistic motif: + +@table @file +@item trunk/Identity/Themes/Models/Default/Distro/5/Anaconda + +This directory contains source files used to produce Anaconda images +for CentOS distribution major release 5 using Default design models. + +Here is where you, as graphic designers, define Default design models for +Anaconda images used in CentOS distribution major release 5. + +The path to this directory is considered master because it contains +the most critical information (i.e., the information that can't be +absent) required to produce Anaconda images used inside CentOS +distribution major release 5. + +@item trunk/Manual/Directories/trunk/Identity/Themes/Models/Default/Distro/5/Anaconda.texi + +This file contains documentation, in Texinfo format, for Default +design models used to produce the Anaconda images used inside CentOS +distribution major release 5. + +Here is where you, as documentor, describe construction of Default +desing models used to produce the Anaconda images for CentOS +distribution major release 5. In this description you can include +image dimensions, color information, image location inside +distribution filesystem, image packaging and similar things. + +The path to this file is considered auxiliar for +@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda} master +path because provides the description required to let everyone know +how to build Default design models used to produce Anaconda images +required by CentOS distribution major release 5. + +@item trunk/Locales/Identity/Themes/Models/Default/Distro/5/Anaconda + +This directory contains translation files, as @command{gettext} +portable objects, for Default design models used to produce the +Anaconda images used inside CentOS distribution major release 5. + +Here is where you, as translator, localize translatable strings +retrived in English language from Default design models used to +produce the Anaconda images of CentOS distribution major release 5 to +your own language. If no portable object is found here, content is +produced in English language. + +The path to this directory is considered auxiliar for +@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda} master +path because provides the language-specific information required to +produce Anaconda Default design models in different languages. + +@item trunk/Manual/Directories/trunk/Locales/Identity/Themes/Models/Default/Distro/5/Anaconda.texi + +This file contains documentation, in Texinfo format, for translation +messages retrived from Default design models used to produce the +Anaconda images used inside CentOS distribution major release 5. + +Here is where you, as documentor, describe localization of Default +desing models used to produce the Anaconda images used in CentOS +distribution major release 5. In this description you can include +image dimensions, color information, image location inside +distribution filesystem, image packaging and similar things. + +The path to this file is considered auxiliar for +@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda} master +path because provides the language-specific information required to +produce Anaconda Default design models in different languages. + +Each master path has its own auxiliar path to store their specific +documentation and whatever the artistic motifs used to produce images +be is somthing irrelevant. + +@item trunk/Identity/Themes/Motifs/Flame/3/Distro/5/Anaconda + +This directory contains Anaconda final images produced from Anaconda +Default design models used by CentOS distribution major release 5 and +Flame 3 artistic motif. + +Here is where you, as packager, can find the images you need to +rebrand Anaconda in CentOS distribution major release 5. + +The path to this directory is considered auxiliar for +@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda} master +path because it provides the final images produced from Anaconda +Default design models. + +@item trunk/Manual/Directories/trunk/Identity/Themes/Motifs/Flame/3/Distro/5/Anaconda.texi + +This directory should contain documentation about how to implement +Anaconda component in CentOS distribution major release 5 would be. +However, since all artistic motifs are produced based on one design +model (@file{trunk/Identity/Themes/Models/Default/Distro/5/Anaconda}, +in this case) we may end up duplicating the same documentation in all +artistic motifs documentation entries and there is no need of that. + +To avoid duplicating information, all documentation related to theme +components like Anaconda is put in design model documentation entires +(@file{trunk/Manual/Directories/trunk/Locales/Identity/Themes/Models/Default/Distro/5/Anaconda.texi} +in this case). The only reason to create documentation entries inside +artistic motifs is to put a redirection admonition to link design +model related information. +@end table + +The Anaconda component is part of CentOS Distribution visual +manifestation. Inside CentOS Distribution visual manifestation there +are other components Syslinux, Grub, Rhgb, Gdm, Kdm, Gsplash and +Ksplash that share a similar file organization to that described 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 to change the related +auxiliar path related to it, 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 by for task automation. + +The auxiliar paths should never be modified under no reason but to +satisfy the relation to their master paths. 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 -Parallel directories are very useful to keep repository organized but -introduce some complications. For instance, consider what would -happen to functionalities like @code{manual} (@samp{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 @code{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 @code{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 (@file{trunk/Manuals}) and change what must be -changed to match the new parent directory structure. - -There is no immediate way for @code{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. +The master and auxiliar paths concept is very useful to keep +repository organized but introduce some complications. For instance, +consider what would happen to functionalities like @code{help}, that +rely on master paths to create documentation entries, through auxiliar +paths, if one of those master paths suddenly change after the +documentation entry has been already created for it? + +In such cases, functionalities like @code{help} may confuse themselves +if path information is not updated to reflect the appropriate path +relation. Such functionalities work with master paths as reference; +if a master path is changed, the functionalities won't even note it +because they work with the last master path available in the +repository, no matter what it is. + +In the specific case of documentation (the @code{help} functionality), +the problem mentioned above provokes that older master paths, already +documented, remain inside documentation directory structures as long +as you get your hands into the documentation directory structure +(@file{trunk/Manual}) and change what must be changed to match the new +master path information. + +There is no immediate way for @code{help} and similar functionalities +that use master paths as reference, to know when and how the path +information is changed inside the repository. Such information is +available only when files or directories are moved in the repository. +So, is there, at the moment of moving files, when we need to +syncronize paths information between master paths and auxiliar paths +and rename old paths to new paths inside all the files which includes +them (e.g., scalalble vector graphics, documentation files and +translation files files) and commit everything to keep the central +repository up to date. @quotation -@strong{Warning} There is not support for URL reference inside -@file{centos-art.sh} script. The @file{centos-art.sh} script is -designed to work with local files inside the working copy only. +@strong{Warning} Even Subversion can perform some operations using +URLs, there is not support for URLs 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 work on URLs +directly, use Subversion command-line interface instead of +@command{centos-art.sh} script. @end quotation -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 +File movement inside the repository is considered a repository change +and it should be recorded as such. In order for this to happen, we +need to add directories and files into the version control system to +make them part of it, commit them, perform the file movement using +version control system commands and finally commit all files related +in the operation. 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. + +Once all path information has been updated in the filesystem, it is +time to update path information inside all the files involved in the +operation. Considere what would happen to documentation entries +defined in the documentation manual when the target locations they +point to are removed from filesystem. Certainly, that would make +Texinfo to produce an error message when documentation manual is +exported to output files. Something similar could happen to scalable +vector graphics that include artistic motifs background images and +translation messages with path information inside. + +So, in order to keep path information syncronized, the @file{centos-art.sh} script needs to know when such changes happen, in -a way they could be noted and handled without producing errors. +a way they could be noted and handled without producing errors (e.g., +replacing old path information to new path information inside all the +files that may include any kind of path information inside). -@subsection What is the right place to store it? +@subsection Extending repository structure 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: -@url{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 (@pxref{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 -@file{trunk/Identity/Themes/Motifs/TreeFlower} directory as example. -It is the trunk development line of @emph{TreeFlower} artistic motif. -Artistic motifs are considered part of themes, which in turn are -considered part of CentOS corporate visual identity. +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. + +The best advice we probably could offer you, when extending +respository structure, is to bear in mind The CentOS Project Corporate +Identity Structure (@pxref{Directories trunk Identity}). The rest is +just matter of choosing appropriate names. + +To illustrate this desition process let's consider the +@file{trunk/Identity/Themes/Motifs/TreeFlower} directory structure as +example. It can be read as: the trunk development line of +@emph{TreeFlower} artistic motif; artistic motifs are part of themes; +and themes 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 @file{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 -@file{trunk/Identity/Themes/Distro/Motifs/TreeFlower} location are -described in the following commands, respectively: +most of time; once you've find one, that may be not a definite +solution. There are many concepts you need to play with, in order to +find a result that match the conceptual idea you try to implement in +the new directory structure. To know which these concepts are, split +directory structures and read their documentation entry from less +specific to more specific. The concepts used in +@file{trunk/Identity/Themes/Distro/Motifs/TreeFlower} directory +structure are described in the following documentation entries, +respectively: @verbatim -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/ +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/ @end verbatim -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. +The @file{trunk/Identity/Themes/Motifs/TreeFlower} location has +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. Other location concepts can be found in the +same way described above, just change the directory structure to the +one you are trying to know concepts for. diff --git a/Manual/repository.info.bz2 b/Manual/repository.info.bz2 index f33cd67..510dcab 100644 Binary files a/Manual/repository.info.bz2 and b/Manual/repository.info.bz2 differ diff --git a/Manual/repository.pdf b/Manual/repository.pdf index c3e9de7..ff96a2f 100644 Binary files a/Manual/repository.pdf and b/Manual/repository.pdf differ diff --git a/Manual/repository.txt.bz2 b/Manual/repository.txt.bz2 index bf01f75..899bedc 100644 Binary files a/Manual/repository.txt.bz2 and b/Manual/repository.txt.bz2 differ diff --git a/Manual/repository.xhtml.tar.bz2 b/Manual/repository.xhtml.tar.bz2 index 6d93d89..235a4c6 100644 Binary files a/Manual/repository.xhtml.tar.bz2 and b/Manual/repository.xhtml.tar.bz2 differ diff --git a/Manual/repository.xml b/Manual/repository.xml index 40e8d98..ac98b5d 100644 --- a/Manual/repository.xml +++ b/Manual/repository.xml @@ -73,8 +73,6 @@ The CentOS Corporate Visual Style - This manual is organized in the same way of CentOS Artwork Repository directory structure. In the CentOS Artwork Repository we use directories to store conceptual ideas of The CentOS Project Corporate Visual Identity. For this manual sake, each directory in CentOS Artwork Repository has its own documentation section to describe the related conceptual ideas it is based on. - This manual uses Texinfo as base documentation system. The Texinfo documentation structure is controlled by the help functionality of centos-art.sh script. Through this functionality you can create documentation sections for each directory structure inside the repository and edit those already created, as well. See Directories trunk Scripts Functions Help, for more information on how to use the help functionality of centos-art.sh script. This guide assumes you have a basic understanding of your CentOS system. If you need help with CentOS, refer to the help page on the CentOS Wiki (http://wiki.centos.org/Help) for a list of different places you can find help. @@ -329,16 +327,20 @@ manual_deleteCrossReferences.sh manual_searchIndex.sh Documentation - This work line exists to describe what each directory structure inside the CentOS Artwork Repository is for and how to produce content inside it. + This work line exists to describe what each directory structure inside the CentOS Artwork Repository is for and how to produce content inside them. + Documentation is supported by Texinfo, a documentation system that uses a single source file to produce both online information and printed output. + Documentation is organized in the same way of CentOS Artwork Repository directory structure. In the CentOS Artwork Repository we use directories to store conceptual ideas of The CentOS Project Corporate Visual Identity. This way, each directory in CentOS Artwork Repository has its own documentation section to describe the related conceptual ideas it is based on. Documentation entries related to repository directory structure are organized in sections under Repository Directories chapter (see Directories). + The file structure of documentation related to the repository directory structures is stored under trunk/Manual/Directories directory structure and controlled by the help functionality of centos-art.sh script. Using this functionality you can create, edit and remove documentation for each directory structure inside the repository; so 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 directory structure (e.g., Preface, Introduction and similar) you need to do it manually, there is no functionality to automate such process yet. See Directories trunk Manual, for more information on documentation. Localization This work line exists to localize corporate design and documentation source files, so they can be produced in different languages. - Whatever content rendition you perform, sometimes you need to produce 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 processed provided by gettext internationalization standard. + Whatever content rendition you perform, sometimes you need to produce 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 processes provided by gettext internationalization standard. Basically, the gettext internationalization standard consists on retriving translatable strings from source files and creating Portable Objects and Machine Objects. Portable Objects contain the information used by translators to do their work, they are files 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 ones 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 the 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 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 xml2po, the Machine Object file is used just temporally to produce the final translated XML based file. + 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 the source files supported by gettext are those from programming languages like C, C++, Bash, Python and Perl just to mention a few ones 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. + To translate XML based source files like SVG, XHTML and Docbook we use the xml2po program. This program comes with gnome-doc-utils package and reads one XML based file to extract translatable strings from it. As result it creates one Portable Object that is use by xml2po itself to create a translated XML based file 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 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. @@ -347,10 +349,10 @@ manual_deleteCrossReferences.sh manual_searchIndex.sh Automation - This work line exists to standardize corporate design, documentation and localization processes and automate their production. There is no need to repeat several tasks time after time if they can be programmed in just one for you to execute. If you need to improve the way content is produced, look inside automation scripts and make your improvement there for every one to benefit. + This work line exists to standardize content production inside CentOS Artwork Repository. There is no need to repeat several tasks time after time if they can be programmed in just one. If you need to improve the way content is produced, look inside automation scripts and make your improvement there for every one to benefit. 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. + 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 or create your own new functionalities and propose them as well. 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. @@ -359,43 +361,134 @@ manual_deleteCrossReferences.sh manual_searchIndex.sh - 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. + Connection between directories + In order to produce content correctly inside CentOS Artwork Repository, it is required that all work lines be connected somehow. This way it could be possible to know what design models and translation messages to use in order to produce a specific content. This directory connection between work lines takes place through one master path that may have several auxiliar paths. + Master paths are those whose contain source files used to produce base content and auxiliar paths provide the files used to modify the production of such base content. For example, when images are produced from source files, the directory structure that holds source files is considered the master path and all other directory structures are considered auxiliar paths. There are auxiliar paths to store images, translation messages and documentation. + Auxiliar paths take their structure from one unique parent path. Inside CentOS Artwork Repository, this unique parent path is under trunk/Identity directory structure. The trunk/Identity location must be considered as a reference for whatever information you plan to create inside the repository. For example, all the possible paths related to brands component production, are: + + + trunk/Identity/Models/Brands + + This is the master path where source files used to produce brands are stored in. + + + + trunk/Locales/Identity/Models/Brands + + This is the auxiliar path where translation messages used to produce brands, if there is any at all, are stored in. + + + + trunk/Manual/Directories/trunk/Locales/Identity/Models/Brands.texi + + This is the auxiliar path where documentation about translation messages, used to produce brands are stored in. + + + + trunk/Identity/Images/Brands + + This is the auxiliar path where output images produced as result of rendition are stored in. + + + + trunk/Manual/Directories/trunk/Identity/Models/Brands.texi + + This is the auxiliar path where documentation about brand design is stored in. This is, how brands are constructed, the color information, the proportions, etc. Notice that it points to a regular file, not a directory as other auxilar path use to do. + + + + trunk/Manual/Directories/trunk/Identity/Images/Brands.texi + + This is the auxiliar path where documentation about brand implementation. This is, how the brand is applied and how it cannot be applied in each different visual manifestation. Notice that it points to a regular file, not a directory as other auxiliar path use to do. + + +
+ The configuration described above for organizing brand component inside the repository is the one used by direct rendition and can be used as reference to organize other components inside the repository that are produced through direct rendition too. Just change the component name from brands to that one you want to add without changing the path structure around it. + The file organization used by theme rendition, however, is a bit different from that used by direct rendition. In theme rendition, both master paths and auxiliar paths are built dynamically based on the design model and the artistic motifs you specify at rendition time. As a mnemotechnic resource, consider theme rendition as two independent lists, one list of design models and one list of artistic motifs, which are arbitrary combined among themselves in order to render images. For example, consider the organization used to produce Anaconda images to CentOS distribution major release 5 from Default design model and Flame artistic motif: + + + trunk/Identity/Themes/Models/Default/Distro/5/Anaconda + + This directory contains source files used to produce Anaconda images for CentOS distribution major release 5 using Default design models. + Here is where you, as graphic designers, define Default design models for Anaconda images used in CentOS distribution major release 5. + The path to this directory is considered master because it contains the most critical information (i.e., the information that can't be absent) required to produce Anaconda images used inside CentOS distribution major release 5. + + + + trunk/Manual/Directories/trunk/Identity/Themes/Models/Default/Distro/5/Anaconda.texi + + This file contains documentation, in Texinfo format, for Default design models used to produce the Anaconda images used inside CentOS distribution major release 5. + Here is where you, as documentor, describe construction of Default desing models used to produce the Anaconda images for CentOS distribution major release 5. In this description you can include image dimensions, color information, image location inside distribution filesystem, image packaging and similar things. + The path to this file is considered auxiliar for trunk/Identity/Themes/Models/Default/Distro/5/Anaconda master path because provides the description required to let everyone know how to build Default design models used to produce Anaconda images required by CentOS distribution major release 5. + + + + trunk/Locales/Identity/Themes/Models/Default/Distro/5/Anaconda + + This directory contains translation files, as gettext portable objects, for Default design models used to produce the Anaconda images used inside CentOS distribution major release 5. + Here is where you, as translator, localize translatable strings retrived in English language from Default design models used to produce the Anaconda images of CentOS distribution major release 5 to your own language. If no portable object is found here, content is produced in English language. + The path to this directory is considered auxiliar for trunk/Identity/Themes/Models/Default/Distro/5/Anaconda master path because provides the language-specific information required to produce Anaconda Default design models in different languages. + + + + trunk/Manual/Directories/trunk/Locales/Identity/Themes/Models/Default/Distro/5/Anaconda.texi + + This file contains documentation, in Texinfo format, for translation messages retrived from Default design models used to produce the Anaconda images used inside CentOS distribution major release 5. + Here is where you, as documentor, describe localization of Default desing models used to produce the Anaconda images used in CentOS distribution major release 5. In this description you can include image dimensions, color information, image location inside distribution filesystem, image packaging and similar things. + The path to this file is considered auxiliar for trunk/Identity/Themes/Models/Default/Distro/5/Anaconda master path because provides the language-specific information required to produce Anaconda Default design models in different languages. + Each master path has its own auxiliar path to store their specific documentation and whatever the artistic motifs used to produce images be is somthing irrelevant. + + + + trunk/Identity/Themes/Motifs/Flame/3/Distro/5/Anaconda + + This directory contains Anaconda final images produced from Anaconda Default design models used by CentOS distribution major release 5 and Flame 3 artistic motif. + Here is where you, as packager, can find the images you need to rebrand Anaconda in CentOS distribution major release 5. + The path to this directory is considered auxiliar for trunk/Identity/Themes/Models/Default/Distro/5/Anaconda master path because it provides the final images produced from Anaconda Default design models. + + + + trunk/Manual/Directories/trunk/Identity/Themes/Motifs/Flame/3/Distro/5/Anaconda.texi + + This directory should contain documentation about how to implement Anaconda component in CentOS distribution major release 5 would be. However, since all artistic motifs are produced based on one design model (trunk/Identity/Themes/Models/Default/Distro/5/Anaconda, in this case) we may end up duplicating the same documentation in all artistic motifs documentation entries and there is no need of that. + To avoid duplicating information, all documentation related to theme components like Anaconda is put in design model documentation entires (trunk/Manual/Directories/trunk/Locales/Identity/Themes/Models/Default/Distro/5/Anaconda.texi in this case). The only reason to create documentation entries inside artistic motifs is to put a redirection admonition to link design model related information. + + +
+ The Anaconda component is part of CentOS Distribution visual manifestation. Inside CentOS Distribution visual manifestation there are other components Syslinux, Grub, Rhgb, Gdm, Kdm, Gsplash and Ksplash that share a similar file organization to that described 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 to change the related auxiliar path related to it, 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 by for task automation. + The auxiliar paths should never be modified under no reason but to satisfy the relation to their master paths. 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.
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. + The master and auxiliar paths concept is very useful to keep repository organized but introduce some complications. For instance, consider what would happen to functionalities like help, that rely on master paths to create documentation entries, through auxiliar paths, if one of those master paths suddenly change after the documentation entry has been already created for it? + In such cases, functionalities like help may confuse themselves if path information is not updated to reflect the appropriate path relation. Such functionalities work with master paths as reference; if a master path is changed, the functionalities won't even note it because they work with the last master path available in the repository, no matter what it is. + In the specific case of documentation (the help functionality), the problem mentioned above provokes that older master paths, already documented, remain inside documentation directory structures as long as you get your hands into the documentation directory structure (trunk/Manual) and change what must be changed to match the new master path information. + There is no immediate way for help and similar functionalities that use master paths as reference, to know when and how the path information is changed inside the repository. Such information is available only when files or directories are moved in the repository. So, is there, at the moment of moving files, when we need to syncronize paths information between master paths and auxiliar paths and rename old paths to new paths inside all the files which includes them (e.g., scalalble vector graphics, documentation files and translation files files) and commit everything to keep the central repository up to date. - 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. + Warning Even Subversion can perform some operations using URLs, there is not support for URLs inside centos-art.sh script. The centos-art.sh script is designed to work with local files inside the working copy only. If you need to work on URLs directly, use Subversion command-line interface instead of centos-art.sh script. - 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. + File movement inside the repository is considered a repository change and it should be recorded as such. In order for this to happen, we need to add directories and files into the version control system to make them part of it, commit them, perform the file movement using version control system commands and finally commit all files related in the operation. 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. + Once all path information has been updated in the filesystem, it is time to update path information inside all the files involved in the operation. Considere what would happen to documentation entries defined in the documentation manual when the target locations they point to are removed from filesystem. Certainly, that would make Texinfo to produce an error message when documentation manual is exported to output files. Something similar could happen to scalable vector graphics that include artistic motifs background images and translation messages with path information inside. + So, in order to keep path information syncronized, the centos-art.sh script needs to know when such changes happen, in a way they could be noted and handled without producing errors (e.g., replacing old path information to new path information inside all the files that may include any kind of path information inside). - What is the right place to store it? + Extending repository structure 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: + The best place to find answers is in The CentOS Community (see page 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. + The best advice we probably could offer you, when extending respository structure, is to bear in mind The CentOS Project Corporate Identity Structure (see Directories trunk Identity). The rest is just matter of choosing appropriate names. + To illustrate this desition process let's consider the trunk/Identity/Themes/Motifs/TreeFlower directory structure as example. It can be read as: the trunk development line of TreeFlower artistic motif; artistic motifs are part of themes; and themes 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 one, that may be not a definite solution. There are many concepts you need to play with, in order to find a result that match the conceptual idea you try to implement in the new directory structure. To know which these concepts are, split directory structures and read their documentation entry from less specific to more specific. The concepts used in trunk/Identity/Themes/Distro/Motifs/TreeFlower directory structure are described in the following documentation entries, respectively: - 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. + The trunk/Identity/Themes/Motifs/TreeFlower location has 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. Other location concepts can be found in the same way described above, just change the directory structure to the one you are trying to know concepts for.