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 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 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,
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 .
Texinfo backend's document structure.
Texinfo backend's 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