diff options
Diffstat (limited to 'en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml')
| -rw-r--r-- | en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml | 299 |
1 files changed, 299 insertions, 0 deletions
diff --git a/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml new file mode 100644 index 0000000000..0fcb999857 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml @@ -0,0 +1,299 @@ +<!-- 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. + + $Id: chapter.sgml,v 1.1 1999-09-03 17:22:38 nik Exp $ +--> + +<chapter id="structure"> + <title>Structuring documents under <filename>doc/</filename></title> + + <para>The <filename>doc/</filename> tree is organised in a particular + fashion, and the documents that are part of the FDP are in turn organised + in a particular fashion. The aim is to make it simple to add new + documentation in to the tree and;</para> + + <orderedlist> + <listitem> + <para>be easy to automate converting the document to other formats</para> + </listitem> + + <listitem> + <para>promote consistency between the different documentation + organisations, 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> + <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> + <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 categorise 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/sgml</filename>.</seg> + </seglistitem> + + <seglistitem> + <seg><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename></seg> + + <seg>One directory exists for each available translation and encoding + of the documentation, for example + <filename>en_US.ISO_8859-1/</filename> and + <filename>zh_TW.Big5/</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> + <title>The + <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> directories</title> + + <para>These directories contain the documents themselves. The + documentation is split in to up to three more categories at this + level, indicated by the different directory names.</para> + + <segmentedlist> + <seglistitem> + <seg><filename>articles</filename></seg> + + <seg>Documentation marked up as a DocBook <sgmltag>article</sgmltag> + (or equivalent). Reasonably short, and broken up in to sections. + Normally only available as one HTML file.</seg> + </seglistitem> + + <seglistitem> + <seg><filename>books</filename></seg> + + <seg>Documentation marked up as a DocBook <sgmltag>book</sgmltag> (or + equivalent). Book length, and broken up in to chapters. Normally + available as both one large HTML file (for people with fast + connections, or who want to print it easily from their 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>man<replaceable>n</replaceable></filename> directories, + corresponding to the sections that have been translated.</seg> + </seglistitem> + </segmentedlist> + + <para>Not every + <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> directory will contain all of these directories. It depends + on much translation has been accomplished by that translation + team.</para> + </sect1> + + <sect1> + <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 organised as a DocBook <sgmltag>book</sgmltag>. + It is then divided into <sgmltag>part</sgmltag>s, each of which may + contain several <sgmltag>chapter</sgmltag>s. + <sgmltag>chapter</sgmltag>s are further subdivided into sections + (<sgmltag>sect1</sgmltag>) and subsections (<sgmltag>sect2</sgmltag>, + <sgmltag>sect3</sgmltag>) and so on.</para> + + <sect3> + <title>Physical organisation</title> + + <para>There are a number of files and directories within the + <filename>handbook</filename> directory.</para> + + <note> + <para>The Handbook's organisation may change over time, and this + document may lag in detailing the organisational changes. If you + have any questions about how the Handbook is organised, please + contact the FreeBSD Documentation Project, + <email>freebsd-doc@FreeBSD.org</email>.</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.sgml</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.sgml</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><replaceable>directory</replaceable>/chapter.sgml</filename></title> + + <para>Each chapter in the Handbook is stored in a file called + <filename>chapter.sgml</filename> in a separate directory from the + other chapters. Each directory is named after the value of the + <literal>id</literal> attribute on the <sgmltag>chapter</sgmltag> + 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.sgml</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.sgml</filename>, and named + after the value of the <literal>id</literal> attribute on the + file's <sgmltag>chapter</sgmltag> element. Moving them in to + 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 and 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.sgml</filename> files, including + <filename>basics/chapter.sgml</filename>, + <filename>introduction/chapter.sgml</filename>, and + <filename>printing/chapter.sgml</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 reorganised; + this sort of reorganistion 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.sgml</filename> file will not be a + complete SGML document. In particular, they will not have their + own DOCTYPE line at the start of the file.</para> + + <para>This is unfortunate for two reasons;</para> + + <itemizedlist> + <listitem> + <para>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 as had on just + one chapter.</para> + </listitem> + + <listitem> + <para>Emacs' <literal>sgml-mode</literal> can not use it to + determine the DTD to use, losing useful benefits of + <literal>sgml-mode</literal> (element completion, automatic + validation, and so on).</para> + </listitem> + </itemizedlist> + </sect4> + </sect3> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + |