From 32cd6d42ccdf5120769c31583bdaa184823e063a Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Aug 10 2011 16:52:40 +0000 Subject: Update `Manuals/Texinfo/production.docbook'. --- diff --git a/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook b/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook index d5e8216..0c10f88 100644 --- a/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook +++ b/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook @@ -7,9 +7,9 @@ format is realized through the help functionality of centos-art.sh script, as described in . To illustrate the - production cycle, we'll describe it here using the - Repository File System documentation manual as - reference. + production cycle, let us consider the creation of + Repository File System documentation manual, as + example. @@ -22,16 +22,17 @@ the very begining, explaining the whole idea of all directories inside &TCAR; on one manual was difficult, there were many changing concepts floting around which needed to be - considered. So, as a way to understand what I was doing, I - decided to adapt documentation to such changes through the - same principales I followed to create functionalities inside + considered in the same changing way. So, as a way to + understand what we were doing, it was decided to adapt + documentation to such changes through the same principales we + followed to create functionalities inside centos-art.sh script. This way, if programs should do one thing well, each directory inside the repository should be documented well in order to better understand what they do and how they relate one another. Later, summing all - directory documentations would let me, hypothetically, to + directory documentations would let us, hypothetically, to correct the whole idea through an improvement cycle that would - consolidate the final idea I try to implement. + consolidate the final idea we try to implement. @@ -39,18 +40,21 @@ manual is for, it is time for you to define the manual title and the manual directory name. The manual title describes, in few words, what the documentation manual is about. The manual - directory name must be one or more words separated by minus - sign. As convenction, to the manual directory name, it would - be convenient to use acronyms or abbreviations related to - manual's title. In our example, the documentation manual was - initially titled The CentOS Artwork Repository - but later it changed to Repository File System - and its manual directory name ended up being - Tcar-fs. + directory name describes the manual title in one or more words + separated by minus sign. + + ... a good convenction to follow here might be to use + acronyms or abbreviations from manual's title. + + + In our example, the documentation manual was initially titled + The CentOS Artwork Repository but later it + changed to Repository File System and its + manual directory name ended up being Tcar-fs. - Once both manual title and manual directory name have been + Once both manual's title and manual's directory name have been defined, it is time to planificate manual's content through chapters and sections. In our example, the documentation manual is made of three chapters named The The branches Directory and The tags Directory and one - appendix named License. Inside each chapter + appendix named Licenses. Inside each chapter there is one documentation section for each directory in &TCAR;. - To create a manual like that one described so far, you need to - introduce such organization through the help - functionality of centos-art.sh script, as - it is described in the following list of commands: + To create a manual like the one described so far, you need to + use the help functionality of + centos-art.sh script as it is described in + the following list of commands: @@ -78,10 +82,10 @@ - This command creates the tcar-fs manual base - structure and opens its main definition file with your - favorite text editor so you can fix values like title, - subtitle, author, etc. + This command creates the base structure of + tcar-fs manual and opens its main definition + file with your favorite text editor so you can update values + like title, subtitle, author, etc. @@ -92,9 +96,10 @@ - This command creates the introduction chapter - base structure and opens its main definition file with your - favorite text editor so you can fix the chapter introduction. + This command creates the base structure of + introduction chapter and opens its main + definition file with your favorite text editor so you can + update the chapter introduction. @@ -110,13 +115,28 @@ doesn't exist it will be created first. In this command, the identity section refers to trunk/Identity directory inside - &TCAR;. To document other directories, follow the same - procedure but using minus signs to separate directories. For - example, to document the trunk/Identity/Themes you would - use tcar-fs:trunk:identity-themes, and so on - for other directories. + &TCAR;. In order to document other directories, follow the + same procedure but using minus signs to separate directories. + For example, to document the trunk/Identity/Models/Themes + directory you should use the + tcar-fs:trunk:identity-models-themes + documentation entry. + + + + In the very specific case of tcar-fs + manual, it is possible to set chapter and section + documentation entries using the form path/to/dir, as well. For + example, to document the trunk/Identity/Models/Themes + directory you can execute the following command: + + centos-art help --edit trunk/Identity/Models/Themes + +