diff --git a/Manuals/Repository/Docbook/Introduction.ent b/Manuals/Repository/Docbook/Introduction.ent index 0509462..8ce295c 100644 --- a/Manuals/Repository/Docbook/Introduction.ent +++ b/Manuals/Repository/Docbook/Introduction.ent @@ -9,5 +9,14 @@ + + + + + + + + + diff --git a/Manuals/Repository/Docbook/Introduction/Repoconvs.docbook b/Manuals/Repository/Docbook/Introduction/Repoconvs.docbook index 787d45c..a580e4a 100644 --- a/Manuals/Repository/Docbook/Introduction/Repoconvs.docbook +++ b/Manuals/Repository/Docbook/Introduction/Repoconvs.docbook @@ -24,355 +24,12 @@ previous versions of files at any time. - - - Policy - - - The CentOS Artwork Repository is a collaborative tool that - anyone can have access to. However, changing that tool in - any form is something that should be requested in &TCDML;. - Generally, people download working copies from &TCAR;, - study the repository organization, make some changes in - their working copies, make some tests to verify such - changes do work the way expected and finally request - access to commit them up to &TCAR; for others to benefit - from them. - - - Once you've received access to commit your changes, - there is no need for you to request permission again to commit - other changes from your working copy to &TCAR; as long as you - behave as a good cooperating citizen. - Otherwise, your rights to commit changes might be temporarly - revoked or permanently banished. - - As a good cooperating citizen one understand of a person - who respects the work already done by others and share ideas - with authors before changing relevant parts of their work, - specially in situations when the access required to realize - the changes has been granted already. Of course, there is a - time when conversation has taken place, the paths has been - traced and changing the work is so obvious that there is no - need for you to talk about it; that's because you already did, - you already built the trust to keep going. Anyway, the mailing - list mentioned above is available for sharing ideas in a way - that good relationship between community citizens could be - constantly balanced. - - The relationship between community citizens is monitored - by repository administrators. Repository administrators are - responsible of granting that everything goes the way it needs - to go in order for the CentOS Artwork Repository to accomplish - its mission which is: to provide a colaborative tool for &TCC; - where &TCP; corporate visual identity is built and maintained - by &TCC; itself. - - It is also important to remember that all the program - and documentation source files inside CentOS Artwork - Repository must comply the terms of and - respectively in order for them to remain inside the - repository. - - - - - - Work Lines - - Content production inside the repository is organized by - work lines. There are three major work - lines of production inside The CentOS Artwork Repository, - which are: Graphic design, - Documentation and - Localization. The specific way of - producing content inside each specific work line is - standardized by mean of centos-art.sh - script (which in turn, can be considered a work line by itself - [e.g., the Automation work line]). The - centos-art.sh script provides one specific - functionality for automating each major work line of content - production (e.g., render for producing images, - help for manage documentation, and - locale for localizing contents). - - The graphic design work line exists to cover brand - design, typography design and themes design mainly. - Additionally, some auxiliar areas like icon design, - illustration design, brushes design, patterns designs and - palettes of colors are also included here for completeness. - The graphic design work line is organized in the trunk/Identity directory. - - The documentation work line exists to describe what each - directory inside the CentOS Artwork Repository is for, the - conceptual ideas behind them and, if possible, how automation - scripts make use of them. The documentation work line is - organized in the trunk/Manuals directory. - - The localization work line exists to provide the - translation messages required to produce content in different - languages. Translation messages inside the repository are - stored as portable objects (e.g., .po, .pot) and machine - objects (.mo). The localization work line is organized in the - trunk/Locales - directory. - - The automation work line exists to standardize content - production inside the working copies of CentOS Artwork - Repository. Here is developed the - centos-art.sh script, a bash script - specially designed to automate most frequent tasks (e.g., - rendition, documentation and localization) inside the - repository. There is no need to type several tasks, time - after time, if they can be programmed into just one executable - script. The automation work line is organized in the - trunk/Scripts - directory. - - - - - - Relation Between Directories - - In order for automation scripts to produce content inside a - working copy of CentOS Artwork Repository, it is required that all - work lines be related somehow. The relation is used by automation - scripts to know where to retrive the information they need to work - with (e.g., design model, translation messages, output locations, - etc.). This kind of relation is built using two path - constructions named master paths and - auxiliar paths. - - The master path points only to directories that contain - source files (e.g., SVG files) required to produce output base - content (e.g., PNG files) through automation scripts. Each master - path inside the repository may have several auxiliar paths - associated, but auxiliar paths can only have one master path - associated. - - Master paths used for producing images through SVG rendition - are organized under trunk/Identity/Models directory - structure and the auxiliar paths under trunk/Identity/Images, trunk/Locales and trunk/Manuals directory - structures. - - Auxiliar paths can point either to directories or files. - When an auxiliar path points to a directory, that directory - contains information that modifies somehow the content produced - from master paths (e.g., translation messages) or provides the - output information required to know where the content produced - from the master path should be stored. When an auxiliar path - points to a file, that file has no other purpose but to document - the master path it refers to. - - Auxiliar paths should never be modified under any reason but - to satisfy the relationship with the master path. Liberal change - of auxiliar paths may suppress the conceptual idea they were - initially created for; and certainly, automation scripts may stop - working as expected. - - The relationship between auxiliar paths and master paths is - built by combining the master path and the second level directory - structures of the repository. The master path is considered the - path identifier and the repository second level directory - structure is considered the common part of the path where the path - identifier is appended to. So, if we have the master path - trunk/Identity/Models/Brands, we'll - end up having, at least, the trunk/Identity/Images/Brands auxiliar - path for storing output files and, optionally, one path under - trunk/Manuals for storing - documentation and one path under trunk/Locales for storing - localizations. - - - - - - Syncronizing Paths - - Once both master paths and their auxiliar paths have been - set, they shouldn't be changed. Assuming one master path must be - changed it is required that all related auxiliar paths be changed, - too. This is required in order for master paths to retain their - relation with auxiliar paths. This process of keeping relation - between master paths and auxiliar paths is known as path - syncronization. - - Path syncronization is required for automation scripts to - know where to store final output, where to retrive translation - messages, documentation, 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 may imply 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. - - The order followed to syncronize path information is very - important because the versioned nature of the repository files we - are working with. When a renaming action must be 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 except by texinfo backend of - help functionality which provides a restricted - implementation of path syncronization to this specific area of - documentation through the , - and options. - The plan for a full implementation of path syncronization would be - to create individual restricted implementations like this one for - other areas that demand it and then, create a higher implmentation - that combines all restricted implementations as needed. This way, - if we try to rename a repository directory the higer action will - define which are all the restricted actions that should be - performed in order for make a full path syncronization. For - example, if the directory we are renaming is part of graphic - design work line, it is required to syncronize related paths in - documentation and localization work lines. Likewise, if the - directory we are renaming is in documentation work line, it is - required to syncronize related paths in graphic design and - localization work lines. In all these cases, the direction used - for syncronizing paths must be from master path to auxiliar path - and never the opposite (i.e., rename the master path first and - auxiliar paths later). - - A practical example, through which you can notice the - usefulness of path syncronization process, is what happen when - documentation entries are renamed (see section ...). - - - - - - Extending Repository Organization - - Occasionly, you may find that new components of The - CentOS Project corporate visual identity 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 start to - create directories blindly all over, is: What is the - right place to store it? - - The best place to find answers is in The CentOS - Community (see page http://wiki.centos.org/Help), but going - there with hands empty is not good idea. It may give the - impression you don't really care about. Instead, consider the - following suggestions to find your own comprehension in order - to make your own propositions based on it. - - When extending respository structure it is very useful - to bear in mind The CentOS Project corporate visual identity - structure, The CentOS Mission and The CentOS Release Schema. - The rest is a matter of choosing appropriate names. It is also - worth to know that each directory in the repository responds - to a conceptual idea that justifies its existence. - - To build a directory structure inside the repository, - you need to define the conceptual idea first and later create - the directory, remembering that there are locations inside the - repository that define conceptual ideas you probably would - prefer to reuse. For example, the trunk/Identity/Images/Themes - directory stores theme artistic motifs, the trunk/Identity/Models/Themes - directory stores theme design models, the trunk/Manuals directory stores - documentation files, the trunk/Locales stores translation - messages, and the trunk/Scripts stores automation - scripts. - - - To better illustrate this desition process, you can - consider to examin the trunk/Identity/Images/Themes/TreeFlower/3 - directory structure as example. This directory can be - read as: the theme development line of version - 3 of TreeFlower artistic - motif. Additional, we can say that - TreeFlower artistic motif is part of - themes, as themes are part of The CentOS Project corporate - visual identity. - - - - The relationship between conceptual ideas can be - stablished by reading each repository documentation entry - individually, from trunk directory to a deeper - directory in the path. For reading repository - documentation entries we use the help - functionality of centos-art.sh script. - - - - - - - File Names - - Inside the CentOS Artwork Repository, generally, file - names are all written in lowercase (e.g., - 01-welcome.png, - splash.png, - anaconda_header.png, etc.) and directory - names are all written capitalized (e.g., Identity, Themes, Motifs) and sometimes in cammel - case (e.g., TreeFlower, - etc.). - - In the very specific case of repository documentation - entries, file names follow the directory naming convenction. - This is because they are documenting directories and that is - something we want to remark. So, to better describe what we - are documenting, documentation entries follow the name - convenction used by the item they document. - - - - - - Layout - - The CentOS Artwork Repository is organized through a - convenctional trunk, branches - and tags layout. Explanation of each directory - inside the repository can be found in the Directories - part. - - + &intro-repoconvs-policy; + &intro-repoconvs-worklines; + &intro-repoconvs-relbdirs; + &intro-repoconvs-syncpaths; + &intro-repoconvs-extending; + &intro-repoconvs-filenames; + &intro-repoconvs-layout; diff --git a/Manuals/Repository/Docbook/Introduction/Repoconvs/extending.docbook b/Manuals/Repository/Docbook/Introduction/Repoconvs/extending.docbook new file mode 100644 index 0000000..e33074e --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Repoconvs/extending.docbook @@ -0,0 +1,71 @@ + + + Extending Repository Organization + + + Occasionly, you may find that new components of The + CentOS Project corporate visual identity 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 start to + create directories blindly all over, is: What is the + right place to store it? + + + + The best place to find answers is in The CentOS Community (see + page http://wiki.centos.org/Help), but going there with hands + empty is not good idea. It may give the impression you don't + really care about. Instead, consider the following suggestions + to find your own comprehension in order to make your own + propositions based on it. + + + + When extending respository structure it is very useful to bear + in mind The CentOS Project corporate visual identity + structure, The CentOS Mission and The CentOS Release Schema. + The rest is a matter of choosing appropriate names. It is also + worth to know that each directory in the repository responds + to a conceptual idea that justifies its existence. + + + + To build a directory structure inside the repository, you need + to define the conceptual idea first and later create the + directory, remembering that there are locations inside the + repository that define conceptual ideas you probably would + prefer to reuse. For example, the trunk/Identity/Images/Themes + directory stores theme artistic motifs, the trunk/Identity/Models/Themes + directory stores theme design models, the trunk/Manuals directory stores + documentation files, the trunk/Locales stores translation + messages, and the trunk/Scripts stores automation + scripts. + + + + To better illustrate this desition process, you can consider + to examin the trunk/Identity/Images/Themes/TreeFlower/3 + directory structure as example. This directory can be read + as: the theme development line of version 3 of + TreeFlower artistic motif. Additional, we can + say that TreeFlower artistic motif is part of + themes, as themes are part of The CentOS Project corporate + visual identity. + + + + The relationship between conceptual ideas can be stablished by + reading each repository documentation entry individually, from + trunk directory to a + deeper directory in the path. For reading repository + documentation entries we use the help + functionality of centos-art.sh script. + + + diff --git a/Manuals/Repository/Docbook/Introduction/Repoconvs/filenames.docbook b/Manuals/Repository/Docbook/Introduction/Repoconvs/filenames.docbook new file mode 100644 index 0000000..a0ae48e --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Repoconvs/filenames.docbook @@ -0,0 +1,27 @@ + + + File Names + + + Inside &TCAR; directory structure, file names are all written + in lowercase (e.g., 01-welcome.png, + splash.png, + anaconda_header.png, etc.) and directory + names are all written capitalized (e.g., Identity, Themes, Motifs) and sometimes in cammel + case (e.g., TreeFlower, + etc.). + + + + In the very specific case of repository documentation entries, + file names follow the directory naming convenction. This is + because they are documenting directories and that is something + we want to remark. So, to better describe what we are + documenting, documentation entries follow the name convenction + used by the item they document. + + + diff --git a/Manuals/Repository/Docbook/Introduction/Repoconvs/layout.docbook b/Manuals/Repository/Docbook/Introduction/Repoconvs/layout.docbook new file mode 100644 index 0000000..911ec7d --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Repoconvs/layout.docbook @@ -0,0 +1,11 @@ + + + Layout + + + &TCAR; is organized through a convenctional + trunk, branches and + tags layout. + + + diff --git a/Manuals/Repository/Docbook/Introduction/Repoconvs/policy.docbook b/Manuals/Repository/Docbook/Introduction/Repoconvs/policy.docbook new file mode 100644 index 0000000..be790bf --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Repoconvs/policy.docbook @@ -0,0 +1,57 @@ + + + Policy + + + The CentOS Artwork Repository is a collaborative tool that + anyone can have access to. However, changing that tool in any + form is something that should be requested in &TCDML;. + Generally, people download working copies from &TCAR;, study + the repository organization, make some changes in their + working copies, make some tests to verify such changes do work + the way expected and finally request access to commit them up + to &TCAR; for others to benefit from them. + + + + Once you've received access to commit your changes, there is + no need for you to request permission again to commit other + changes from your working copy to &TCAR; as long as you behave + as a good cooperating citizen. + Otherwise, your rights to commit changes might be temporarly + revoked or permanently banished. + + + + As a good cooperating citizen one understand of a person who + respects the work already done by others and share ideas with + authors before changing relevant parts of their work, + specially in situations when the access required to realize + the changes has been granted already. Of course, there is a + time when conversation has taken place, the paths has been + traced and changing the work is so obvious that there is no + need for you to talk about it; that's because you already did, + you already built the trust to keep going. Anyway, the mailing + list mentioned above is available for sharing ideas in a way + that good relationship between community citizens could be + constantly balanced. + + + + The relationship between community citizens is monitored by + repository administrators. Repository administrators are + responsible of granting that everything goes the way it needs + to go in order for &TCAR; to accomplish its mission which is: + to provide a colaborative tool for &TCC; where &TCP; corporate + visual identity is built and maintained by &TCC; itself. + + + + It is also important to remember that all the program and + documentation source files inside &TCAR; must comply the terms + of and respectively in order for them to + remain inside the repository. + + + diff --git a/Manuals/Repository/Docbook/Introduction/Repoconvs/relbdirs.docbook b/Manuals/Repository/Docbook/Introduction/Repoconvs/relbdirs.docbook new file mode 100644 index 0000000..36d72eb --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Repoconvs/relbdirs.docbook @@ -0,0 +1,75 @@ + + + Relation Between Directories + + + In order for automation scripts to produce content inside a + working copy of CentOS Artwork Repository, it is required that + all work lines be related somehow. The relation is used by + automation scripts to know where to retrive the information + they need to work with (e.g., design model, translation + messages, output locations, etc.). This kind of relation is + built using two path constructions named master + paths and auxiliar + paths. + + + + The master path points only to directories that contain source + files (e.g., SVG files) required to produce output base + content (e.g., PNG files) through automation scripts. Each + master path inside the repository may have several auxiliar + paths associated, but auxiliar paths can only have one master + path associated. + + + + Master paths used for producing images through SVG rendition + are organized under trunk/Identity/Models directory + structure and the auxiliar paths under trunk/Identity/Images, trunk/Locales and trunk/Manuals directory + structures. + + + + Auxiliar paths can point either to directories or files. When + an auxiliar path points to a directory, that directory + contains information that modifies somehow the content + produced from master paths (e.g., translation messages) or + provides the output information required to know where the + content produced from the master path should be stored. When + an auxiliar path points to a file, that file has no other + purpose but to document the master path it refers to. + + + + Auxiliar paths should never be modified under any reason but + to satisfy the relationship with the master path. Liberal + change of auxiliar paths may suppress the conceptual idea they + were initially created for; and certainly, automation scripts + may stop working as expected. + + + + The relationship between auxiliar paths and master paths is + built by combining the master path and the second level + directory structures of the repository. The master path is + considered the path identifier and the repository second level + directory structure is considered the common part of the path + where the path identifier is appended to. So, if we have the + master path trunk/Identity/Models/Brands, + we'll end up having, at least, the trunk/Identity/Images/Brands + auxiliar path for storing output files and, optionally, one + path under trunk/Manuals for storing + documentation and one path under trunk/Locales for storing + localizations. + + + diff --git a/Manuals/Repository/Docbook/Introduction/Repoconvs/syncpaths.docbook b/Manuals/Repository/Docbook/Introduction/Repoconvs/syncpaths.docbook new file mode 100644 index 0000000..e619722 --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Repoconvs/syncpaths.docbook @@ -0,0 +1,94 @@ + + + Syncronizing Paths + + + Once both master paths and their auxiliar paths have been set, + they shouldn't be changed. Assuming one master path must be + changed it is required that all related auxiliar paths be + changed, too. This is required in order for master paths to + retain their relation with auxiliar paths. This process of + keeping relation between master paths and auxiliar paths is + known as path syncronization. + + + + Path syncronization is required for automation scripts to know + where to store final output, where to retrive translation + messages, documentation, 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 may imply 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. + + + + The order followed to syncronize path information is very + important because the versioned nature of the repository files + we are working with. When a renaming action must be 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 except by texinfo backend of + help functionality which provides a restricted + implementation of path syncronization to this specific area of + documentation through the , + and + options. The plan for a full implementation of path + syncronization would be to create individual restricted + implementations like this one for other areas that demand it + and then, create a higher implmentation that combines all + restricted implementations as needed. This way, if we try to + rename a repository directory the higer action will define + which are all the restricted actions that should be performed + in order for make a full path syncronization. For example, if + the directory we are renaming is part of graphic design work + line, it is required to syncronize related paths in + documentation and localization work lines. Likewise, if the + directory we are renaming is in documentation work line, it is + required to syncronize related paths in graphic design and + localization work lines. In all these cases, the direction + used for syncronizing paths must be from master path to + auxiliar path and never the opposite (i.e., rename the master + path first and auxiliar paths later). + + + + A practical example, through which you can notice the + usefulness of path syncronization process, is what happen when + documentation entries are renamed (see section ...). + + + diff --git a/Manuals/Repository/Docbook/Introduction/Repoconvs/worklines.docbook b/Manuals/Repository/Docbook/Introduction/Repoconvs/worklines.docbook new file mode 100644 index 0000000..4d243f3 --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Repoconvs/worklines.docbook @@ -0,0 +1,65 @@ + + + Work Lines + + + Content production inside the repository is organized by + work lines. There are three major work + lines of production inside The CentOS Artwork Repository, + which are: Graphic design, + Documentation and + Localization. The specific way of + producing content inside each specific work line is + standardized by mean of centos-art.sh + script (which in turn, can be considered a work line by itself + [e.g., the Automation work line]). The + centos-art.sh script provides one specific + functionality for automating each major work line of content + production (e.g., render for producing images, + help for manage documentation, and + locale for localizing contents). + + + + The graphic design work line exists to cover brand design, + typography design and themes design mainly. Additionally, + some auxiliar areas like icon design, illustration design, + brushes design, patterns designs and palettes of colors are + also included here for completeness. The graphic design work + line is organized in the trunk/Identity directory. + + + + The documentation work line exists to describe what each + directory inside the CentOS Artwork Repository is for, the + conceptual ideas behind them and, if possible, how automation + scripts make use of them. The documentation work line is + organized in the trunk/Manuals directory. + + + + The localization work line exists to provide the translation + messages required to produce content in different languages. + Translation messages inside the repository are stored as + portable objects (e.g., .po, .pot) and machine objects (.mo). + The localization work line is organized in the trunk/Locales directory. + + + + The automation work line exists to standardize content + production inside the working copies of CentOS Artwork + Repository. Here is developed the + centos-art.sh script, a bash script + specially designed to automate most frequent tasks (e.g., + rendition, documentation and localization) inside the + repository. There is no need to type several tasks, time + after time, if they can be programmed into just one executable + script. The automation work line is organized in the + trunk/Scripts + directory. + + +