<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 <filename
        class="directory">trunk</filename> directory inside the
        repository and all subdirectories inside it. The first level
        of directories (i.e., the <filename
        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 <filename
        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 <filename
        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 <xref
        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 <xref
        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>