diff --git a/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook b/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook index 7fd2f87..e69de29 100644 --- a/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook +++ b/Manuals/Tcar-ug/Manuals/Texinfo/production.docbook @@ -1,296 +0,0 @@ - - - Texinfo Document Production Cycle - - - This section describes the procedure you should follow 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 Document Goals - - Before the TCAR-FS exit, there was an - emerging need to understand what each directory inside the - growing repository layout was for, how they could be used and - how they could be connected one another. At that moment the - directory structure was very unstable and explaining the whole - idea behind it wouldn't be possible, there were many changing - concepts floating around which needed to be considered in the - same changing way. So, to understand what was happening, the - TCAR-FS documentation manual appeared. - - - - The TCAR-FS manual let us to document - each directory inside the repository individually and, later, - by considering all directory documentations together, it would - be possible (hypothetically) to correct the whole idea through - an improvement cycle that would consolidate the final idea we - try to implement. - - - - The characteristics of other documentation manuals will surely - be different from those described above, however, it would be - helpful to make yourself an clean idea about what you are - going to document exactly before putting your hands on it. - - - - - - Identifying Document 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 Document Structure - - Once both manual's title and manual's directory name have been - 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 described above, the - TCAR-FS manual was structured as - following: - - - - - - Chapter 1. The trunk - 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). - - - - - - Chapter 2. The branches - Directory - - - This chapter describes the branches - directory and all directories inside it following the same - structure described for trunk directory - above. - - - - - - Chapter 3. The tags - Directory - - - This chapter describes the tags directory - and all directories inside it following the same structure - described for trunk directory above. - - - - - - Appendix A. Licenses - - - 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 . - - - - - - 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. - - - - - - - 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 Document Structure - - - To create a manual like the one described , - you need to use the help functionality of - centos-art.sh script as it is described in - the following list of commands: - - - - - - - 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 manual's definition values like title, subtitle, - author, etc. - - - - - - - centos-art help --edit "tcar-fs::trunk" - - - - 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" - - - - This command creates the identity section - inside the trunk chapter. If the chapter - doesn't exist it will be created first. In this command, the - identity section refers to 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 - directory you should use the - tcar-fs::trunk:identity-models-themes - documentation entry. - - - - - 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 Document 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 . - - - -