aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/structure
diff options
context:
space:
mode:
authorWarren Block <wblock@FreeBSD.org>2012-05-21 14:21:16 +0000
committerWarren Block <wblock@FreeBSD.org>2012-05-21 14:21:16 +0000
commit3e5623c655d903c2d84c0f173f46af8399fb580e (patch)
treeb7ddcf397123eafb955201af8fd8bf9021b97896 /en_US.ISO8859-1/books/fdp-primer/structure
parent02702f555d86e3d5f49a0734d12e0cd9452be945 (diff)
downloaddoc-3e5623c655d903c2d84c0f173f46af8399fb580e.tar.gz
doc-3e5623c655d903c2d84c0f173f46af8399fb580e.zip
Whitespace-only fixes, wrap long lines and correct indentation.
Translators, please ignore.
Notes
Notes: svn path=/head/; revision=38868
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/structure')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml280
1 files changed, 149 insertions, 131 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
index 8acf6ce73f..0b7089b06f 100644
--- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml
@@ -33,14 +33,15 @@
<chapter 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>
+ <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>
+ <para>Make it easy to automate converting the document to other
+ formats.</para>
</listitem>
<listitem>
@@ -50,21 +51,23 @@
</listitem>
<listitem>
- <para>Make it easy to decide where in the tree new documentation should
- be placed.</para>
+ <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>
+ <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 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>
+ <para>There are two types of directory under
+ <filename>doc/</filename>, each with very specific directory
+ names and meanings.</para>
<segmentedlist>
<segtitle>Directory</segtitle>
@@ -73,39 +76,41 @@
<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
+
+ <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/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
+
+ <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.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>
+ <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 id="structure-locale">
<title>The
- <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> Directories</title>
+ <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>
+ documentation is split into up to three more categories at
+ this level, indicated by the different directory names.</para>
<segmentedlist>
<segtitle>Directory</segtitle>
@@ -114,43 +119,47 @@
<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>
+
+ <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 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>
+
+ <seg>Documentation marked up as a DocBook
+ <sgmltag>book</sgmltag> (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>man<replaceable>n</replaceable></filename> directories,
- corresponding to the sections that have been translated.</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
+ <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 id="structure-document">
<title>Document Specific Information</title>
- <para>This section contains specific notes about particular documents
- managed by the FDP.</para>
+ <para>This section contains specific notes about particular
+ documents managed by the FDP.</para>
<sect2>
<title>The Handbook</title>
@@ -159,52 +168,55 @@
<para>The Handbook is written to comply with the FreeBSD DocBook
extended DTD.</para>
-
- <para>The Handbook is organized 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>,
+
+ <para>The Handbook is organized 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 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>
+ <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>
+
+ <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
+
+ <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>
+ 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
+ <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>
@@ -212,69 +224,75 @@
<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>
+ <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>
-
+ <para>For example, if one of the chapter files
+ contains:</para>
+
<programlisting><![ CDATA [
<chapter id="kernelconfig">
...
</chapter>]]></programlisting>
- <para>Then it will be called <filename>chapter.sgml</filename> in
- the <filename>kernelconfig</filename> directory. In
- general, the entire contents of the chapter will be held in this
+ <para>Then it will be called
+ <filename>chapter.sgml</filename> in the
+ <filename>kernelconfig</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>kernelconfig.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.
- Now, it is possible to include images in each
- chapter. Images for each Handbook chapter are stored within
- <filename class="directory">share/images/books/handbook</filename>.
- Note that localized version of these images should be placed in the same
- directory as the SGML sources for each chapter.
- 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>,
+
+ <para>When the HTML version of the Handbook is produced,
+ this will yield <filename>kernelconfig.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. Now, it is possible
+ to include images in each chapter. Images for each
+ Handbook chapter are stored within <filename
+ class="directory">share/images/books/handbook</filename>.
+ Note that localized version of these images should be
+ placed in the same directory as the SGML sources for each
+ chapter. 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 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>
+ <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.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>
+
+ <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>