diff options
Diffstat (limited to 'zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml')
| -rw-r--r-- | zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml new file mode 100644 index 0000000000..c4feee84cb --- /dev/null +++ b/zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml @@ -0,0 +1,281 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- 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. + + $FreeBSD$ + Original revision: 1.17 +--> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="structure"> + <title>Structuring documents under <filename>doc/</filename></title> + + <para>The <filename>doc/</filename> tree is organized in a particular + fashion, and the documents that are part of the FDP are in turn organized + in a particular fashion. The aim is to make it simple to add new + documentation into the tree and:</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 has to accommodate documentation + that could be in many different languages and in many different + encodings. It is important that the structure of the documentation tree + 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> + + <segmentedlist> + <segtitle>Directory</segtitle> + + <segtitle>Meaning</segtitle> + + <seglistitem> + <seg><filename>share/</filename></seg> + + <seg>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 SGML support + files (such as the FreeBSD extended DocBook DTD) are in + <filename>share/xml</filename>.</seg> + </seglistitem> + + <seglistitem> + <seg><filename>lang.encoding/</filename></seg> + + <seg>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 + should a translation team want to provide the documentation in the + same language but in more than one encoding. This also completely + isolates us from any problems that might be caused by a switch to + Unicode.</seg> + </seglistitem> + </segmentedlist> + </sect1> + + <sect1 xml:id="structure-locale"> + <title>The + <filename>lang.encoding/</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> + + <segmentedlist> + <segtitle>Directory</segtitle> + + <segtitle>Contents</segtitle> + + <seglistitem> + <seg><filename>articles</filename></seg> + + <seg>Documentation marked up as a DocBook <tag>article</tag> + (or equivalent). Reasonably short, and broken up into sections. + Normally only available as one HTML file.</seg> + </seglistitem> + + <seglistitem> + <seg><filename>books</filename></seg> + + <seg>Documentation marked up as a DocBook <tag>book</tag> (or + equivalent). Book length, and broken up into chapters. Normally + available as both one large HTML file (for people with fast + connections, or who want to print it easily from a browser) and + as a collection of linked, smaller files.</seg> + </seglistitem> + + <seglistitem> + <seg><filename>man</filename></seg> + + <seg>For translations of the system manual pages. This directory will + contain one or more + <filename>mann</filename> directories, + corresponding to the sections that have been translated.</seg> + </seglistitem> + </segmentedlist> + + <para>Not every + <filename>lang.encoding</filename> directory will contain all of these directories. 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> + <title>The Handbook</title> + + <subtitle><filename>books/handbook/</filename></subtitle> + + <para>The Handbook is written to comply with the FreeBSD DocBook + extended DTD.</para> + + <para>The Handbook is organized as a DocBook <tag>book</tag>. + It is then divided into <tag>part</tag>s, each of which may + contain 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> + <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. If you + have any questions about how the Handbook is organized, please + contact the &a.doc;.</para> + </note> + + <sect4> + <title><filename>Makefile</filename></title> + + <para>The <filename>Makefile</filename> defines some variables that + affect how the SGML 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> file, to + bring in the rest of the code that handles converting documents + from one format to another.</para> + </sect4> + + <sect4> + <title><filename>book.xml</filename></title> + + <para>This is the top level document in the Handbook. It contains + the Handbook's <link linkend="sgml-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="sgml-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="sgml-primer-general-entities">general + entities</link> that are used throughout the rest of the + Handbook.</para> + </sect4> + + <sect4> + <title><filename>directory/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><![CDATA[ +<chapter id="kernelconfiguration"> +... +</chapter>]]></programlisting> + + <para>then it will be called <filename>chapter.xml</filename> in + the <filename>kernelconfiguration</filename> directory. In + general, the entire contents of the chapter will be held in this + file.</para> + + <para>When the HTML version of the Handbook is produced, this will + yield <filename>kernelconfiguration.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. Moving them into + separate directories prepares for future plans for the Handbook. + Specifically, it will soon be possible to include images in each + chapter. It makes more sense for each image to be stored in a + directory with the text for the chapter than to try to keep the + text for all the chapters, and all the images, in one large + directory. Namespace collisions would be 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>Chapters and/or directories should not be named in a fashion + that reflects their ordering within the Handbook. This ordering + might change as the content within the Handbook is reorganized; + this sort of reorganization should not (generally) include the + need to rename files (unless entire chapters are being promoted + or demoted within the hierarchy).</para> + </important> + + <para>Each <filename>chapter.xml</filename> file will not be a + complete SGML document. In particular, they will not have their + own DOCTYPE lines at the start of the files.</para> + + <para>This is unfortunate as + it makes it impossible to treat these as generic SGML + files and simply convert them to HTML, RTF, PS, and other + formats in the same way the main Handbook is generated. This + <emphasis>would</emphasis> force you to rebuild the Handbook + every time you want to see the effect a change has had on just + one chapter.</para> + </sect4> + </sect3> + </sect2> + </sect1> +</chapter> |