Blob Blame History Raw
<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 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
        <function>help</function> functionality of
        <command>centos-art.sh</command> 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.
    </para>

    <para>
        Considering the <citetitle>The CentOS Artwork Repository File
        System</citetitle> 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.
    </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
        <function>help</function> of <command>centos-art.sh</command>
        script inside &TCAR;.
    </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
        <function>help</function> 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 <function>help</function> 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
        <quote>Index</quote> and <quote>Licenses</quote>, which are
        considered inseparable components of documentation manuals
        stored inside &TCAR;.
    </para>

</sect1>