os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Whitespace-only fixes. Translators, please ignore.

Browse source
This commit is contained in:
Warren Block 2013-07-18 00:31:45 +00:00
parent 9d0324df50
commit 27144d9f43
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=42310
1 changed files with 81 additions and 71 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

152
en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
View file

@ -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 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>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>