diff --git a/Manuals/Repository/Docbook/Commons.ent b/Manuals/Repository/Docbook/Commons.ent index 88dad24..3091319 100644 --- a/Manuals/Repository/Docbook/Commons.ent +++ b/Manuals/Repository/Docbook/Commons.ent @@ -20,7 +20,7 @@ -&TC; Project"> +&TC; Project"> @@ -31,13 +31,13 @@ -&TCA; Repository"> -&TCA; SIG"> +&TCA; Repository"> +&TCA; SIG"> -&TCA; Mailing List"> -&TC; Developers Mailing List"> +&TCA; Mailing List"> +&TC; Developers Mailing List"> diff --git a/Manuals/Repository/Docbook/Introduction.docbook b/Manuals/Repository/Docbook/Introduction.docbook index cfc091d..d483c3b 100644 --- a/Manuals/Repository/Docbook/Introduction.docbook +++ b/Manuals/Repository/Docbook/Introduction.docbook @@ -9,11 +9,10 @@ - &TCARUG; describes how The CentOS Project corporate visual - identity is organized and produced inside &TCAR;. If you are - looking for a comprehensive, task-oriented guide for - understanding how &TCPCI; is produced, this is the manual for - you. + &TCARUG; describes how &TCPCVI; is organized and produced + inside &TCAR;. If you are looking for a comprehensive, + task-oriented guide for understanding how &TCPCI; is produced, + this is the manual for you. @@ -29,9 +28,6 @@ &intro-copying; &intro-policy; &intro-worklines; - &intro-relbdirs; - &intro-syncpaths; - &intro-extending; &intro-filenames; &intro-layout; diff --git a/Manuals/Repository/Docbook/Introduction.ent b/Manuals/Repository/Docbook/Introduction.ent index 6cf79cb..d730bd1 100644 --- a/Manuals/Repository/Docbook/Introduction.ent +++ b/Manuals/Repository/Docbook/Introduction.ent @@ -10,13 +10,17 @@ - - - - - - - - + + + + + + + + + + + + diff --git a/Manuals/Repository/Docbook/Introduction/Extending.docbook b/Manuals/Repository/Docbook/Introduction/Extending.docbook deleted file mode 100644 index e0bfa67..0000000 --- a/Manuals/Repository/Docbook/Introduction/Extending.docbook +++ /dev/null @@ -1,42 +0,0 @@ - - - Extending Repository Organization - - - Occasionly, you may find that new components of &TCPCVI; need - to be added to the repository in order to work them out. If - that is the case, the first question we need to ask ourselves, - before starting to create directories blindly all over, is: - What is the right place to store it? - - - - When the repository structure is extended, it is very useful - to bear in mind &TCPCVIS;, &TCM; and &TCDRS;. The rest is a - matter of choosing appropriate names. It is also worth to - know that each directory in the repository responds to one or - more concepts that justify its existence. - - - - To build a directory structure inside the repository, you need - to define the concept behind it first and later create the - directory, remembering that there are locations inside the - repository that define concepts you probably would prefer to - reuse. For example, the trunk/Identity/Images/Themes - directory stores artistic motifs of different themes, the - trunk/Identity/Models/Themes - directory stores design models for themes, the trunk/Manuals directory stores - documentation, the trunk/L10n stores translation - messages, and the trunk/Scripts stores automation - scripts. Using this information and the one provided in , it is possible for you to - find out good places for extending &TCAR;. - - - diff --git a/Manuals/Repository/Docbook/Introduction/Layout.docbook b/Manuals/Repository/Docbook/Introduction/Layout.docbook index 4b29108..048a0a6 100644 --- a/Manuals/Repository/Docbook/Introduction/Layout.docbook +++ b/Manuals/Repository/Docbook/Introduction/Layout.docbook @@ -46,7 +46,7 @@ The second level of directories in the repository provides organization for each work line described in . + linkend="intro-worklines" />. diff --git a/Manuals/Repository/Docbook/Introduction/Relbdirs.docbook b/Manuals/Repository/Docbook/Introduction/Relbdirs.docbook deleted file mode 100644 index 48e2f81..0000000 --- a/Manuals/Repository/Docbook/Introduction/Relbdirs.docbook +++ /dev/null @@ -1,128 +0,0 @@ - - - Relation Between Directories - - - In order for automation scripts to produce content inside a - working copy of &TCAR;, it is required that all work lines be - related somehow. The relation between work lines is used by - automation scripts to know where to retrive the information - they need to work with (e.g., input files, translation - messages, output locations, etc.). This kind of relation is - built using two path constructions known as master - paths and auxiliar paths. - - - - - Master Paths - - - A master path refers to a directory inside the repository that - contain input files required to produce output files through - automation scripts. Examples of master paths inside the - repository include: - - - - - trunk/Identity/Models/Brands - - - - - trunk/Manuals/Repository/Docbook - - - - - trunk/Identity/Models/Themes/Default/Distro/5/Anaconda - - - - - - - - - Auxiliar paths - - - An auxiliar path refers a directory inside the repository - considered auxiliar for the master path. Auxiliar path can be - either for output or localization. Assuming the master path - provides the input information, the auxiliar paths provide the - auxiliar information which describes how and where that input - information is rendered by automation scripts. Examples of - auxiliar paths inside the repository include: - - - - - trunk/Identity/Images/Brands - - - - - trunk/Manuals/Repository/Docbook/es_ES - - - - - trunk/Locales/Manuals/Repository/Docbook/es_ES - - - - - trunk/Identity/Images/Themes/Flame/3/Distro/5/Anaconda/es_ES - - - - - trunk/Locales/Identity/Models/Default/Distro/5/Anaconda/es_ES - - - - - - - - - - - The relationship between master and auxiliar paths is built by - combining the second directory level of master paths with - directories in the second directory level of repository - layout. In the second directory level of repository layout, - the Identity, Manuals and Scripts directories are always - used to create the master paths and the output auxiliar paths. - The Locales directory, - on the other hand, is always used to create localization - auxiliar paths for all the master paths available under - Identity, Manuals and Scripts directories. - - - - For example, if the LANG environment variable - is set to es_ES.UTF-8 and you execute the - render functionality of - centos-art.sh script with the trunk/Manuals/Repository/Docbook - master path as argument, it will produce &TCARUG; in Spanish - language using translation messages from trunk/Locales/Manuals/Repository/Docbook/es_ES - auxiliar path and saving output files inside trunk/Manuals/Repository/Docbook/es_ES - auxiliar path. - - - - To better understand what each directory inside the repository - means, read . - - - diff --git a/Manuals/Repository/Docbook/Introduction/Syncpaths.docbook b/Manuals/Repository/Docbook/Introduction/Syncpaths.docbook deleted file mode 100644 index 3d6245b..0000000 --- a/Manuals/Repository/Docbook/Introduction/Syncpaths.docbook +++ /dev/null @@ -1,93 +0,0 @@ - - - Syncronizing Paths - - - Once both master and auxiliar paths have been set in the - repository, they shouldn't be changed. However, assuming you - need to change them, it is required that you also change the - relation between them, in order for both master and auxiliar - paths to retain their relation one another. This process of - keeping relation between master and auxiliar paths updated is - known as path syncronization. - - - - Path syncronization is required for automation scripts to know - where to store final output, where to retrive translation, and - any information that might be desired. If the relation between - master paths and auxiliar paths is lost, there is no way for - centos-art.sh script to know where to - retrive the information it needs to work with. Path - syncronization is the way we use to organize and extend the - information stored in the repository. - - - - Path syncronization involves both movement of files and - replacement of content inside files. Movement of files is - related to actions like renaming files and directories inside - the repository. Replacement of content inside files is - related to actions like replacing information (e.g., paths - information) inside files in order to keep file contents and - file locations consistent one another after the movement. - - - - The order followed to syncronize path information is very - important because the versioned nature of the files we are - working with. When a renaming action is performed, we avoid - making replacements inside files first and file movements - later. This would require two commit actions: one for the - files' internal changes and another for the file movement - itself. Otherwise, we prefer to perform file movements first - and file internal replacements later. This way it is possible - to commit both changes as if they were just one. - - - - - There is no support for URLs actions 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 perform URL actions directly, use Subversion - commands instead. - - - - - At this moment there is no full implementation of path - syncronization process inside centos-art.sh - script and it is somthing we need to do oursleves. However, - the texinfo backend of help - functionality which provides a restricted implementation of - path syncronization to this specific area of documentation - through the , - and options you can take as - reference to implement it in other areas. - - - - The plan for a full implementation of path syncronization - would be to create individual restricted implementations like - the one in texinfo backend for other areas that - demand it and then, create a higher implmentation that - combines them all as needed. This way, if we try to rename a - repository directory the higher action will define which are - all the restricted actions that should be performed in order - to make the full path syncronization. - - - - For example, if the directory we are renaming is a master - path, it is required to syncronize the related output and - localization auxiliar paths. On the other hand, if the - directory we are renaming through full path syncronization is - an auxiliar path, it is required to determine first what is - the related master path and later, perform the syncronization - from master path to auxiliar paths as if the path provided - would be the master path not the auxiliar path. - - - diff --git a/Manuals/Repository/Docbook/Introduction/Worklines.docbook b/Manuals/Repository/Docbook/Introduction/Worklines.docbook index 14beb48..6f6987c 100644 --- a/Manuals/Repository/Docbook/Introduction/Worklines.docbook +++ b/Manuals/Repository/Docbook/Introduction/Worklines.docbook @@ -1,93 +1,24 @@ - + Repository Work Lines To organize content production inside &TCAR;, production has been divided into individual work lines that relate one - another. The is based on the idea of doing one thing well and - later combine the result of each individual part to achieve a - higher purpose. Work lines, as conceived here, provide - relayable output components that combine one another to close - the production cycle inside &TCAR;. + another based on the idea of doing one thing well. Later, the + results produced individually by each work line are combined + to achieve a higher purpose. Work lines, as conceived here, + provide the relayable output components the production cycle + inside &TCAR; needs to let everyone to work syncronized in a + descentralized environment. - - - - Visual Identity (trunk/Identity) - - - In the production cycle, the first step takes place through - graphic design. It is focused on preparing design models for - all the visual manifestation &TCP; is made of. Here, graphic - designers describe the visual characteristics of each visual - manifestation (e.g., image dimensions, position of text in the - visible area, translation markers, etc.). Later, once design - models have been defined, graphic designers take care of - artistic motifs to define the visual style of those design - models already created (e.g., how the look and feel). - Furthermore, graphic designers use the - render functionality of - centos-art.sh script to combine both design - models and artistic motifs in order to produce the final - images required by each visual manifestaions. - - - - - - Localization (trunk/L10n) - - - The second step in the production cycle is to localize - source files (e.g., SVG, DocBook, Shell scripts). This step - makes possible to produce localized images, localized - documentation and localized automation scripts. The - localization tasks are carried on by translators using the - locale functionality of the - centos-art.sh script which take care of - retriving translatable strings from source files and provide a - consistent localization interface based on the ideas behind - GNU gettext multi-lingual message - production. - - - - - - Documentation (trunk/Manuals) - - - The third step in the production cycle is to document &TCAR;, - what it is and how to use it. This step provides the - conceptual ideas used as base to edificate &TCPCVI; and is - implemented by mean of &TCARUG;. To write documentation, - documentors use the help functionality of - centos-art.sh script which provide an - consistent interface for building documentation through - different documentation backends (e.g., Texinfo, DocBook). - - - - - - Automation (trunk/Scripts) - - - The fourth step in the production cycle is to automate - frequent tasks inside &TCAR;. This step closes the production - cycle and provides the production standards needed by all - different work lines to coexist together. Here is where we - develop the centos-art.sh script and all - its functionalities (e.g., render for - rendition, help for documentation, - locale for localization, etc.). At this - point it should be obvious, but we consider worth to remember - that: there is no need to type several tasks, time after time, - if they can be programmed into just one executable script. - - - - + &intro-worklines-identity; + &intro-worklines-l10n; + &intro-worklines-manuals; + &intro-worklines-scripts; + &intro-worklines-relbdirs; + &intro-worklines-syncpaths; + &intro-worklines-extending; + diff --git a/Manuals/Repository/Docbook/Introduction/Worklines/extending.docbook b/Manuals/Repository/Docbook/Introduction/Worklines/extending.docbook new file mode 100644 index 0000000..5c9978a --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Worklines/extending.docbook @@ -0,0 +1,42 @@ + + + Extending Repository Layout + + + Occasionly, you may find that new components of &TCPCVI; need + to be added to the repository in order to work them out. If + that is the case, the first question we need to ask ourselves, + before starting to create directories blindly all over, is: + What is the right place to store it? + + + + When the repository structure is extended, it is very useful + to bear in mind &TCPCVIS;, &TCM; and &TCDRS;. The rest is a + matter of choosing appropriate names. It is also worth to + know that each directory in the repository responds to one or + more concepts that justify its existence. + + + + To build a directory structure inside the repository, you need + to define the concept behind it first and later create the + directory, remembering that there are locations inside the + repository that define concepts you probably would prefer to + reuse. For example, the trunk/Identity/Images/Themes + directory stores artistic motifs of different themes, the + trunk/Identity/Models/Themes + directory stores design models for themes, the trunk/Manuals directory stores + documentation, the trunk/L10n stores translation + messages, and the trunk/Scripts stores automation + scripts. Using this information and the one provided in , it is possible for you to + find out good places for extending &TCAR;. + + + diff --git a/Manuals/Repository/Docbook/Introduction/Worklines/identity.docbook b/Manuals/Repository/Docbook/Introduction/Worklines/identity.docbook new file mode 100644 index 0000000..4b7626d --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Worklines/identity.docbook @@ -0,0 +1,26 @@ + + + Visual Identity + + + In the production cycle, the first step takes place through + graphic design. It is focused on preparing design models for + all the visual manifestation &TCP; is made of. Here, graphic + designers describe the visual characteristics of each visual + manifestation (e.g., image dimensions, position of text in the + visible area, translation markers, etc.). + Later, once design models have been defined, graphic designers + take care of artistic motifs to define the visual style of + those design models already created (e.g., how they look and + feel). + + + + Finally, graphic designers use the + render functionality of + centos-art.sh script to combine both design + models and artistic motifs in order to produce the final + images required by each visual manifestaions. + + + diff --git a/Manuals/Repository/Docbook/Introduction/Worklines/l10n.docbook b/Manuals/Repository/Docbook/Introduction/Worklines/l10n.docbook new file mode 100644 index 0000000..31f5ebc --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Worklines/l10n.docbook @@ -0,0 +1,22 @@ + + + Localization + + + The second step in the production cycle is to localize + source files (e.g., SVG, DocBook, Shell scripts). This step + makes possible to produce localized images, localized + documentation and localized automation scripts. + + + + The localization tasks are carried on by translators using the + locale functionality of the + centos-art.sh script which take care of + retriving translatable strings from source files and provide a + consistent localization interface based on GNU + gettext multi-lingual message + production tool set and xml2po command. + + + diff --git a/Manuals/Repository/Docbook/Introduction/Worklines/manuals.docbook b/Manuals/Repository/Docbook/Introduction/Worklines/manuals.docbook new file mode 100644 index 0000000..1718f28 --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Worklines/manuals.docbook @@ -0,0 +1,20 @@ + + + Documentation + + + The third step in the production cycle is to document &TCAR;, + what it is and how to use it. This step provides the + conceptual ideas used as base to edificate &TCPCVI; and is + implemented through &TCARUG;. + + + + To write documentation, documentors use the + help functionality of + centos-art.sh script which provide an + consistent interface for building documentation through + different documentation backends (e.g., Texinfo and DocBook). + + + diff --git a/Manuals/Repository/Docbook/Introduction/Worklines/relbdirs.docbook b/Manuals/Repository/Docbook/Introduction/Worklines/relbdirs.docbook new file mode 100644 index 0000000..22bf7f8 --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Worklines/relbdirs.docbook @@ -0,0 +1,128 @@ + + + Relation Between Directories + + + In order for automation scripts to produce content inside a + working copy of &TCAR;, it is required that all work lines be + related somehow. The relation between work lines is used by + automation scripts to know where to retrive the information + they need to work with (e.g., input files, translation + messages, output locations, etc.). This kind of relation is + built using two path constructions known as master + paths and auxiliar paths. + + + + + Master Paths + + + A master path refers to a directory inside the repository that + contain input files required to produce output files through + automation scripts. Examples of master paths inside the + repository include: + + + + + trunk/Identity/Models/Brands + + + + + trunk/Manuals/Repository/Docbook + + + + + trunk/Identity/Models/Themes/Default/Distro/5/Anaconda + + + + + + + + + Auxiliar paths + + + An auxiliar path refers a directory inside the repository + considered auxiliar for the master path. Auxiliar path can be + either for output or localization. Assuming the master path + provides the input information, the auxiliar paths provide the + auxiliar information which describes how and where that input + information is rendered by automation scripts. Examples of + auxiliar paths inside the repository include: + + + + + trunk/Identity/Images/Brands + + + + + trunk/Manuals/Repository/Docbook/es_ES + + + + + trunk/Locales/Manuals/Repository/Docbook/es_ES + + + + + trunk/Identity/Images/Themes/Flame/3/Distro/5/Anaconda/es_ES + + + + + trunk/Locales/Identity/Models/Default/Distro/5/Anaconda/es_ES + + + + + + + + + + + The relationship between master and auxiliar paths is built by + combining the second directory level of master paths with + directories in the second directory level of repository + layout. In the second directory level of repository layout, + the Identity, Manuals and Scripts directories are always + used to create the master paths and the output auxiliar paths. + The Locales directory, + on the other hand, is always used to create localization + auxiliar paths for all the master paths available under + Identity, Manuals and Scripts directories. + + + + For example, if the LANG environment variable + is set to es_ES.UTF-8 and you execute the + render functionality of + centos-art.sh script with the trunk/Manuals/Repository/Docbook + master path as argument, it will produce &TCARUG; in Spanish + language using translation messages from trunk/Locales/Manuals/Repository/Docbook/es_ES + auxiliar path and saving output files inside trunk/Manuals/Repository/Docbook/es_ES + auxiliar path. + + + + To better understand what each directory inside the repository + means, read . + + + diff --git a/Manuals/Repository/Docbook/Introduction/Worklines/scripts.docbook b/Manuals/Repository/Docbook/Introduction/Worklines/scripts.docbook new file mode 100644 index 0000000..0ceaa6b --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Worklines/scripts.docbook @@ -0,0 +1,24 @@ + + + Automation + + + The fourth step in the production cycle is to automate + frequent tasks inside &TCAR;. This step closes the production + cycle and provides the production standards needed by all + different work lines to coexist together. Here is where + the centos-art.sh script and all + its functionalities (e.g., render for + rendition, help for documentation, + locale for localization, etc.) are + developed. + + + + At this point it should be obvious, but we consider worth to + remember that: there is no need to type several tasks, time + after time, if they can be programmed into just one executable + script. + + + diff --git a/Manuals/Repository/Docbook/Introduction/Worklines/syncpaths.docbook b/Manuals/Repository/Docbook/Introduction/Worklines/syncpaths.docbook new file mode 100644 index 0000000..a6e8219 --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Worklines/syncpaths.docbook @@ -0,0 +1,96 @@ + + + Path Syncronization + + + Once both master and auxiliar paths have been related in the + repository, they shouldn't be changed except you absolutly + need to do so. In this cases, when you need to change master + or auxiliar paths, it is required that you also change the + relation between them so as to retain their bond. This + process of keeping master and auxiliar paths + connected between themselves is known as + path syncronization. + + + + Path syncronization is required for automation scripts to know + where to store final output, where to retrive translation + messages from, and whatever information you might need to + count with. If the relation between master paths and auxiliar + paths is lost, there is no way for automation scripts to know + where to retrive the information they need to work with or + where to store the output information produced from it. Path + syncronization is the way we use through to organize and + extend the information stored in the repository. + + + + Path syncronization involves both movement of files and + replacement of content inside files. Movement of files is + related to actions like renaming files and directories inside + the repository. Replacement of content inside files is + related to actions like replacing information (e.g., paths + information) inside files in order to keep file contents and + file locations consistent one another after a file movement. + + + + The order followed to syncronize path information is very + important because the versioned nature of the files we are + working with. When a renaming action needs to be performed + inside the repository, we avoid making replacements inside + files first and file movements later. This would demand two + commit actions: one for the files' internal changes and + another for the file movement itself. Otherwise, we prefer to + perform file movements first and files' internal replacements + later. This way it is possible to commit both changes as if + they were just one. + + + + + There is no support for URLs actions 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 + perform URL actions directly, use Subversion's commands + instead. + + + + + At this moment there is no full implementation of path + syncronization process inside centos-art.sh + script and it is somthing we need to do oursleves. However, + the texinfo backend of help + functionality which provides a restricted implementation of + path syncronization to this specific area of documentation + through the , + and options you can take as + reference to implement it in other areas. + + + + The plan for a full implementation of path syncronization + would be to create individual restricted implementations like + the one in texinfo backend for other areas that + demand it and then, create a higher implmentation that + combines them all as needed. This way, if we try to rename a + repository directory the higher action will define which are + all the restricted actions that should be performed in order + to make the full path syncronization. + + + + For example, if the directory we are renaming is a master + path, it is required to syncronize the related output and + localization auxiliar paths. On the other hand, if the + directory we are renaming through full path syncronization is + an auxiliar path, it is required to determine first what is + the related master path and later, perform the syncronization + from master path to auxiliar paths as if the path provided + would be the master path not the auxiliar path. + + +