diff options
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.xml | 314 |
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> |