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 specific document structure you choose for a documentation
manuals is affected by the documentation format you use to
write documentation source files. Nevertheless, no matter
what the documentation format be, the document structure
produced from the
functionality will always follow and upside-down tree
configuration for document structures. In this configuration,
documentation manuals can be organized through different
structural levels (e.g., parts, chapters, sections,
subsection, etc.) based on the support provided by the
documentation format you chose.
The The CentOS Artwork Repository File
System documentation manual was conceived to
document each directory structure &TCAR; is made of, using
Texinfo as main documentation format.
At this point we find that &TCAR; had more levels deep than
sectioning commands available inside documentation format.
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 re-accommodate the document structure in order
to be able of documenting every directory &TCAR; is made of,
using the sectioning levels supported by that documentation
format we chose, no matter how many levels deep the repository
directory structure had.
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 functionality.
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 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 functionality
doesn't include sectioning constructions like parts, chapters,
sections, subsections and the like in the document structure
created. 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;.