From 97869219af673632ca91a4771413b986007b089e Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Jun 22 2011 17:33:25 +0000 Subject: Update repository documentation manual in docbook format. --- diff --git a/Manuals/Repository/Docbook/Introduction.docbook b/Manuals/Repository/Docbook/Introduction.docbook index 32dee77..c83b0dc 100644 --- a/Manuals/Repository/Docbook/Introduction.docbook +++ b/Manuals/Repository/Docbook/Introduction.docbook @@ -1,4 +1,4 @@ - + Introduction diff --git a/Manuals/Repository/Docbook/Introduction/Repoconvs/extending.docbook b/Manuals/Repository/Docbook/Introduction/Repoconvs/extending.docbook index afc2859..d974d41 100644 --- a/Manuals/Repository/Docbook/Introduction/Repoconvs/extending.docbook +++ b/Manuals/Repository/Docbook/Introduction/Repoconvs/extending.docbook @@ -3,68 +3,40 @@ Extending Repository Organization - Occasionly, you may find that new components of &TCP; - 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? + 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? - The best place to find answers is in &TCC; (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 &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 a conceptual idea - that justifies its existence. + 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 conceptual idea first and later create the + to define the concept behind it 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 + documentation, the trunk/L10n 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. + 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/Repoconvs/filenames.docbook b/Manuals/Repository/Docbook/Introduction/Repoconvs/filenames.docbook index a0ae48e..777bb74 100644 --- a/Manuals/Repository/Docbook/Introduction/Repoconvs/filenames.docbook +++ b/Manuals/Repository/Docbook/Introduction/Repoconvs/filenames.docbook @@ -3,8 +3,8 @@ File Names - Inside &TCAR; directory structure, file names are all written - in lowercase (e.g., 01-welcome.png, + 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., - &TCAR; is organized through a convenctional - trunk, branches and - tags layout. + The first level of directories in the repository provides + organization through a convenctional trunk, + branches and tags layout. In + this configuration the trunk directory is where main + changes take place, the tags directory is where frozen + copies of trunk changes + are placed in for releasing, and the branches directory is an + intermediate place between trunk and tags states where changes take + place before being merged into trunk and finally released into + tags. + + + + The second level of directories in the repository provides + organization for each work line described in . + + + + All other subsequent levels of directories in the repository, + from third level on, are created to organize specific concepts + related to the work line they are in. A complete reference for + each directory inside &TCAR; is available at . diff --git a/Manuals/Repository/Docbook/Introduction/Repoconvs/syncpaths.docbook b/Manuals/Repository/Docbook/Introduction/Repoconvs/syncpaths.docbook index e619722..a651c66 100644 --- a/Manuals/Repository/Docbook/Introduction/Repoconvs/syncpaths.docbook +++ b/Manuals/Repository/Docbook/Introduction/Repoconvs/syncpaths.docbook @@ -3,21 +3,20 @@ 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 + 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 - 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 + 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 @@ -25,29 +24,28 @@ - Path syncronization may imply both movement of files and + 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. + file locations consistent one another after the movement. 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. + 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 @@ -56,39 +54,40 @@ 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). + 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. + + - A practical example, through which you can notice the - usefulness of path syncronization process, is what happen when - documentation entries are renamed (see section ...). + 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/repository.docbook b/Manuals/Repository/Docbook/repository.docbook index d83e220..4bd43a7 100644 --- a/Manuals/Repository/Docbook/repository.docbook +++ b/Manuals/Repository/Docbook/repository.docbook @@ -10,6 +10,7 @@ + %Commons.ent; @@ -19,6 +20,7 @@ %Locales.ent; %Manuals.ent; %Scripts.ent; +%Directories.ent; %Licenses.ent; ]> @@ -81,6 +83,7 @@ &locales; &manuals; &scripts; + &dirs; &licenses;