aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/structure
diff options
context:
space:
mode:
authorWarren Block <wblock@FreeBSD.org>2013-07-18 00:31:45 +0000
committerWarren Block <wblock@FreeBSD.org>2013-07-18 00:31:45 +0000
commit27144d9f4343c001084e3e6d2a98f688ee7eb648 (patch)
tree318e7202cf07e5836bfd1f47335c219186c3f3d8 /en_US.ISO8859-1/books/fdp-primer/structure
parent9d0324df5070b46830af3b84dfd3698103fc6acc (diff)
downloaddoc-27144d9f4343c001084e3e6d2a98f688ee7eb648.tar.gz
doc-27144d9f4343c001084e3e6d2a98f688ee7eb648.zip
Whitespace-only fixes. Translators, please ignore.
Notes
Notes: svn path=/head/; revision=42310
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/structure')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml154
1 files changed, 82 insertions, 72 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
index c4ebeb7d60..b4974a9068 100644
--- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
@@ -34,8 +34,9 @@
<chapter id="structure">
<title>Documentation Directory Structure</title>
- <para>Files and directories in the <filename class="directory">doc/</filename> tree follow a structure
- meant to:</para>
+ <para>Files and directories in the
+ <filename class="directory">doc/</filename> tree follow a
+ structure meant to:</para>
<orderedlist>
<listitem>
@@ -56,17 +57,17 @@
</orderedlist>
<para>In addition, the documentation tree has to accommodate
- documents in many different languages and
- encodings. It is important that
- the documentation tree structure does not enforce any particular defaults or
- cultural preferences.</para>
+ documents in many different languages and encodings. It is
+ important that the documentation tree structure does not enforce
+ any particular defaults or cultural preferences.</para>
<sect1 id="structure-top">
- <title>The Top Level, <filename class="directory">doc/</filename></title>
+ <title>The Top Level,
+ <filename class="directory">doc/</filename></title>
<para>There are two types of directory under
- <filename class="directory">doc/</filename>, each with very specific directory
- names and meanings.</para>
+ <filename class="directory">doc/</filename>, each with very
+ specific directory names and meanings.</para>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
@@ -79,30 +80,35 @@
<tbody>
<row>
- <entry valign="top"><filename class="directory">share</filename></entry>
+ <entry valign="top">
+ <filename class="directory">share</filename></entry>
<entry>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 class="directory">share/mk</filename>, while
- the additional <acronym>XML</acronym> support files (such as the &os;
- extended DocBook <acronym>DTD</acronym>) are in
- <filename class="directory">share/xml</filename>.</entry>
+ 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 class="directory">share/mk</filename>, while
+ the additional <acronym>XML</acronym> support files
+ (such as the &os; extended DocBook
+ <acronym>DTD</acronym>) are in <filename
+ class="directory">share/xml</filename>.</entry>
</row>
<row>
- <entry valign="top"><filename class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>
-
- <entry>One directory exists for each available translation and
- encoding of the documentation, for example
- <filename class="directory">en_US.ISO8859-1/</filename> and
- <filename class="directory">zh_TW.Big5/</filename>. The names are long, but
- by fully specifying the language and encoding we prevent any
- future headaches when a translation team wants to provide
- documentation in the same language but in more than one
- encoding. This also avoids
- problems that might be caused by a future switch to Unicode.</entry>
+ <entry valign="top"><filename
+ class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>
+
+ <entry>One directory exists for each available translation
+ and encoding of the documentation, for example
+ <filename class="directory">en_US.ISO8859-1/</filename>
+ and <filename class="directory">zh_TW.Big5/</filename>.
+ The names are long, but by fully specifying the language
+ and encoding we prevent any future headaches when a
+ translation team wants to provide documentation in the
+ same language but in more than one encoding. This also
+ avoids problems that might be caused by a future switch
+ to Unicode.</entry>
</row>
</tbody>
</tgroup>
@@ -129,43 +135,46 @@
<tbody>
<row>
- <entry valign="top"><filename class="directory">articles</filename></entry>
+ <entry valign="top">
+ <filename class="directory">articles</filename></entry>
<entry>Documentation marked up as a DocBook
- <sgmltag>article</sgmltag> (or equivalent). Reasonably
- short, and broken up into sections. Normally only available
- as one <acronym>XHTML</acronym> file.</entry>
+ <sgmltag>article</sgmltag> (or equivalent). Reasonably
+ short, and broken up into sections. Normally only
+ available as one <acronym>XHTML</acronym> file.</entry>
</row>
<row>
<entry valign="top"><filename>books</filename></entry>
<entry>Documentation marked up as a DocBook
- <sgmltag>book</sgmltag> (or equivalent). Book length, and
- broken up into chapters. Normally available as both one
- large <acronym>XHTML</acronym> file (for people with fast connections, or who
- want to print it easily from a browser) and as a collection
- of linked, smaller files.</entry>
+ <sgmltag>book</sgmltag> (or equivalent). Book length,
+ and broken up into chapters. Normally available as both
+ one large <acronym>XHTML</acronym> file (for people with
+ fast connections, or who want to print it easily from a
+ browser) and as a collection of linked, smaller
+ files.</entry>
</row>
<row>
- <entry valign="top"><filename class="directory">man</filename></entry>
+ <entry valign="top">
+ <filename class="directory">man</filename></entry>
<entry>For translations of the system manual pages. This
- directory will contain one or more
- <filename class="directory">man<replaceable>n</replaceable></filename>
- directories, corresponding to the sections that have been
- translated.</entry>
+ directory will contain one or more <filename
+ class="directory">man<replaceable>n</replaceable></filename>
+ directories, corresponding to the sections that have
+ been translated.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
- <para>Not every
- <filename class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
- directory will contain all of these subdirectories. It depends on
- how much translation has been accomplished by that translation
- team.</para>
+ <para>Not every <filename
+ class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
+ directory will contain all of these subdirectories. It depends
+ on how much translation has been accomplished by that
+ translation team.</para>
</sect1>
<sect1 id="structure-document">
@@ -179,8 +188,8 @@
<subtitle><filename>books/handbook/</filename></subtitle>
- <para>The Handbook is written in DocBook <acronym>XML</acronym> using the &os; DocBook
- extended DTD.</para>
+ <para>The Handbook is written in DocBook <acronym>XML</acronym>
+ using the &os; DocBook extended DTD.</para>
<para>The Handbook is organized as a DocBook
<sgmltag>book</sgmltag>. The book is divided into
@@ -199,20 +208,20 @@
<note>
<para>The Handbook's organization may change over time, and
this document may lag in detailing the organizational
- changes. Post questions about Handbook
- organization to &a.doc;.</para>
+ changes. Post questions about Handbook organization to
+ &a.doc;.</para>
</note>
<sect4>
<title><filename>Makefile</filename></title>
<para>The <filename>Makefile</filename> defines some
- variables that affect how the <acronym>XML</acronym> 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>, to bring in the
- rest of the code that handles converting documents from
- one format to another.</para>
+ variables that affect how the <acronym>XML</acronym>
+ 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>,
+ to bring in the rest of the code that handles converting
+ documents from one format to another.</para>
</sect4>
<sect4>
@@ -235,7 +244,8 @@
</sect4>
<sect4>
- <title><filename class="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title>
+ <title><filename
+ class="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title>
<para>Each chapter in the Handbook is stored in a file
called <filename>chapter.xml</filename> in a separate
@@ -257,10 +267,11 @@
the entire contents of the chapter will be held in this
file.</para>
- <para>When the <acronym>XHTML</acronym> 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>When the <acronym>XHTML</acronym> 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
@@ -271,11 +282,11 @@
Handbook chapter are stored within <filename
class="directory">share/images/books/handbook</filename>.
Note that the localized version of these images should be
- placed in the same directory as the <acronym>XML</acronym> 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>
+ placed in the same directory as the <acronym>XML</acronym>
+ 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.xml</filename> files,
@@ -285,16 +296,15 @@
<important>
<para>Do not name chapters or directories after
- their ordering within the
- Handbook. This ordering can change as the content
- within the Handbook is reorganized.
- Reorganization should be possible without
+ their ordering within the Handbook. This ordering can
+ change as the content within the Handbook is
+ reorganized. Reorganization should be possible without
renaming files, unless entire chapters are being
promoted or demoted within the hierarchy.</para>
</important>
<para>The <filename>chapter.xml</filename> files are not
- complete <acronym>XML</acronym> documents. They cannot be
+ complete <acronym>XML</acronym> documents. They cannot be
individually rendered to output formats, but must be built
as part of the Handbook.</para>
</sect4>