diff --git a/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook b/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook index e283b3a..92e1826 100644 --- a/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook +++ b/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook @@ -96,9 +96,9 @@ - As consequence of sectioning limitations, the - TCAR-FS manual was structured in the - following chapters: + As consequence of sectioning limitations described above, the + TCAR-FS manual was structured as + following: @@ -108,7 +108,15 @@ Directory - ... + This chapter describes the trunk + directory and all directories inside it. The first level of + directories (i.e., the trunk directory itself) is described + inside the chapter entry. Deeper directory levels are all + documented through sections and have a file for their own. It + is also possible to write subsections and subsubsections, + however, they don't have a file for their own as sections do. + Subsections and Subsubsections should be written as part of + section files (i.e., when writting sections). @@ -118,7 +126,10 @@ Directory - ... + This chapter describes the branches + directory and all directories inside it following the same + structure described for trunk directory + above. @@ -128,48 +139,62 @@ Directory - ... + This chapter describes the tags directory + and all directories inside it following the same structure + described for trunk directory above. - + + Appendix A. Licenses + - and the following appendixes: + This appendix is confined to organize licenses mentioned + in the manual. The content of this appendix is out of + documenatation manual scope itself and is shared among all + documentation manuals written through the + help of centos-art.sh + script inside &TCAR;. To know how to edit the content of this + chapter, see . + + - - Appendix A. Licenses + Index - ... + This chapter organizes links to those index definitions you + defined inside the documentation manual. The index information + displayed by this chapter is auto-generated each time the + manual's output files are created so this chapter is not + editable. - 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. + The structure of other documentation manuals is very similar + to that one described so far. When you create a new + documentation manual it is created with a base structure that + includes the Licenses appendix and the + Index unnumbered chapter only. This structure + is ready for output but you surely found it useless since no + content is described in it (execpt for the licenses, of + course). In order to describe inside a documentation manual + recently created, you need to create the chapters it will have + and the sections inside them, as described in . + - + 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 @@ -181,35 +206,39 @@ - centos-art help --edit tcar-fs + centos-art help --edit "tcar-fs" 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. + TCAR-FS manual and opens its main + definition file with your favorite text editor so you can + update manual's definition values like title, subtitle, + author, etc. - centos-art help --edit tcar-fs::introduction + centos-art help --edit "tcar-fs::trunk" - 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. + This command creates the base structure for the + trunk chapter and opens its main definition + file with your favorite text editor so you can update the + chapter introduction. This very same procedure is used to + create branches and tags + chapters, just be sure to change the chapter field + accordingly. - centos-art help --edit tcar-fs::trunk:identity + centos-art help --edit "tcar-fs::trunk:identity" @@ -220,40 +249,41 @@ class="directory">trunk/Identity directory inside &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 + For example, to document the trunk/Identity/Models/Themes directory you should use the - tcar-fs:trunk:identity-models-themes + tcar-fs::trunk:identity-models-themes documentation entry. - In the very specific case of tcar-fs - 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 trunk/Identity/Models/Themes - directory you can execute the following command: - - centos-art help --edit trunk/Identity/Models/Themes + In the very specific case of + TCAR-FS manual, it is also possible + to refer chapters and sections using a path/to/dir format. + For example, the reference + tcar-fs::trunk:identity-models-themes + can also be specified as trunk/Identity/Models/Themes, + in case you feel more confortable with it than the former + one. - - - ... - Maintaining Manual's Structure - ... + Most maintaining tasks related to documentation manuals + written through texinfo documentation backend are standardized + by the help functionality of + centos-art.sh script, as described in .