diff --git a/Manuals/Tcar-ug/Manuals/Production/identifying-structure.docbook b/Manuals/Tcar-ug/Manuals/Production/identifying-structure.docbook index ce2d6e9..ba18edf 100644 --- a/Manuals/Tcar-ug/Manuals/Production/identifying-structure.docbook +++ b/Manuals/Tcar-ug/Manuals/Production/identifying-structure.docbook @@ -4,26 +4,28 @@ 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 + TCAR-FS manual follows the same + organization of &TCAR; directories so each directory inside + the repository does 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. + about the content it holds. As we are using documentation + formats to write documentation entries, it is also possible to + use all the features they permit to use (e.g., cross + references, index definition, etc.) to improve the whole + manual and the way information can be found inside it. - 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. + At this point we phase a repository directory structure with + more levels deep than sectioning commands supported by the + documentation formats that can be used to represent them. This + way it is not possible to use one sectioning level from + documentation format for each directory level inside the + repository. It is necessary to reaccomodate the document + structure in order to be able of documenting + all the directories &TCAR; is made of, + using the sectioning levels supported by most documentation + formats inside &TCD;. @@ -39,15 +41,18 @@ 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). + This chapter describes the trunk directory inside the + repository and all subdirectories 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). @@ -57,9 +62,10 @@ Directory - This chapter describes the branches - directory and all directories inside it following the same - structure described for trunk directory + This chapter describes the branches directory and all + directories inside it following the same structure described + for trunk directory above. @@ -70,9 +76,11 @@ Directory - This chapter describes the tags directory - and all directories inside it following the same structure - described for trunk directory above. + This chapter describes the tags directory and all + directories inside it following the same structure described + for trunk directory + above. @@ -87,7 +95,7 @@ documentation manuals written through the help of centos-art.sh script inside &TCAR;. To know how to edit the content of this - chapter, see ... + chapter, see @@ -107,18 +115,23 @@ - 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 . + The documentation structure depends on the documentation + format you used to create the documentation manual. The one + described so far (without the first three numbered chapters) + is the one produced by the help + functionality when Texinfo documentation format is used. + Likewise, other documentation formats were + programmed + + At time of this writting, only Texinfo documentation format + has been programmed inside the help + functionality. Other documentation formats like DocBook and + LaTeX are scheduled to be included in the future. + + inside the help functionality + to produce the same documentation structure that Texinfo + documentation format does but saving the internal differences + the documentation formts might have between themselves.