diff --git a/Identity/Manual/Introduction/authors.texi b/Identity/Manual/Introduction/authors.texi index 89df7c0..d1565b3 100755 --- a/Identity/Manual/Introduction/authors.texi +++ b/Identity/Manual/Introduction/authors.texi @@ -9,7 +9,7 @@ Infrastructure, Packaging. @item Ralph Angenendt -Infrastructure, Packaging. +Infrastructure, Packaging, Documentation. @item Alain Reguera Delgado diff --git a/Identity/Manual/Introduction/chapter-menu.texi b/Identity/Manual/Introduction/chapter-menu.texi index 8bff50a..39781c3 100644 --- a/Identity/Manual/Introduction/chapter-menu.texi +++ b/Identity/Manual/Introduction/chapter-menu.texi @@ -2,7 +2,7 @@ * History:: * Authors:: * Copying Conditions:: -* Convenctions:: -* Layout:: +* Document Convenctions:: +* Repository Convenctions:: * Feedback:: @end menu diff --git a/Identity/Manual/Introduction/chapter-nodes.texi b/Identity/Manual/Introduction/chapter-nodes.texi index 0938433..3501296 100644 --- a/Identity/Manual/Introduction/chapter-nodes.texi +++ b/Identity/Manual/Introduction/chapter-nodes.texi @@ -13,15 +13,15 @@ @cindex Copying conditions @include Introduction/copying.texi -@node Convenctions +@node Document Convenctions @section Document Convenctions @cindex Document convenctions -@include Introduction/convenctions.texi +@include Introduction/doc-convenctions.texi -@node Layout -@section Repository Layout -@cindex Repository layout -@include Introduction/layout.texi +@node Repository Convenctions +@section Repository Convenctions +@cindex Repository convenctions +@include Introduction/repo-convenctions.texi @node Feedback @section Send in Your Feedback diff --git a/Identity/Manual/Introduction/convenctions.texi b/Identity/Manual/Introduction/convenctions.texi deleted file mode 100644 index f74c31a..0000000 --- a/Identity/Manual/Introduction/convenctions.texi +++ /dev/null @@ -1,109 +0,0 @@ -In this manual the personal pronoun @emph{we} is used to repesent -@emph{The CentOS Artwork SIG}. This is, the group of persons building -the CentOS Artwork Repository. - -In this manual, certain words are represented in different fonts, -typefaces, sizes, and weights. This highlighting is systematic; -different words are represented in the same style to indicate their -inclusion in a specific category. The types of words that are -represented this way include the following: - -@table @command -@item command - -Linux commands (and other operating system commands, when used) are -represented this way. This style should indicate to you that you can -type the word or phrase on the command line and press Enter to invoke -a command. Sometimes a command contains words that would be displayed -in a different style on their own (such as file names). In these -cases, they are considered to be part of the command, so the entire -phrase is displayed as a command. For example: - -Use the @command{centos-art identity --render='path/to/dir'} command -to produce contents inside the @file{trunk/Identity} directory -structure. -@end table - -@table @file -@item file name - -File names, directory names, paths, and RPM package names are -represented this way. This style indicates that a particular file or -directory exists with that name on your system. Examples: - -The @file{init.sh} file in @file{trunk/Scripts/Bash/Cli/} directory is -the initialization script, written in Bash, used to automate most of -tasks in the repository. - -The @command{centos-art} command uses the @file{ImageMagick} RPM -package to convert images from PNG format to other formats. -@end table - -@table @key -@item @key{key} - -A key on the keyboard is shown in this style. For example: - -To use @key{TAB} completion to list particular files in a directory, -type @command{ls}, then a character, and finally the Tab key. Your -terminal displays the list of files in the working directory that -begin with that character. -@end table - -@table @key -@item @key{key-combination} -A combination of keystrokes is represented in this way. For example: - -The @key{Ctrl-Alt-Backspace} key combination exits your graphical -session and returns you to the graphical login screen or the console. -@end table - -@table @code -@item @code{computer output} - -Text in this style indicates text displayed to a shell prompt such as -error messages and responses to commands. For example: - -The @command{ls} command displays the contents of a directory. For example: - -@verbatim -Config manual_renameEntry.sh -manual_copyEntry.sh manual_restoreCrossReferences.sh -manual_deleteCrossReferences.sh manual_searchIndex.sh -@end verbatim - -The output returned in response to the command (in this case, the -contents of the directory) is shown in this style. -@end table - -Additionally, we use several different strategies to draw your -attention to certain pieces of information. In order of urgency, these -items are marked as a note, tip, important, caution, or warning. For -example: - -@quotation -@strong{Note} Remember that Linux is case sensitive. In other words, a -rose is not a ROSE is not a rOsE. -@end quotation - -@quotation -@strong{Tip} The directory @file{/usr/share/doc/} contains additional -documentation for packages installed on your system. -@end quotation - -@quotation -@strong{Important} If you modify the DHCP configuration file, the -changes do not take effect until you restart the DHCP daemon. -@end quotation - -@quotation -@strong{Caution} Do not perform routine tasks as root --- use a -regular user account unless you need to use the root account for -system administration tasks. -@end quotation - -@quotation -@strong{Warning} Be careful to remove only the necessary partitions. -Removing other partitions could result in data loss or a corrupted -system environment. -@end quotation diff --git a/Identity/Manual/Introduction/doc-convenctions.texi b/Identity/Manual/Introduction/doc-convenctions.texi new file mode 100644 index 0000000..f74c31a --- /dev/null +++ b/Identity/Manual/Introduction/doc-convenctions.texi @@ -0,0 +1,109 @@ +In this manual the personal pronoun @emph{we} is used to repesent +@emph{The CentOS Artwork SIG}. This is, the group of persons building +the CentOS Artwork Repository. + +In this manual, certain words are represented in different fonts, +typefaces, sizes, and weights. This highlighting is systematic; +different words are represented in the same style to indicate their +inclusion in a specific category. The types of words that are +represented this way include the following: + +@table @command +@item command + +Linux commands (and other operating system commands, when used) are +represented this way. This style should indicate to you that you can +type the word or phrase on the command line and press Enter to invoke +a command. Sometimes a command contains words that would be displayed +in a different style on their own (such as file names). In these +cases, they are considered to be part of the command, so the entire +phrase is displayed as a command. For example: + +Use the @command{centos-art identity --render='path/to/dir'} command +to produce contents inside the @file{trunk/Identity} directory +structure. +@end table + +@table @file +@item file name + +File names, directory names, paths, and RPM package names are +represented this way. This style indicates that a particular file or +directory exists with that name on your system. Examples: + +The @file{init.sh} file in @file{trunk/Scripts/Bash/Cli/} directory is +the initialization script, written in Bash, used to automate most of +tasks in the repository. + +The @command{centos-art} command uses the @file{ImageMagick} RPM +package to convert images from PNG format to other formats. +@end table + +@table @key +@item @key{key} + +A key on the keyboard is shown in this style. For example: + +To use @key{TAB} completion to list particular files in a directory, +type @command{ls}, then a character, and finally the Tab key. Your +terminal displays the list of files in the working directory that +begin with that character. +@end table + +@table @key +@item @key{key-combination} +A combination of keystrokes is represented in this way. For example: + +The @key{Ctrl-Alt-Backspace} key combination exits your graphical +session and returns you to the graphical login screen or the console. +@end table + +@table @code +@item @code{computer output} + +Text in this style indicates text displayed to a shell prompt such as +error messages and responses to commands. For example: + +The @command{ls} command displays the contents of a directory. For example: + +@verbatim +Config manual_renameEntry.sh +manual_copyEntry.sh manual_restoreCrossReferences.sh +manual_deleteCrossReferences.sh manual_searchIndex.sh +@end verbatim + +The output returned in response to the command (in this case, the +contents of the directory) is shown in this style. +@end table + +Additionally, we use several different strategies to draw your +attention to certain pieces of information. In order of urgency, these +items are marked as a note, tip, important, caution, or warning. For +example: + +@quotation +@strong{Note} Remember that Linux is case sensitive. In other words, a +rose is not a ROSE is not a rOsE. +@end quotation + +@quotation +@strong{Tip} The directory @file{/usr/share/doc/} contains additional +documentation for packages installed on your system. +@end quotation + +@quotation +@strong{Important} If you modify the DHCP configuration file, the +changes do not take effect until you restart the DHCP daemon. +@end quotation + +@quotation +@strong{Caution} Do not perform routine tasks as root --- use a +regular user account unless you need to use the root account for +system administration tasks. +@end quotation + +@quotation +@strong{Warning} Be careful to remove only the necessary partitions. +Removing other partitions could result in data loss or a corrupted +system environment. +@end quotation diff --git a/Identity/Manual/Introduction/layout.texi b/Identity/Manual/Introduction/layout.texi deleted file mode 100644 index 6f02b0d..0000000 --- a/Identity/Manual/Introduction/layout.texi +++ /dev/null @@ -1,346 +0,0 @@ -@emph{''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: @file{trunk/}, -@file{branches/}, and @file{tags/}. - -The @file{trunk/} directory (@pxref{Directories trunk}) organizes the main -development line of CentOS corporate visual identity. Inside -@file{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 -@file{trunk/} directory structure is mainly used to perform -development tasks related to CentOS corporate visual identity. - -The @file{branches/} directory (@pxref{Directories branches}) oranizes -parallel development lines to @file{trunk/} directory. The -@file{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 @file{branches/} directory is mainly used to perform -quality assurance tasks related to CentOS corporate visual identity. - -The @file{tags/} directory (@pxref{Directories tags}) organizes parallel frozen -lines to @file{branches/} directory. The parallel frozen lines are -immutable, nothing change inside them once they has been created. The -@file{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 (@url{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. - -@subsection 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 (@samp{01-welcome.png}, @samp{splash.png}, -@samp{anaconda_header.png}, etc.) and directory names are all written -capitalized (e.g., @samp{Identity}, @samp{Themes}, @samp{Motifs}, -@samp{TreeFlower}, etc.). - -Repository name convenctions are implemented inside the -@code{cli_getRepoName} function of @file{centos-art.sh} script. With -@code{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. - -@subsection Repository work flow - -As repository work flow we understand a serie of normalized steps used -to produce contents inside CentOS Artwork Repository. There are three -remarkable actions inside the repository that we need to provide a -normalized work flow for, they are: @emph{Rendition}, -@emph{Localization} and @emph{Programming}. - -@subsubsection Rendition - -Rendition is the action through which The CentOS Project Corporate -Identity is produced inside the repository. The CentOS Project -Corporate Identityis is made, in part, of several visual -manifestations. These visual manifestations implement the Corporate -Identity by mean of images placed in key areas of each manifestation -visual space. - -As work flow to produce these images, we decompose them 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 is built for. - -The combination of one design models with one artistic motifs is what -we know as one @emph{theme}. Inside themes directory structure, you -can find several design models and several artistic motifs, apart one -another, that can be albitrarily combined one another through -@emph{theme rendition}, a flexible way to produce images for different -visual manifestations inside CentOS Artwork Repository. Theme -rendition takes place in @file{trunk/Identity/Themes/Models} and -@file{trunk/Identity/Themes/Motifs} directory structures. - -In addition to theme rendition, 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. Such configuration is -named @emph{direct rendition} and is very useful to produce simple -content that doesn't need specific background information like icons -and illustrations used in documentation. Direct rendition takes place -in @file{trunk/Identity/Models} and @file{trunk/Identity/Images} -directory structures. - -@xref{Directories trunk Identity}, for more information. - -@subsubsection Localization - -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. - -Basically, the @command{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 @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 -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. - -@quotation -@strong{Tip} If you want to have your content localized inside CentOS -Artwork Repository be sure to use source files supported by -@command{gettext} and @command{xml2po} programs. -@end quotation - -@xref{Directories trunk Locales}, for more information. - -@subsubsection 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 @command{centos-art.sh} -script, a bash script specially designed to automate most frequent -tasks inside CentOS Artwork Repository. The @command{centos-art.sh} -script is stored in @file{trunk/Scripts} directory structure and is -there where the main development for @command{centos-art.sh} script -takes place. Basically, the @command{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 @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. - -@quotation -@strong{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 @email{centos-devel@@centos.org} mailing list exists -for you to manifest yourself. This restrictions are necessary to -protect our work from spammers. -@end quotation - -@xref{Directories trunk Scripts}, for more information. - -@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 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. - -@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. -@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{centos-art.sh} script needs to know when such changes happen, in -a way they could be noted and handled without producing errors. - -@subsection 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: -@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. - -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: - -@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/ -@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. diff --git a/Identity/Manual/Introduction/repo-convenctions.texi b/Identity/Manual/Introduction/repo-convenctions.texi new file mode 100644 index 0000000..0377d90 --- /dev/null +++ b/Identity/Manual/Introduction/repo-convenctions.texi @@ -0,0 +1,383 @@ +@emph{''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 names convenctions, how to +extend the current layout and the way content is produced, as well. + +The repository layout is used as standard backend for automation +scripts to work correctly. If repository layout changes unexpectedly, +automation scripts may get 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: @file{trunk/}, +@file{branches/}, and @file{tags/}. + +The @file{trunk/} directory (@pxref{Directories trunk}) organizes the main +development line of CentOS corporate visual identity. Inside +@file{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 +@file{trunk/} directory structure is mainly used to perform +development tasks related to CentOS corporate visual identity. + +The @file{branches/} directory (@pxref{Directories branches}) oranizes +parallel development lines to @file{trunk/} directory. The +@file{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 @file{branches/} directory is mainly used to perform +quality assurance tasks related to CentOS corporate visual identity. + +The @file{tags/} directory (@pxref{Directories tags}) organizes parallel frozen +lines to @file{branches/} directory. The parallel frozen lines are +immutable, nothing change inside them once they has been created. The +@file{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 (@url{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. + +@subsection 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 (@samp{01-welcome.png}, @samp{splash.png}, +@samp{anaconda_header.png}, etc.) and directory names are all written +capitalized (e.g., @samp{Identity}, @samp{Themes}, @samp{Motifs}, +@samp{TreeFlower}, etc.). + +Repository name convenctions are implemented inside the +@code{cli_getRepoName} function of @file{centos-art.sh} script. With +@code{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. + +@subsection Repository work flow + +As repository work flow we understand a serie of normalized steps used +to produce contents inside CentOS Artwork Repository. There are three +remarkable actions inside the repository that we need to provide a +normalized work flow for, they are: @emph{Rendition}, +@emph{Localization} and @emph{Programming}. + +@subsubsection Rendition + +Rendition is the action through which The CentOS Project Corporate +Identity is produced inside the repository. The CentOS Project +Corporate Identityis is made, in part, of several visual +manifestations. These visual manifestations implement the Corporate +Identity by mean of images placed in key areas of their visual space. + +As work flow to produce these images, we decompose them 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 is built for. + +The combination of one design models with one artistic motifs is what +we know as one @emph{theme}. Inside themes directory structure, you +can find several design models and several artistic motifs, apart one +another, that can be albitrarily combined one another through +@emph{theme rendition}, a flexible way to produce images for different +visual manifestations inside CentOS Artwork Repository. Theme +rendition takes place in @file{trunk/Identity/Themes/Models} and +@file{trunk/Identity/Themes/Motifs} directory structures. + +In addition to theme rendition, 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. Such configuration is +named @emph{direct rendition} and is very useful to produce simple +content that doesn't need specific background information like icons +and illustrations used in documentation. Direct rendition takes place +in @file{trunk/Identity/Models} and @file{trunk/Identity/Images} +directory structures. + +@xref{Directories trunk Identity}, for more information. + +@subsubsection Localization + +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. + +Basically, the @command{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 @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 +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. + +@quotation +@strong{Tip} If you want to have your content localized inside CentOS +Artwork Repository be sure to use source files supported by +@command{gettext} and @command{xml2po} programs. +@end quotation + +@xref{Directories trunk Locales}, for more information. + +@subsubsection 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 @command{centos-art.sh} +script, a bash script specially designed to automate most frequent +tasks inside CentOS Artwork Repository. The @command{centos-art.sh} +script is stored in @file{trunk/Scripts} directory structure and is +there where the main development for @command{centos-art.sh} script +takes place. Basically, the @command{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 @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. + +@quotation +@strong{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 @email{centos-devel@@centos.org} mailing list exists +for you to manifest yourself. This restrictions are necessary to +protect our work from spammers. +@end quotation + +@xref{Directories trunk Scripts}, for more information. + +@subsection Work lines + +The CentOS Artwork Repository is organized using the Rendition, +Localization and Programming concepts described above. These concepts +suggest three different work lines to get focused in: + +@table @strong +@item Graphic design + +This work line exists to cover the corporate design (e.g., brand +design, typography design and theme design). Other areas that could be +included here are icon design and illustration design for +documentation. + +@item 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. + +@item Translation + +This work line exists to localize corporate design and documentation +source files, so they can be produced in different languages. + +@item 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. +@end table + +@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 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. + +@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. +@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{centos-art.sh} script needs to know when such changes happen, in +a way they could be noted and handled without producing errors. + +@subsection 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: +@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. + +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: + +@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/ +@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. diff --git a/Identity/Manual/repository.info.bz2 b/Identity/Manual/repository.info.bz2 index 57e2f5f..4f446fe 100644 Binary files a/Identity/Manual/repository.info.bz2 and b/Identity/Manual/repository.info.bz2 differ diff --git a/Identity/Manual/repository.pdf b/Identity/Manual/repository.pdf index 8999a75..4fa37d1 100644 Binary files a/Identity/Manual/repository.pdf and b/Identity/Manual/repository.pdf differ diff --git a/Identity/Manual/repository.txt.bz2 b/Identity/Manual/repository.txt.bz2 index b6a3407..3c52f72 100644 Binary files a/Identity/Manual/repository.txt.bz2 and b/Identity/Manual/repository.txt.bz2 differ diff --git a/Identity/Manual/repository.xhtml.tar.bz2 b/Identity/Manual/repository.xhtml.tar.bz2 index d3a433b..691c578 100644 Binary files a/Identity/Manual/repository.xhtml.tar.bz2 and b/Identity/Manual/repository.xhtml.tar.bz2 differ diff --git a/Identity/Manual/repository.xml b/Identity/Manual/repository.xml index 26c5791..4960488 100644 --- a/Identity/Manual/repository.xml +++ b/Identity/Manual/repository.xml @@ -93,13 +93,13 @@ - Convenctions - Convenctions + Document Convenctions + Document Convenctions - Layout - Layout + Repository Convenctions + Repository Convenctions @@ -168,7 +168,7 @@ Ralph Angenendt <ralph@centos.org> - Infrastructure, Packaging. + Infrastructure, Packaging, Documentation. @@ -194,7 +194,7 @@ Copying Conditions - Convenctions + Document Convenctions Authors Introduction
@@ -211,8 +211,8 @@
- Convenctions - Layout + Document Convenctions + Repository Convenctions Copying Conditions Introduction
@@ -290,14 +290,15 @@ manual_deleteCrossReferences.sh manual_searchIndex.sh
- Layout + Repository Convenctions Feedback - Convenctions + Document Convenctions Introduction
- Repository Layout - Repository layout”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. + Repository Convenctions + Repository convenctions”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 names convenctions, how to extend the current layout and the way content is produced, as well. + The repository layout is used as standard backend for automation scripts to work correctly. If repository layout changes unexpectedly, automation scripts may get 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. @@ -316,38 +317,69 @@ manual_deleteCrossReferences.sh manual_searchIndex.sh Rendition - See Directories trunk Identity. - Rendition is the action through which The CentOS Project Corporate Identity is produced inside the repository. The CentOS Project Corporate Identityis is made, in part, of several visual manifestations. These visual manifestations implement the Corporate Identity by mean of images placed in key areas of each manifestation visual space. + Rendition is the action through which The CentOS Project Corporate Identity is produced inside the repository. The CentOS Project Corporate Identityis is made, in part, of several visual manifestations. These visual manifestations implement the Corporate Identity by mean of images placed in key areas of their visual space. As work flow to produce these images, we decompose them 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 is built for. The combination of one design models with one artistic motifs is what we know as one theme. Inside themes directory structure, you can find several design models and several artistic motifs, apart one another, that can be albitrarily combined one another through theme rendition, a flexible way to produce images for different visual manifestations inside CentOS Artwork Repository. Theme rendition takes place in trunk/Identity/Themes/Models and trunk/Identity/Themes/Motifs directory structures. In addition to theme rendition, 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. Such configuration is named direct rendition and is very useful to produce simple content that doesn't need specific background information like icons and illustrations used in documentation. Direct rendition takes place in trunk/Identity/Models and trunk/Identity/Images directory structures. + See Directories trunk Identity, for more information. Localization - See Directories trunk Locales. 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. 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. 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. + See Directories trunk Locales, for more information. Programming - See Directories trunk Scripts. 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. + See Directories trunk Scripts, for more information. + Work lines + The CentOS Artwork Repository is organized using the Rendition, Localization and Programming concepts described above. These concepts suggest three different work lines to get focused in: + + + Graphic design + + This work line exists to cover the corporate design (e.g., brand design, typography design and theme design). Other areas that could be included here are icon design and illustration design for documentation. + + + + 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. + + + + Translation + + This work line exists to localize corporate design and documentation source files, so they can be produced in different languages. + + + + 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. + + +
+ + + 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. @@ -390,7 +422,7 @@ centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/ Feedback - Layout + Repository Convenctions Introduction
Send in Your Feedback @@ -439,11 +471,6 @@ centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/ - Directories trunk Identity Locales - Directories trunk Identity Locales - - - Directories trunk Identity Manual Directories trunk Identity Manual @@ -559,6 +586,11 @@ centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/ + Directories trunk Locales + Directories trunk Locales + + + Directories trunk Scripts Directories trunk Scripts @@ -798,7 +830,7 @@ centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/ Locales This section organizes production of translation messages for Identity, Documentation and Scripts. This place is perfect to consolidate The CentOS Translation SIG. If you love translating, you'll find lot of messages waiting for you to translate here. - See Directories trunk Identity Locales, for more information. + See Directories trunk Locales, for more information. @@ -909,7 +941,7 @@ centos-art render trunk/Identity/Path/To/Dir Directories trunk Identity Fonts - Directories trunk Identity Locales + Directories trunk Identity Manual Directories trunk Identity Brands Directories
@@ -959,33 +991,9 @@ centos-art render trunk/Identity/Path/To/Dir
- Directories trunk Identity Locales - Directories trunk Identity Manual - Directories trunk Identity Fonts - Directories -
- The <file>trunk/Identity/Locales</file> Directory - Directories trunk Identity LocalesThe trunk/Locales directory exists to store the translation messages used to produce content in different languages. - Translation messages are organized using the directory structure of the component being translated. For example, if we want to provide translation messages for trunk/Manuals/Repository, then the trunk/Locales/Manuals/Repository directory needs to be created. - Once the locale directory exists for the component we want to provide translation messages for, it is necessary to create the translation files where translation messages are. The translation files follows the concepts of xml2po and GNU gettext tools. - The basic translation process is as follow: first, translatable strings are extracted from files and a portable object template (.pot) is created or updated with the information. Using the portable object template, a portable object (.po) is created or updated for translator to locale the messages retrived. Finally, a machine object (.mo) is created from portable object to sotore the translated messages. - Inside the repository there are two ways to retrive translatable strings from files. The first one is through xml2po command and the second through xgettext command. The xml2po is used to retrive translatable strings from XML files (e.g., Scalable Vector Graphics, DocBook, etc.) and the xgettext command is used to retrive translatable strings from shell scripts files (e.g., the files that make the centos-art.sh command-line interface). - When translatable strings are retrived from XML files, using the xml2po command, there is no need to create the machine object as we do when translatable strings ar retrived from shell files, using the xgettext command. The xml2po produces a temporal machine object in order to create a translated XML file. Once the translated XML file has been created the machine object is no longer needed. On the other hand, the machine object produced by the xgettext command is required by the system in order for the show shell script localized messages. - Another difference between xml2po and xgettext we need to be aware of is the directory structure used to store machine objects. In xml2po, the machine object is created in the current working directory as .xml2po.mo and can be safetly removed once the translated XML file has been created. In the case of xgettext, the machine object needs to be stored in the $TEXTDOMAIN/$LOCALE/LL_MESSAGES/$TEXTDOMAIN.mo file in order for the system to interpret it and should not be removed since it is the file that contain the translation messages themselves. - Automation of localization tasks is achived through the locale functionality of command-line interface. - - - Directories trunk Scripts Functions Locale - Directories trunk Scripts Functions Locale - - - -
- - Directories trunk Identity Manual Directories trunk Identity Palettes - Directories trunk Identity Locales + Directories trunk Identity Fonts Directories
The <file>trunk/Identity/Manual</file> Directory @@ -2140,7 +2148,7 @@ centos-art render trunk/Identity/Path/To/Dir Directories trunk Identity Webenv - Directories trunk Scripts + Directories trunk Locales Directories trunk Identity Themes Motifs TreeFlower Directories
@@ -2402,9 +2410,33 @@ priority=10
+ Directories trunk Locales + Directories trunk Scripts + Directories trunk Identity Webenv + Directories +
+ The <file>trunk/Locales</file> Directory + Directories trunk LocalesThe trunk/Locales directory exists to store the translation messages used to produce content in different languages. + Translation messages are organized using the directory structure of the component being translated. For example, if we want to provide translation messages for trunk/Manuals/Repository, then the trunk/Locales/Manuals/Repository directory needs to be created. + Once the locale directory exists for the component we want to provide translation messages for, it is necessary to create the translation files where translation messages are. The translation files follows the concepts of xml2po and GNU gettext tools. + The basic translation process is as follow: first, translatable strings are extracted from files and a portable object template (.pot) is created or updated with the information. Using the portable object template, a portable object (.po) is created or updated for translator to locale the messages retrived. Finally, a machine object (.mo) is created from portable object to sotore the translated messages. + Inside the repository there are two ways to retrive translatable strings from files. The first one is through xml2po command and the second through xgettext command. The xml2po is used to retrive translatable strings from XML files (e.g., Scalable Vector Graphics, DocBook, etc.) and the xgettext command is used to retrive translatable strings from shell scripts files (e.g., the files that make the centos-art.sh command-line interface). + When translatable strings are retrived from XML files, using the xml2po command, there is no need to create the machine object as we do when translatable strings ar retrived from shell files, using the xgettext command. The xml2po produces a temporal machine object in order to create a translated XML file. Once the translated XML file has been created the machine object is no longer needed. On the other hand, the machine object produced by the xgettext command is required by the system in order for the show shell script localized messages. + Another difference between xml2po and xgettext we need to be aware of is the directory structure used to store machine objects. In xml2po, the machine object is created in the current working directory as .xml2po.mo and can be safetly removed once the translated XML file has been created. In the case of xgettext, the machine object needs to be stored in the $TEXTDOMAIN/$LOCALE/LL_MESSAGES/$TEXTDOMAIN.mo file in order for the system to interpret it and should not be removed since it is the file that contain the translation messages themselves. + Automation of localization tasks is achived through the locale functionality of command-line interface. + + + Directories trunk Scripts Functions Locale + Directories trunk Scripts Functions Locale + + + +
+ + Directories trunk Scripts Directories trunk Scripts Functions - Directories trunk Identity Webenv + Directories trunk Locales Directories
The <file>trunk/Scripts</file> Directory