|
|
1c9079 |
<sect1 id="manuals-production-identifying-structure">
|
|
|
1c9079 |
<title>Identifying Document Structure</title>
|
|
|
1c9079 |
<para>
|
|
|
f69538 |
Once both the manual's title and the manual's directory name
|
|
|
f69538 |
have been defined, it is time for you to plan the document
|
|
|
f69538 |
structure through which the manual's content will be
|
|
|
f69538 |
organized.
|
|
|
f69538 |
</para>
|
|
|
f69538 |
|
|
|
f69538 |
<para>
|
|
|
864d0d |
The specific document structure you choose for a documentation
|
|
|
864d0d |
manuals is affected by the documentation format you use to
|
|
|
864d0d |
write documentation source files. Nevertheless, no matter
|
|
|
864d0d |
what the documentation format be, the document structure
|
|
|
864d0d |
produced from the <xref linkend="scripts-bash-help" />
|
|
|
864d0d |
functionality will always follow and upside-down tree
|
|
|
864d0d |
configuration for document structures. In this configuration,
|
|
|
864d0d |
documentation manuals can be organized through different
|
|
|
864d0d |
structural levels (e.g., parts, chapters, sections,
|
|
|
864d0d |
subsection, etc.) based on the support provided by the
|
|
|
864d0d |
documentation format you chose.
|
|
|
1c9079 |
</para>
|
|
|
1c9079 |
|
|
|
1c9079 |
<para>
|
|
|
864d0d |
The <citetitle>The CentOS Artwork Repository File
|
|
|
864d0d |
System</citetitle> documentation manual was conceived to
|
|
|
864d0d |
document each directory structure &TCAR; is made of, using
|
|
|
864d0d |
Texinfo as main documentation format.
|
|
|
864d0d |
</para>
|
|
|
864d0d |
|
|
|
864d0d |
<para>
|
|
|
864d0d |
At this point we find that &TCAR; had more levels deep than
|
|
|
864d0d |
sectioning commands available inside documentation format.
|
|
|
864d0d |
This way it is not possible to use one sectioning command for
|
|
|
864d0d |
each directory level inside the repository directory structure
|
|
|
864d0d |
we need to document. Based on these issues, it is
|
|
|
864d0d |
imperative to re-accommodate the document structure in order
|
|
|
864d0d |
to be able of documenting every directory &TCAR; is made of,
|
|
|
864d0d |
using the sectioning levels supported by that documentation
|
|
|
864d0d |
format we chose, no matter how many levels deep the repository
|
|
|
864d0d |
directory structure had.
|
|
|
1c9079 |
</para>
|
|
|
f69538 |
|
|
|
1c9079 |
<para>
|
|
|
f69538 |
As consequence, <citetitle>The CentOS Artwork Repository File
|
|
|
f69538 |
System</citetitle> ended up being organized through the
|
|
|
f69538 |
following documentation structure:
|
|
|
1c9079 |
</para>
|
|
|
1c9079 |
|
|
|
1c9079 |
<variablelist>
|
|
|
1c9079 |
<varlistentry>
|
|
|
1c9079 |
<term>Chapter 1. The <filename class="directory">trunk</filename>
|
|
|
1c9079 |
Directory</term>
|
|
|
1c9079 |
<listitem>
|
|
|
1c9079 |
<para>
|
|
|
7ade69 |
This chapter describes the
|
|
|
7ade69 |
class="directory">trunk</filename> directory inside the
|
|
|
7ade69 |
repository and all subdirectories inside it. The first level
|
|
|
7ade69 |
of directories (i.e., the
|
|
|
7ade69 |
class="directory">trunk</filename> directory itself) is
|
|
|
7ade69 |
described inside the chapter entry. Deeper directory levels
|
|
|
7ade69 |
are all documented through sections and have a file for their
|
|
|
7ade69 |
own. It is also possible to write subsections and
|
|
|
7ade69 |
subsubsections, however, they don't have a file for their own
|
|
|
7ade69 |
as sections do. Subsections and Subsubsections should be
|
|
|
7ade69 |
written as part of section files (i.e., when writting
|
|
|
7ade69 |
sections).
|
|
|
1c9079 |
</para>
|
|
|
1c9079 |
</listitem>
|
|
|
1c9079 |
</varlistentry>
|
|
|
1c9079 |
|
|
|
1c9079 |
<varlistentry>
|
|
|
1c9079 |
<term>Chapter 2. The <filename class="directory">branches</filename>
|
|
|
1c9079 |
Directory</term>
|
|
|
1c9079 |
<listitem>
|
|
|
1c9079 |
<para>
|
|
|
7ade69 |
This chapter describes the
|
|
|
7ade69 |
class="directory">branches</filename> directory and all
|
|
|
7ade69 |
directories inside it following the same structure described
|
|
|
7ade69 |
for <filename class="directory">trunk</filename> directory
|
|
|
1c9079 |
above.
|
|
|
1c9079 |
</para>
|
|
|
1c9079 |
</listitem>
|
|
|
1c9079 |
</varlistentry>
|
|
|
1c9079 |
|
|
|
1c9079 |
<varlistentry>
|
|
|
1c9079 |
<term>Chapter 3. The <filename class="directory">tags</filename>
|
|
|
1c9079 |
Directory</term>
|
|
|
1c9079 |
<listitem>
|
|
|
1c9079 |
<para>
|
|
|
7ade69 |
This chapter describes the
|
|
|
7ade69 |
class="directory">tags</filename> directory and all
|
|
|
7ade69 |
directories inside it following the same structure described
|
|
|
7ade69 |
for <filename class="directory">trunk</filename> directory
|
|
|
7ade69 |
above.
|
|
|
1c9079 |
</para>
|
|
|
1c9079 |
</listitem>
|
|
|
1c9079 |
</varlistentry>
|
|
|
1c9079 |
|
|
|
1c9079 |
<varlistentry>
|
|
|
1c9079 |
<term>Appendix A. Licenses</term>
|
|
|
1c9079 |
<listitem>
|
|
|
1c9079 |
<para>
|
|
|
1c9079 |
This appendix is confined to organize licenses mentioned
|
|
|
1c9079 |
in the manual. The content of this appendix is out of
|
|
|
1c9079 |
documenatation manual scope itself and is shared among all
|
|
|
864d0d |
documentation manuals written through the
|
|
|
864d0d |
linkend="scripts-bash-help" /> functionality.
|
|
|
1c9079 |
</para>
|
|
|
1c9079 |
</listitem>
|
|
|
1c9079 |
</varlistentry>
|
|
|
1c9079 |
|
|
|
1c9079 |
<varlistentry>
|
|
|
1c9079 |
<term>Index</term>
|
|
|
1c9079 |
<listitem>
|
|
|
1c9079 |
<para>
|
|
|
1c9079 |
This chapter organizes links to those index definitions you
|
|
|
1c9079 |
defined inside the documentation manual. The index information
|
|
|
1c9079 |
displayed by this chapter is auto-generated each time the
|
|
|
1c9079 |
manual's output files are created so this chapter is not
|
|
|
1c9079 |
editable.
|
|
|
1c9079 |
</para>
|
|
|
1c9079 |
</listitem>
|
|
|
1c9079 |
</varlistentry>
|
|
|
1c9079 |
</variablelist>
|
|
|
1c9079 |
|
|
|
1c9079 |
<para>
|
|
|
f69538 |
The document structure illustrated above is also considered
|
|
|
864d0d |
the default document structure used by the
|
|
|
864d0d |
linkend="scripts-bash-help" /> functionality of
|
|
|
f69538 |
<command>centos-art.sh</command> script when you produce new
|
|
|
f69538 |
documentation manuals inside &TCAR;. In contrast with document
|
|
|
f69538 |
structure illustrated above, the default document structure
|
|
|
864d0d |
used by <xref linkend="scripts-bash-help" /> functionality
|
|
|
864d0d |
doesn't include sectioning constructions like parts, chapters,
|
|
|
864d0d |
sections, subsections and the like in the document structure
|
|
|
864d0d |
created. Such structuring constructions should be specified by
|
|
|
864d0d |
you when building the documentation manual. The only
|
|
|
864d0d |
exceptions to this restriction are sectioning structures used
|
|
|
864d0d |
to organize contents like <quote>Index</quote> and
|
|
|
864d0d |
<quote>Licenses</quote>, which are considered inseparable
|
|
|
864d0d |
components of documentation manuals stored inside &TCAR;.
|
|
|
1c9079 |
</para>
|
|
|
1c9079 |
|
|
|
1c9079 |
</sect1>
|