aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml
diff options
context:
space:
mode:
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.sgml299
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:
+-->
+