Whitespace-only fixes, wrap long lines and correct indentation.
Translators, please ignore.
This commit is contained in:
Warren Block
parent
02702f555d
commit
3e5623c655
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=38868
1 changed files with 147 additions and 129 deletions
|
|
@ -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>
|
||||
|
|
@ -74,38 +77,40 @@
|
|||
<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>
|
||||
|
|
@ -115,42 +120,46 @@
|
|||
<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>
|
||||
|
|
@ -160,11 +169,12 @@
|
|||
<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>
|
||||
|
|
@ -174,37 +184,39 @@
|
|||
<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>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>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>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>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>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>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue