From 8c6bbc896b14f150303f7a163aeb1b84a7a55f2c Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Aug 04 2011 19:52:24 +0000 Subject: Update `Manuals/Texinfo/structure.docbook'. --- diff --git a/Manuals/Tcar-ug/Manuals/Texinfo/structure.docbook b/Manuals/Tcar-ug/Manuals/Texinfo/structure.docbook index 42c26a2..5a01699 100644 --- a/Manuals/Tcar-ug/Manuals/Texinfo/structure.docbook +++ b/Manuals/Tcar-ug/Manuals/Texinfo/structure.docbook @@ -1,128 +1,81 @@ - + Texinfo Document Structure - The document structure provides the organization needed to - make the documentation scalable and maintainable through time - which, in turn, involves document sectioning and file - organization inside specific locations of the working copy. - The document structure is also a convenction we adopt in order - to automate frequent tasks related to the document structure - itself. Without a well defined document structure convenction, - it would be very difficult for automation script to guess - where the documentation files are. + The document structure provided by texinfo backend creates the + organization needed to make documentation manuals scalable and + maintainable through time. Structuring considerations follows + the idea of an upside-down tree to organize chapters, + sections, subsections, and the like. The document initiates + with a Top node where we place document title, copyright note, + abstract, and the list of chapters. Inside each chapter the + information is logically organized in sections, subsections + and subsubsections. - - The file organization of Texinfo documentation backend takes - place in trunk/Manuals/Repository/Texinfo/ - directory. Inside this location there is one documentation - structure for each language you want to support and the - repository-init.pl and - repository.sed files which let you - control common characteristics of final XHTML output (e.g., - texi2html initialization, and markup - transformations). - - - - The document sectioning follows the idea of an upside-down - tree to organize chapters, sections, subsections, and the - like. The document initiates with a Top node where we placed - document's title, copyright note, abstract, and a list of - available chapters to start browsing. Inside each chapter the - information is logically organized in sections which in turn - are subdivided in subsections and subsubsections. + + The first time you create a documentation manual through + texinfo backend, the centos-art.sh script + considers the working directory you are placed in order to + determine where to store the documentation manual. When the + current working directory is branches/Manuals/Texinfo, the + documentation manual directory is created therein. On all + other situations, the documentation manual directory is + created under trunk/Manuals directory. Once + the documentation manual directory has been created, the + centos-art.sh script creates its definition + files in conjuction with an appendix named + Licenses. The content of licenses stored in + the Licenses appendix isn't inside the documentation manual + directory but refered from texinfo document templates, as + described at , so + the help functionality cannot control it. - The Texinfo document structure produced by - help functionality organizes information - in two chapters only, which are: - - - - - - Directories — This chapter organizes documentation - entries related to repository directories. In the normal - work flow, you don't need to touch the files of this - chapter by your own. For that purpose, the - centos-art.sh script porovides the - help functionality. To manipulate - documentation entries in this chapter, you use the - help functionality as described in - . - - - - - - Licenses — This chapter includes licenses from - trunk/Scripts/Functions/Help/Texinfo/Templates/language/Licenses/ - directory. In the normal work flow, you don't need to - touch this chapter. It is created when the document - structure is created and should ramain that way. If you - need to improve the markup, update the template files for - your language, not the content of this chapter. - - - - - - - - - At the same level of chapter directories, the - repository.texinfo, - repository-index.texinfo, - repository-menu.texinfo and - repository-nodes.texinfo files exist to - set manual's main definitions (e.g., title, copyright notice, - chapters, appendixes, indexes and all the similar stuff a - documentation manual should have). - - - Inside each chapter directory, the - chapter.texinfo, + Inside the documentation manual directory, the + ${MANUAL_NAME}.texinfo, + ${MANUAL_NAME}-index.texinfo, + ${MANUAL_NAME}-menu.texinfo and + ${MANUAL_NAME}-nodes.texinfo files exist to + set manual's main definitions; including title, copyright + notice, chapters, appendixes, indexes and all the similar + stuff a documentation manual should have. Inside each chapter + directory, the chapter.texinfo, chapter-menu.texinfo and chapter-nodes.texinfo files exist to - control definition of sections. In addition to these files, - there are documentation entries to store the document's content - itself, using arbitrary file names prefixed with the texinfo extension, just as it is - illustrated in . + control section definitions, related to the chapter they are + stored in. The documentation manual content itself is stored + in section files (a.k.a. documentation entries) + suffixed with texinfo + extension and arbitrarily named, as describes. - Texinfo backend's document structure. + Texinfo document structure. - Texinfo backend's document structure. + Texinfo document structure. - trunk/Manuals/Repository/Texinfo -|-- en_US -| |-- Directories -| | |-- chapter-menu.texinfo -| | |-- chapter-nodes.texinfo -| | |-- chapter.texinfo -| | |-- trunk/Identity.texinfo -| | `-- trunk.texinfo -| |-- Licenses -| | |-- chapter-menu.texinfo -| | |-- chapter-nodes.texinfo -| | `-- chapter.texinfo -| |-- repository-index.texinfo -| |-- repository-menu.texinfo -| |-- repository-nodes.texinfo -| `-- repository.texinfo -|-- repository-init.pl -|-- repository.css -`-- repository.sed + trunk/Manuals/${MANUAL_NAME} +`-- ${LANG} + |-- ${CHAPTER_NAME} + | |-- chapter-menu.texinfo + | |-- chapter-nodes.texinfo + | |-- chapter.texinfo + | `-- ${SECTION_NAME}.texinfo + |-- Licenses + | |-- chapter-menu.texinfo + | |-- chapter-nodes.texinfo + | `-- chapter.texinfo + |-- ${MANUAL_NAME}-index.texinfo + |-- ${MANUAL_NAME}-menu.texinfo + |-- ${MANUAL_NAME}-nodes.texinfo + `-- ${MANUAL_NAME}.texinfo