Identifying Document Structure
Once both the manual's title and the manual's directory name
have been defined, it is time for you to plan the document
structure through which the manual's content will be
organized.
The document structure of documentation manuals is specific to
that documentation format used to write documentation source
files. Nevertheless, no matter what the documentation format
be, the document structure produce produced from the
help functionality of
centos-art.sh script follows and
upside-down tree configuration. In this configuration,
documentation manuals can be organized through parts,
chapters, sections, and several subsection levels based in
whether the chosen documentation format supports them or not.
Considering the The CentOS Artwork Repository File
System documentation manual, we already know that
it was conceived to document each directory structure &TCAR;
is made of using Texinfo format and the sectioning levels
supported by it. At this point we phase that &TCAR; has more
levels deep than sectioning commands available inside Texinfo
formats. This way it is not possible to use one sectioning
command for each directory level inside the repository
directory structure we need to document. Based on these
issues, it is imperative to reaccomodate the document
structure in order to be able of documenting every directory
&TCAR; is made of, using the sectioning levels supported by
most documentation formats inside &TCD;, no matter how many
levels deep the repository directory structure has.
As consequence, The CentOS Artwork Repository File
System ended up being organized through the
following documentation structure:
Chapter 1. The trunk
Directory
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).
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;.
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 document structure illustrated above is also considered
the default document structure used by the
help functionality of
centos-art.sh script when you produce new
documentation manuals inside &TCAR;. In contrast with document
structure illustrated above, the default document structure
used by help functionality doesn't
include sectioning constructions like parts, chapters,
sections, subsections and the like. Such structuring
constructions should be specified by you when building the
documentation manual. The only exceptions to this restriction
are sectioning structures used to organize contents like
Index
and Licenses
, which are
considered inseparable components of documentation manuals
stored inside &TCAR;.