diff options
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml')
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml | 287 |
1 files changed, 0 insertions, 287 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml deleted file mode 100644 index 6b42003e89..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml +++ /dev/null @@ -1,287 +0,0 @@ -<!-- 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: doc/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml,v 1.2 1999/09/06 06:52:42 peter 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 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 as had on just - one chapter.</para> - </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: ---> - |