aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml314
1 files changed, 0 insertions, 314 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
deleted file mode 100644
index 8b6c3e2361..0000000000
--- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
+++ /dev/null
@@ -1,314 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
-
- Redistribution and use in source (SGML DocBook) and 'compiled' forms
- (SGML HTML, PDF, PostScript, RTF and so forth) with or without
- modification, are permitted provided that the following conditions
- are met:
-
- 1. Redistributions of source code (SGML DocBook) must retain the above
- copyright notice, this list of conditions and the following
- disclaimer as the first lines of this file unmodified.
-
- 2. Redistributions in compiled form (transformed to other DTDs,
- converted to PDF, PostScript, RTF and other formats) must reproduce
- the above copyright notice, this list of conditions and the
- following disclaimer in the documentation and/or other materials
- provided with the distribution.
-
- THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
- IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
- INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
- (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
- SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
- STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
- ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
- POSSIBILITY OF SUCH DAMAGE.
-
--->
-<chapter xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
- xml:id="structure">
- <title>Documentation Directory Structure</title>
-
- <para>Files and directories in the
- <filename>doc/</filename> tree follow a
- structure meant to:</para>
-
- <orderedlist>
- <listitem>
- <para>Make it easy to automate converting the document to other
- formats.</para>
- </listitem>
-
- <listitem>
- <para>Promote consistency between the different documentation
- organizations, to make it easier to switch between working on
- different documents.</para>
- </listitem>
-
- <listitem>
- <para>Make it easy to decide where in the tree new documentation
- should be placed.</para>
- </listitem>
- </orderedlist>
-
- <para>In addition, the documentation tree must accommodate
- documents in many different languages and encodings. It is
- important that the documentation tree structure does not enforce
- any particular defaults or cultural preferences.</para>
-
- <sect1 xml:id="structure-top">
- <title>The Top Level,
- <filename>doc/</filename></title>
-
- <para>There are two types of directory under
- <filename>doc/</filename>, each with very
- specific directory names and meanings.</para>
-
- <informaltable pgwide="1" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Directory</entry>
- <entry>Usage</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry valign="top">
- <filename>share</filename></entry>
-
- <entry>Contains files that are not specific to the various
- translations and encodings of the documentation.
- Contains subdirectories to further categorize the
- information. For example, the files that comprise the
- &man.make.1; infrastructure are in
- <filename>share/mk</filename>, while the additional
- <acronym>XML</acronym> support files (such as the &os;
- extended DocBook <acronym>DTD</acronym>) are in
- <filename>share/xml</filename>.</entry>
- </row>
-
- <row>
- <entry valign="top">
- <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>
-
- <entry>One directory exists for each available translation
- and encoding of the documentation, for example
- <filename>en_US.ISO8859-1/</filename>
- and <filename>zh_TW.UTF-8/</filename>.
- The names are long, but by fully specifying the language
- and encoding we prevent any future headaches when a
- translation team wants to provide documentation in the
- same language but in more than one encoding. This also
- avoids problems that might be caused by a future switch
- to Unicode.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect1>
-
- <sect1 xml:id="structure-locale">
- <title>The
- <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename>
- Directories</title>
-
- <para>These directories contain the documents themselves. The
- documentation is split into up to three more categories at
- this level, indicated by the different directory names.</para>
-
- <informaltable pgwide="1" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Directory</entry>
- <entry>Usage</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry valign="top">
- <filename>articles</filename></entry>
-
- <entry>Documentation marked up as a DocBook
- <tag>article</tag> (or equivalent). Reasonably
- short, and broken up into sections. Normally only
- available as one <acronym>XHTML</acronym> file.</entry>
- </row>
-
- <row>
- <entry valign="top"><filename>books</filename></entry>
-
- <entry>Documentation marked up as a DocBook
- <tag>book</tag> (or equivalent). Book length,
- and broken up into chapters. Normally available as both
- one large <acronym>XHTML</acronym> file (for people with
- fast connections, or who want to print it easily from a
- browser) and as a collection of linked, smaller
- files.</entry>
- </row>
-
- <row>
- <entry valign="top">
- <filename>man</filename></entry>
-
- <entry>For translations of the system manual pages. This
- directory will contain one or more <filename
- role="directory">man<replaceable>N</replaceable></filename>
- directories, corresponding to the sections that have
- been translated.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>Not every <filename
- role="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
- directory will have all of these subdirectories. It depends on
- how much translation has been accomplished by that translation
- team.</para>
- </sect1>
-
- <sect1 xml:id="structure-document">
- <title>Document-Specific Information</title>
-
- <para>This section contains specific notes about particular
- documents managed by the FDP.</para>
-
- <sect2 xml:id="structure-document-handbook">
- <title>The Handbook</title>
-
- <subtitle><filename>books/handbook/</filename></subtitle>
-
- <para>The Handbook is written in DocBook <acronym>XML</acronym>
- using the &os; DocBook extended <acronym>DTD</acronym>.</para>
-
- <para>The Handbook is organized as a DocBook
- <tag>book</tag>. The book is divided into
- <tag>part</tag>s, each of which contains several
- <tag>chapter</tag>s. <tag>chapter</tag>s are
- further subdivided into sections (<tag>sect1</tag>)
- and subsections (<tag>sect2</tag>,
- <tag>sect3</tag>) and so on.</para>
-
- <sect3 xml:id="structure-document-handbook-physical">
- <title>Physical Organization</title>
-
- <para>There are a number of files and directories within the
- <filename>handbook</filename> directory.</para>
-
- <note>
- <para>The Handbook's organization may change over time, and
- this document may lag in detailing the organizational
- changes. Post questions about Handbook organization to
- the &a.doc;.</para>
- </note>
-
- <sect4 xml:id="structure-document-handbook-physical-Makefile">
- <title><filename>Makefile</filename></title>
-
- <para>The <filename>Makefile</filename> defines some
- variables that affect how the <acronym>XML</acronym>
- source is converted to other formats, and lists the
- various source files that make up the Handbook. It then
- includes the standard <filename>doc.project.mk</filename>,
- to bring in the rest of the code that handles converting
- documents from one format to another.</para>
- </sect4>
-
- <sect4 xml:id="structure-document-handbook-physical-book-xml">
- <title><filename>book.xml</filename></title>
-
- <para>This is the top level document in the Handbook. It
- contains the Handbook's <link
- linkend="xml-primer-doctype-declaration">DOCTYPE
- declaration</link>, as well as the elements that
- describe the Handbook's structure.</para>
-
- <para><filename>book.xml</filename> uses <link
- linkend="xml-primer-parameter-entities">parameter
- entities</link> to load in the files with the
- <filename>.ent</filename> extension. These files
- (described later) then define <link
- linkend="xml-primer-general-entities">general
- entities</link> that are used throughout the rest of the
- Handbook.</para>
- </sect4>
-
- <sect4
- xml:id="structure-document-handbook-physical-chapters-xml">
- <title><filename
- role="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title>
-
- <para>Each chapter in the Handbook is stored in a file
- called <filename>chapter.xml</filename> in a separate
- directory from the other chapters. Each directory is
- named after the value of the <literal>id</literal>
- attribute on the <tag>chapter</tag>
- element.</para>
-
- <para>For example, if one of the chapter files
- contains:</para>
-
- <programlisting><tag class="starttag">chapter id="kernelconfig"</tag>
-...
-<tag class="endtag">chapter</tag></programlisting>
-
- <para>Then it will be called
- <filename>chapter.xml</filename> in the
- <filename>kernelconfig</filename> directory. In general,
- the entire contents of the chapter are in this one
- file.</para>
-
- <para>When the <acronym>XHTML</acronym> version of the
- Handbook is produced, this will yield
- <filename>kernelconfig.html</filename>. This is because
- of the <literal>id</literal> value, and is not related to
- the name of the directory.</para>
-
- <para>In earlier versions of the Handbook, the files were
- stored in the same directory as
- <filename>book.xml</filename>, and named after the value
- of the <literal>id</literal> attribute on the file's
- <tag>chapter</tag> element. Now, it is possible to
- include images in each chapter. Images for each Handbook
- chapter are stored within
- <filename>share/images/books/handbook</filename>. The
- localized version of these images should be placed in the
- same directory as the <acronym>XML</acronym> sources for
- each chapter. Namespace collisions are inevitable, and it
- is easier to work with several directories with a few
- files in them than it is to work with one directory that
- has many files in it.</para>
-
- <para>A brief look will show that there are many directories
- with individual <filename>chapter.xml</filename> files,
- including <filename>basics/chapter.xml</filename>,
- <filename>introduction/chapter.xml</filename>, and
- <filename>printing/chapter.xml</filename>.</para>
-
- <important>
- <para>Do not name chapters or directories after
- their ordering within the Handbook. This ordering can
- change as the content within the Handbook is
- reorganized. Reorganization should be possible without
- renaming files, unless entire chapters are being
- promoted or demoted within the hierarchy.</para>
- </important>
-
- <para>The <filename>chapter.xml</filename> files are not
- complete <acronym>XML</acronym> documents that can be
- built individually. They can only be built
- as parts of the whole Handbook.</para>
- </sect4>
- </sect3>
- </sect2>
- </sect1>
-</chapter>