From f92c9e6ba0482e8df53f8de21a316c5732bd6eaa Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Sep 13 2011 22:38:49 +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 0c10f88..e283b3a 100644 --- a/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook +++ b/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook @@ -1,73 +1,176 @@ - - - Texinfo Document Production - - - The production of documentation manuals written in Texinfo - format is realized through the help functionality - of centos-art.sh script, as described in - . To illustrate the - production cycle, let us consider the creation of - Repository File System documentation manual, as - example. - - - - The first step for creating a documentation manual is to make - yourself an idea of what such manual intends to document. The - Repository File System emerged with the need of - understanding what each directory inside &TCAR; was for, how - they could be used and how they connected themselves one - another, as the repository structure itself was built on. At - 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 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 us, hypothetically, to - correct the whole idea through an improvement cycle that would - consolidate the final idea we try to implement. - - - - Once you've make yourself an idea of what the documentation - 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 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. + + + Texinfo Document Production Cycle + + + This section describes the procedure you should follow in + order to produce and maintain manuals through texinfo + documentation backend inside &TCAR;. To illustrate this + creation process, we'll use the TCAR-FS + manual as example. + + + Identifying Manual's Goals + + The first step to create a documentation manual is to make + yourself an idea of what such manual intends to document. As + the repository directory structure was built on, there was an + emerging need to understand what each directory inside it was + for, how they could be used and how they could be connected + one another. At that moment the structure was very unstable + and explaining the whole idea of all directories inside &TCAR; + on one manual was not possible, there were many changing + concepts floting around which needed to be considered in the + same changing way. + + + + To understand what we were doing, it was decided to document + each directory inside the repository in order to better + understand the concepts behind them one by one, as well as how + they relate one another. Later, summing all directory + documentations would let us, hypothetically, to correct the + whole idea through an improvement cycle that would consolidate + the final idea we try to implement. + + + + + + Identifying Manual's Title + + Once you've make yourself an clean idea of what the + documentation manual is for and the needs behind, it is time + for to define the manual's title and the manual's directory + name. Both manuals' title and manual's directory name + describe what the documentation manual is about. The manual's + title is used inside the documentation and the manual's + directory name is used to store the related source files + inside the repository. As convenction, manual's title is a + few words phrase while manual's directory name is the + abbreviation of that phrase set as manual's title. + + + + Following with our example, the documentation manual was + initially titled The CentOS Artwork Repository File + System but that name was too long to remain that way, + so it was abbreviated soon into TCAR-FS which + is less descriptive but easier to remember and doesn't need to + be translated into other languages. The related manual's + directory for it would be + Tcar-fs in order to comply + with the file name convenctions described at . + + + + + Identifying Manual's Structure 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 trunk Directory, - The branches - Directory and The tags Directory and one - appendix named Licenses. Inside each chapter - there is one documentation section for each directory in - &TCAR;. + defined, it is time to plan manual's structure through which + chapters and sections will be organized. The + TCAR-FS manual has been following the + same organization of &TCAR; directories. Each directory inside + the repository can have its own documentation entry to store + related information that let people to communicate thoughts + about its content. As we are using texinfo format to write + such documentation entries, it is possible to refer other + documentation entries through cross reference. + + + + At this point we phase that the repository directory structure + has more levels deep than those texinfo sectioning commands + can conver. Notice that this is not a Texinfo limitation since + content in most manuals can be very good organized with the + sectioning levels provided by Texinfo system. The thing is + that it is not possible to set one sectioning level for + each directory level deep inside the repository using Texinfo + sectioning command; the content organization must be + reaccomodated in order to fit the amount of sectioning + commands the Texinfo system provides. + + + + As consequence of sectioning limitations, the + TCAR-FS manual was structured in the + following chapters: + + + + + + Chapter 1. The trunk + Directory + + + ... + + + + + + Chapter 2. The branches + Directory + + + ... + + + + + + Chapter 3. The tags + Directory + + + ... + + + + + + + and the following appendixes: + + + + + Appendix A. Licenses + + + ... + + + + In addition to these chapters and appendixes, there is one + special unnumbered chapter named Index. This + chapter organizes all index related commands you use + inside the documentation manual. Notice that this information + is auto-generated each time the manual's output files are + created. + + + + + Implementing Manual's Structure + + + + Most production tasks related to documentation manuals written + in Texinfo format are standardized by the help + functionality of centos-art.sh script, as + described in . + + + 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 @@ -127,7 +230,7 @@ In the very specific case of tcar-fs - manual, it is possible to set chapter and section + manual, it is also possible to set chapter and section documentation entries using the form path/to/dir, as well. For example, to document the ... + + + Maintaining Manual's Structure + + ... + + +