From 33f5203f76413ec454b1016b687dd5750925f13b Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Jun 22 2011 20:48:36 +0000 Subject: Update repository documentation manual in docbook format. --- diff --git a/Manuals/Repository/Docbook/Introduction.docbook b/Manuals/Repository/Docbook/Introduction.docbook index d483c3b..02e3d8d 100644 --- a/Manuals/Repository/Docbook/Introduction.docbook +++ b/Manuals/Repository/Docbook/Introduction.docbook @@ -28,7 +28,6 @@ &intro-copying; &intro-policy; &intro-worklines; - &intro-filenames; &intro-layout; diff --git a/Manuals/Repository/Docbook/Introduction.ent b/Manuals/Repository/Docbook/Introduction.ent index d730bd1..5d4917c 100644 --- a/Manuals/Repository/Docbook/Introduction.ent +++ b/Manuals/Repository/Docbook/Introduction.ent @@ -17,10 +17,11 @@ - - - - + + + + + diff --git a/Manuals/Repository/Docbook/Introduction/Filenames.docbook b/Manuals/Repository/Docbook/Introduction/Filenames.docbook deleted file mode 100644 index fccaea7..0000000 --- a/Manuals/Repository/Docbook/Introduction/Filenames.docbook +++ /dev/null @@ -1,27 +0,0 @@ - - - Repository File Names - - - Inside &TCAR;, 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/Layout.docbook b/Manuals/Repository/Docbook/Introduction/Layout.docbook index 048a0a6..16f3ba4 100644 --- a/Manuals/Repository/Docbook/Introduction/Layout.docbook +++ b/Manuals/Repository/Docbook/Introduction/Layout.docbook @@ -56,5 +56,10 @@ each directory inside &TCAR; is available at . + + &intro-layout-filenames; + &intro-layout-relbdirs; + &intro-layout-syncpaths; + &intro-layout-extending; diff --git a/Manuals/Repository/Docbook/Introduction/Layout/extending.docbook b/Manuals/Repository/Docbook/Introduction/Layout/extending.docbook new file mode 100644 index 0000000..3b050a6 --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Layout/extending.docbook @@ -0,0 +1,40 @@ + + + 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. + + + diff --git a/Manuals/Repository/Docbook/Introduction/Layout/filenames.docbook b/Manuals/Repository/Docbook/Introduction/Layout/filenames.docbook new file mode 100644 index 0000000..d66230a --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Layout/filenames.docbook @@ -0,0 +1,27 @@ + + + File Names + + + Inside &TCAR;, 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/Layout/relbdirs.docbook b/Manuals/Repository/Docbook/Introduction/Layout/relbdirs.docbook new file mode 100644 index 0000000..d97d300 --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Layout/relbdirs.docbook @@ -0,0 +1,123 @@ + + + Path Types + + + 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. + + + diff --git a/Manuals/Repository/Docbook/Introduction/Layout/syncpaths.docbook b/Manuals/Repository/Docbook/Introduction/Layout/syncpaths.docbook new file mode 100644 index 0000000..a6e8219 --- /dev/null +++ b/Manuals/Repository/Docbook/Introduction/Layout/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. + + + diff --git a/Manuals/Repository/Docbook/Introduction/Policy.docbook b/Manuals/Repository/Docbook/Introduction/Policy.docbook index f2ee617..cab31f8 100644 --- a/Manuals/Repository/Docbook/Introduction/Policy.docbook +++ b/Manuals/Repository/Docbook/Introduction/Policy.docbook @@ -1,24 +1,21 @@ - Repository Policy + Repository Usage Conditions &TCAR; 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 of &TCAR; to study its organization, make local + working copies of &TCAR; to study its layout, make local changes, test the changes really work the way expected and - finally, request access to commit them up to &TCAR; for others - to benefit from them. + finally, request access to publish them up. - 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. + Once you've received access to publish your changes and as + long as you behave as a good cooperating + citizen, there is no need for you to request + permission to publish new changes. @@ -42,7 +39,10 @@ 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 &TCPCVI; could - be built and maintained by &TCC; itself. + be built and maintained by &TCC; itself. Repository + administrators have the reposability of creating new user's + account, setting permissions and revoking publishing rights to + ill-willed users, as well. diff --git a/Manuals/Repository/Docbook/Introduction/Worklines.docbook b/Manuals/Repository/Docbook/Introduction/Worklines.docbook index 6f6987c..3e0c156 100644 --- a/Manuals/Repository/Docbook/Introduction/Worklines.docbook +++ b/Manuals/Repository/Docbook/Introduction/Worklines.docbook @@ -17,8 +17,5 @@ &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 deleted file mode 100644 index 5c9978a..0000000 --- a/Manuals/Repository/Docbook/Introduction/Worklines/extending.docbook +++ /dev/null @@ -1,42 +0,0 @@ - - - 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/relbdirs.docbook b/Manuals/Repository/Docbook/Introduction/Worklines/relbdirs.docbook deleted file mode 100644 index 22bf7f8..0000000 --- a/Manuals/Repository/Docbook/Introduction/Worklines/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/Worklines/syncpaths.docbook b/Manuals/Repository/Docbook/Introduction/Worklines/syncpaths.docbook deleted file mode 100644 index a6e8219..0000000 --- a/Manuals/Repository/Docbook/Introduction/Worklines/syncpaths.docbook +++ /dev/null @@ -1,96 +0,0 @@ - - - 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. - - -