<sect1 id="manuals-production-identifying-structure">

    <title>Identifying Document Structure</title>

    <para>

        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.

    </para>

    <para>

        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 <xref linkend="scripts-bash-help" />

        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.

    </para>

    <para>

        The <citetitle>The CentOS Artwork Repository File

        System</citetitle> documentation manual was conceived to

        document each directory structure &TCAR; is made of, using

        Texinfo as main documentation format.

    </para>

    <para>

        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.

    </para>

    <para>

        As consequence,  <citetitle>The CentOS Artwork Repository File

        System</citetitle> ended up being organized through the

        following documentation structure:

    </para>

    <variablelist>

    <varlistentry>

    <term>Chapter 1. The <filename class="directory">trunk</filename>

    Directory</term>

    <listitem>

    <para>

        This chapter describes the 

        class="directory">trunk</filename> directory inside the

        repository and all subdirectories inside it. The first level

        of directories (i.e., the 

        class="directory">trunk</filename> 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).

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>Chapter 2. The <filename class="directory">branches</filename>

    Directory</term>

    <listitem>

    <para>

        This chapter describes the 

        class="directory">branches</filename> directory and all

        directories inside it following the same structure described

        for <filename class="directory">trunk</filename> directory

        above.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>Chapter 3. The <filename class="directory">tags</filename>

    Directory</term>

    <listitem>

    <para>

        This chapter describes the 

        class="directory">tags</filename> directory and all

        directories inside it following the same structure described

        for <filename class="directory">trunk</filename> directory

        above.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>Appendix A. Licenses</term>

    <listitem>

    <para>

        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 

        linkend="scripts-bash-help" /> functionality.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>Index</term>

    <listitem>

    <para>

        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.

    </para>

    </listitem>

    </varlistentry>

    </variablelist>

    <para>

        The document structure illustrated above is also considered

        the default document structure used by the 

        linkend="scripts-bash-help" /> functionality of

        <command>centos-art.sh</command> script when you produce new

        documentation manuals inside &TCAR;. In contrast with document

        structure illustrated above, the default document structure

        used by <xref linkend="scripts-bash-help" /> 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 <quote>Index</quote> and

        <quote>Licenses</quote>, which are considered inseparable

        components of documentation manuals stored inside &TCAR;.

    </para>

</sect1>