aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/structure
diff options
context:
space:
mode:
authorGabor Kovesdan <gabor@FreeBSD.org>2013-11-07 15:39:28 +0000
committerGabor Kovesdan <gabor@FreeBSD.org>2013-11-07 15:39:28 +0000
commit24d129e8d1984a0b46a543bc523b63d216813bb0 (patch)
tree7dd0501c857c6f2139f4a71191c93bf19136412a /en_US.ISO8859-1/books/fdp-primer/structure
parent35f1d6c78be90eb13320d655cd68f94333a0ab26 (diff)
downloaddoc-24d129e8d1984a0b46a543bc523b63d216813bb0.tar.gz
doc-24d129e8d1984a0b46a543bc523b63d216813bb0.zip
- Definitively upgrade to DocBook 5.0
Notes
Notes: svn path=/projects/db5/; revision=43125
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/structure')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml80
1 files changed, 35 insertions, 45 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 ad0cd93676..1c4d177084 100644
--- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
@@ -30,12 +30,11 @@
$FreeBSD$
-->
-
-<chapter id="structure">
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="structure">
<title>Documentation Directory Structure</title>
<para>Files and directories in the
- <filename class="directory">doc/</filename> tree follow a
+ <filename>doc/</filename> tree follow a
structure meant to:</para>
<orderedlist>
@@ -61,12 +60,12 @@
important that the documentation tree structure does not enforce
any particular defaults or cultural preferences.</para>
- <sect1 id="structure-top">
+ <sect1 xml:id="structure-top">
<title>The Top Level,
- <filename class="directory">doc/</filename></title>
+ <filename>doc/</filename></title>
<para>There are two types of directory under
- <filename class="directory">doc/</filename>, each with very
+ <filename>doc/</filename>, each with very
specific directory names and meanings.</para>
<informaltable pgwide="1" frame="none">
@@ -81,28 +80,26 @@
<tbody>
<row>
<entry valign="top">
- <filename class="directory">share</filename></entry>
+ <filename>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
+ <filename>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>
+ <acronym>DTD</acronym>) are in <filename>share/xml</filename>.</entry>
</row>
<row>
- <entry valign="top"><filename
- class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>
+ <entry valign="top"><filename>lang.encoding</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>.
+ <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 when a
translation team wants to provide documentation in the
@@ -115,9 +112,9 @@
</informaltable>
</sect1>
- <sect1 id="structure-locale">
+ <sect1 xml:id="structure-locale">
<title>The
- <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename>
+ <filename>lang.encoding/</filename>
Directories</title>
<para>These directories contain the documents themselves. The
@@ -136,10 +133,10 @@
<tbody>
<row>
<entry valign="top">
- <filename class="directory">articles</filename></entry>
+ <filename>articles</filename></entry>
<entry>Documentation marked up as a DocBook
- <sgmltag>article</sgmltag> (or equivalent). Reasonably
+ <tag>article</tag> (or equivalent). Reasonably
short, and broken up into sections. Normally only
available as one <acronym>XHTML</acronym> file.</entry>
</row>
@@ -148,7 +145,7 @@
<entry valign="top"><filename>books</filename></entry>
<entry>Documentation marked up as a DocBook
- <sgmltag>book</sgmltag> (or equivalent). Book length,
+ <tag>book</tag> (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
@@ -158,11 +155,10 @@
<row>
<entry valign="top">
- <filename class="directory">man</filename></entry>
+ <filename>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>
+ directory will contain one or more <filename>mann</filename>
directories, corresponding to the sections that have
been translated.</entry>
</row>
@@ -170,14 +166,13 @@
</tgroup>
</informaltable>
- <para>Not every <filename
- class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
+ <para>Not every <filename>lang.encoding</filename>
directory will have all of these subdirectories. It depends
on how much translation has been accomplished by that
translation team.</para>
</sect1>
- <sect1 id="structure-document">
+ <sect1 xml:id="structure-document">
<title>Document-Specific Information</title>
<para>This section contains specific notes about particular
@@ -192,12 +187,12 @@
using the &os; DocBook extended <acronym>DTD</acronym>.</para>
<para>The Handbook is organized as a DocBook
- <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>,
- <sgmltag>sect3</sgmltag>) and so on.</para>
+ <tag>book</tag>. The book is divided into
+ <tag>part</tag>s, each of which contains several
+ <tag>chapter</tag>s. <tag>chapter</tag>s are
+ further subdivided into sections (<tag>sect1</tag>)
+ and subsections (<tag>sect2</tag>,
+ <tag>sect3</tag>) and so on.</para>
<sect3>
<title>Physical Organization</title>
@@ -228,38 +223,34 @@
<title><filename>book.xml</filename></title>
<para>This is the top level document in the Handbook. It
- contains the Handbook's <link
- linkend="xml-primer-doctype-declaration">DOCTYPE
+ contains the Handbook's <link linkend="xml-primer-doctype-declaration">DOCTYPE
declaration</link>, as well as the elements that
describe the Handbook's structure.</para>
- <para><filename>book.xml</filename> uses <link
- linkend="xml-primer-parameter-entities">parameter
+ <para><filename>book.xml</filename> uses <link linkend="xml-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="xml-primer-general-entities">general
+ (described later) then define <link linkend="xml-primer-general-entities">general
entities</link> that are used throughout the rest of the
Handbook.</para>
</sect4>
<sect4>
- <title><filename
- class="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title>
+ <title><filename>directory/chapter.xml</filename></title>
<para>Each chapter in the Handbook is stored in a file
called <filename>chapter.xml</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>
+ attribute on the <tag>chapter</tag>
element.</para>
<para>For example, if one of the chapter files
contains:</para>
- <programlisting><sgmltag class="starttag">chapter id="kernelconfig"</sgmltag>
+ <programlisting><tag class="starttag">chapter id="kernelconfig"</tag>
...
-<sgmltag class="endtag">chapter</sgmltag></programlisting>
+<tag class="endtag">chapter</tag></programlisting>
<para>Then it will be called
<filename>chapter.xml</filename> in the
@@ -277,10 +268,9 @@
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
- <sgmltag>chapter</sgmltag> element. Now, it is possible
+ <tag>chapter</tag> 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>.
+ Handbook chapter are stored within <filename>share/images/books/handbook</filename>.
The localized version of these images should be
placed in the same directory as the <acronym>XML</acronym>
sources for each chapter. Namespace collisions are