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.sgml295
1 files changed, 0 insertions, 295 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
deleted file mode 100644
index 2de30fe013..0000000000
--- a/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml
+++ /dev/null
@@ -1,295 +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.4 2000/07/07 18:38:38 dannyboy 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>make it 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>
- <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 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 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 <sgmltag>article</sgmltag>
- (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 <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 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>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 how 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 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>
-
-<!--
- 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:
--->
-