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:21:37 +0000
committerWarren Block <wblock@FreeBSD.org>2013-07-18 00:21:37 +0000
commit9d0324df5070b46830af3b84dfd3698103fc6acc (patch)
tree83406109e3319914e097c455508504f8181ddc90 /en_US.ISO8859-1/books/fdp-primer/structure
parentffc975fb9266f74e485098459487a0935f3196dc (diff)
downloaddoc-9d0324df5070b46830af3b84dfd3698103fc6acc.tar.gz
doc-9d0324df5070b46830af3b84dfd3698103fc6acc.zip
Edit, update, and simplify the structure chapter.
Reviewed by: bps and Allan Jude on IRC
Notes
Notes: svn path=/head/; revision=42309
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/structure')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml187
1 files changed, 95 insertions, 92 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 7a688264b4..c4ebeb7d60 100644
--- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
@@ -32,12 +32,10 @@
-->
<chapter id="structure">
- <title>Structuring Documents Under <filename>doc/</filename></title>
+ <title>Documentation Directory Structure</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>Files and directories in the <filename class="directory">doc/</filename> tree follow a structure
+ meant to:</para>
<orderedlist>
<listitem>
@@ -58,50 +56,57 @@
</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
+ 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>doc/</filename></title>
+ <title>The Top Level, <filename class="directory">doc/</filename></title>
<para>There are two types of directory under
- <filename>doc/</filename>, each with very specific directory
+ <filename class="directory">doc/</filename>, each with very specific directory
names and meanings.</para>
- <segmentedlist>
- <segtitle>Directory</segtitle>
+ <informaltable pgwide="1" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Directory</entry>
+ <entry>Usage</entry>
+ </row>
+ </thead>
- <segtitle>Meaning</segtitle>
+ <tbody>
+ <row>
+ <entry valign="top"><filename class="directory">share</filename></entry>
- <seglistitem>
- <seg><filename>share/</filename></seg>
-
- <seg>Contains files that are not specific to the various
+ <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>share/mk</filename>, while
- the additional XML support files (such as the FreeBSD
- extended DocBook DTD) are in
- <filename>share/xml</filename>.</seg>
- </seglistitem>
+ 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>
- <seglistitem>
- <seg><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename></seg>
+ <row>
+ <entry valign="top"><filename class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>
- <seg>One directory exists for each available translation and
+ <entry>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
+ <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 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>
+ 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>
+ </informaltable>
</sect1>
<sect1 id="structure-locale">
@@ -113,51 +118,58 @@
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>
+ <informaltable pgwide="1" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Directory</entry>
+ <entry>Usage</entry>
+ </row>
+ </thead>
- <seglistitem>
- <seg><filename>articles</filename></seg>
+ <tbody>
+ <row>
+ <entry valign="top"><filename class="directory">articles</filename></entry>
- <seg>Documentation marked up as a DocBook
+ <entry>Documentation marked up as a DocBook
<sgmltag>article</sgmltag> (or equivalent). Reasonably
short, and broken up into sections. Normally only available
- as one XHTML file.</seg>
- </seglistitem>
+ as one <acronym>XHTML</acronym> file.</entry>
+ </row>
- <seglistitem>
- <seg><filename>books</filename></seg>
+ <row>
+ <entry valign="top"><filename>books</filename></entry>
- <seg>Documentation marked up as a DocBook
+ <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 XHTML file (for people with fast connections, or who
+ 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.</seg>
- </seglistitem>
+ of linked, smaller files.</entry>
+ </row>
- <seglistitem>
- <seg><filename>man</filename></seg>
+ <row>
+ <entry valign="top"><filename class="directory">man</filename></entry>
- <seg>For translations of the system manual pages. This
+ <entry>For translations of the system manual pages. This
directory will contain one or more
- <filename>man<replaceable>n</replaceable></filename>
+ <filename class="directory">man<replaceable>n</replaceable></filename>
directories, corresponding to the sections that have been
- translated.</seg>
- </seglistitem>
- </segmentedlist>
+ translated.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
<para>Not every
- <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
- directory will contain all of these directories. It depends on
+ <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">
- <title>Document Specific Information</title>
+ <title>Document-Specific Information</title>
<para>This section contains specific notes about particular
documents managed by the FDP.</para>
@@ -167,12 +179,12 @@
<subtitle><filename>books/handbook/</filename></subtitle>
- <para>The Handbook is written to comply with the FreeBSD DocBook
+ <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>. It is then divided into
- <sgmltag>part</sgmltag>s, each of which may contain several
+ <sgmltag>book</sgmltag>. The book is divided into
+ <sgmltag>part</sgmltag>s, each of which contains several
<sgmltag>chapter</sgmltag>s. <sgmltag>chapter</sgmltag>s are
further subdivided into sections (<sgmltag>sect1</sgmltag>)
and subsections (<sgmltag>sect2</sgmltag>,
@@ -187,18 +199,18 @@
<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>
+ 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 XML source is converted to
+ 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> file, to bring in the
+ <filename>doc.project.mk</filename>, to bring in the
rest of the code that handles converting documents from
one format to another.</para>
</sect4>
@@ -223,7 +235,7 @@
</sect4>
<sect4>
- <title><filename><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
@@ -235,10 +247,9 @@
<para>For example, if one of the chapter files
contains:</para>
- <programlisting><![CDATA[
-<chapter id="kernelconfig">
+ <programlisting><sgmltag class="starttag">chapter id="kernelconfig"</sgmltag>
...
-</chapter>]]></programlisting>
+<sgmltag class="endtag">chapter</sgmltag></programlisting>
<para>Then it will be called
<filename>chapter.xml</filename> in the
@@ -246,12 +257,12 @@
the entire contents of the chapter will be held in this
file.</para>
- <para>When the XHTML version of the Handbook is produced,
+ <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
+ <para>In earlier versions of the Handbook, the files were
stored in the same directory as
<filename>book.xml</filename>, and named after the value
of the <literal>id</literal> attribute on the file's
@@ -259,8 +270,8 @@
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 XML sources for each
+ 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
@@ -273,27 +284,19 @@
<filename>printing/chapter.xml</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>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
+ renaming files, unless entire chapters are being
+ promoted or demoted within the hierarchy.</para>
</important>
- <para>Each <filename>chapter.xml</filename> file will not
- be a complete XML 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 XML 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>The <filename>chapter.xml</filename> files are not
+ complete <acronym>XML</acronym> documents. They cannot be
+ individually rendered to output formats, but must be built
+ as part of the Handbook.</para>
</sect4>
</sect3>
</sect2>