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">
|
<chapter id="structure">
|
||||||
<title>Structuring Documents Under <filename>doc/</filename></title>
|
<title>Structuring Documents Under <filename>doc/</filename></title>
|
||||||
|
|
||||||
<para>The <filename>doc/</filename> tree is organized in a particular
|
<para>The <filename>doc/</filename> tree is organized in a
|
||||||
fashion, and the documents that are part of the FDP are in turn organized
|
particular fashion, and the documents that are part of the FDP are
|
||||||
in a particular fashion. The aim is to make it simple to add new
|
in turn organized in a particular fashion. The aim is to make it
|
||||||
documentation into the tree and:</para>
|
simple to add new documentation into the tree and:</para>
|
||||||
|
|
||||||
<orderedlist>
|
<orderedlist>
|
||||||
<listitem>
|
<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>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
|
|
@ -50,21 +51,23 @@
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Make it easy to decide where in the tree new documentation should
|
<para>Make it easy to decide where in the tree new documentation
|
||||||
be placed.</para>
|
should be placed.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</orderedlist>
|
</orderedlist>
|
||||||
|
|
||||||
<para>In addition, the documentation tree has to accommodate documentation
|
<para>In addition, the documentation tree has to accommodate
|
||||||
that could be in many different languages and in many different
|
documentation that could be in many different languages and in
|
||||||
encodings. It is important that the structure of the documentation tree
|
many different encodings. It is important that the structure of
|
||||||
does not enforce any particular defaults or cultural preferences.</para>
|
the documentation tree does not enforce any particular defaults or
|
||||||
|
cultural preferences.</para>
|
||||||
|
|
||||||
<sect1 id="structure-top">
|
<sect1 id="structure-top">
|
||||||
<title>The Top Level, <filename>doc/</filename></title>
|
<title>The Top Level, <filename>doc/</filename></title>
|
||||||
|
|
||||||
<para>There are two types of directory under <filename>doc/</filename>,
|
<para>There are two types of directory under
|
||||||
each with very specific directory names and meanings.</para>
|
<filename>doc/</filename>, each with very specific directory
|
||||||
|
names and meanings.</para>
|
||||||
|
|
||||||
<segmentedlist>
|
<segmentedlist>
|
||||||
<segtitle>Directory</segtitle>
|
<segtitle>Directory</segtitle>
|
||||||
|
|
@ -74,38 +77,40 @@
|
||||||
<seglistitem>
|
<seglistitem>
|
||||||
<seg><filename>share/</filename></seg>
|
<seg><filename>share/</filename></seg>
|
||||||
|
|
||||||
<seg>Contains files that are not specific to the various translations
|
<seg>Contains files that are not specific to the various
|
||||||
and encodings of the documentation. Contains subdirectories to
|
translations and encodings of the documentation. Contains
|
||||||
further categorize the information. For example, the files that
|
subdirectories to further categorize the information. For
|
||||||
comprise the &man.make.1; infrastructure are in
|
example, the files that comprise the &man.make.1;
|
||||||
<filename>share/mk</filename>, while the additional SGML support
|
infrastructure are in <filename>share/mk</filename>, while
|
||||||
files (such as the FreeBSD extended DocBook DTD) are in
|
the additional SGML support files (such as the FreeBSD
|
||||||
|
extended DocBook DTD) are in
|
||||||
<filename>share/sgml</filename>.</seg>
|
<filename>share/sgml</filename>.</seg>
|
||||||
</seglistitem>
|
</seglistitem>
|
||||||
|
|
||||||
<seglistitem>
|
<seglistitem>
|
||||||
<seg><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename></seg>
|
<seg><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename></seg>
|
||||||
|
|
||||||
<seg>One directory exists for each available translation and encoding
|
<seg>One directory exists for each available translation and
|
||||||
of the documentation, for example
|
encoding of the documentation, for example
|
||||||
<filename>en_US.ISO8859-1/</filename> and
|
<filename>en_US.ISO8859-1/</filename> and
|
||||||
<filename>zh_TW.Big5/</filename>. The names are long, but by fully
|
<filename>zh_TW.Big5/</filename>. The names are long, but
|
||||||
specifying the language and encoding we prevent any future headaches
|
by fully specifying the language and encoding we prevent any
|
||||||
should a translation team want to provide the documentation in the
|
future headaches should a translation team want to provide
|
||||||
same language but in more than one encoding. This also completely
|
the documentation in the same language but in more than one
|
||||||
isolates us from any problems that might be caused by a switch to
|
encoding. This also completely isolates us from any
|
||||||
Unicode.</seg>
|
problems that might be caused by a switch to Unicode.</seg>
|
||||||
</seglistitem>
|
</seglistitem>
|
||||||
</segmentedlist>
|
</segmentedlist>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1 id="structure-locale">
|
<sect1 id="structure-locale">
|
||||||
<title>The
|
<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
|
<para>These directories contain the documents themselves. The
|
||||||
documentation is split into up to three more categories at this
|
documentation is split into up to three more categories at
|
||||||
level, indicated by the different directory names.</para>
|
this level, indicated by the different directory names.</para>
|
||||||
|
|
||||||
<segmentedlist>
|
<segmentedlist>
|
||||||
<segtitle>Directory</segtitle>
|
<segtitle>Directory</segtitle>
|
||||||
|
|
@ -115,42 +120,46 @@
|
||||||
<seglistitem>
|
<seglistitem>
|
||||||
<seg><filename>articles</filename></seg>
|
<seg><filename>articles</filename></seg>
|
||||||
|
|
||||||
<seg>Documentation marked up as a DocBook <sgmltag>article</sgmltag>
|
<seg>Documentation marked up as a DocBook
|
||||||
(or equivalent). Reasonably short, and broken up into sections.
|
<sgmltag>article</sgmltag> (or equivalent). Reasonably
|
||||||
Normally only available as one HTML file.</seg>
|
short, and broken up into sections. Normally only available
|
||||||
|
as one HTML file.</seg>
|
||||||
</seglistitem>
|
</seglistitem>
|
||||||
|
|
||||||
<seglistitem>
|
<seglistitem>
|
||||||
<seg><filename>books</filename></seg>
|
<seg><filename>books</filename></seg>
|
||||||
|
|
||||||
<seg>Documentation marked up as a DocBook <sgmltag>book</sgmltag> (or
|
<seg>Documentation marked up as a DocBook
|
||||||
equivalent). Book length, and broken up into chapters. Normally
|
<sgmltag>book</sgmltag> (or equivalent). Book length, and
|
||||||
available as both one large HTML file (for people with fast
|
broken up into chapters. Normally available as both one
|
||||||
connections, or who want to print it easily from a browser) and
|
large HTML file (for people with fast connections, or who
|
||||||
as a collection of linked, smaller files.</seg>
|
want to print it easily from a browser) and as a collection
|
||||||
|
of linked, smaller files.</seg>
|
||||||
</seglistitem>
|
</seglistitem>
|
||||||
|
|
||||||
<seglistitem>
|
<seglistitem>
|
||||||
<seg><filename>man</filename></seg>
|
<seg><filename>man</filename></seg>
|
||||||
|
|
||||||
<seg>For translations of the system manual pages. This directory will
|
<seg>For translations of the system manual pages. This
|
||||||
contain one or more
|
directory will contain one or more
|
||||||
<filename>man<replaceable>n</replaceable></filename> directories,
|
<filename>man<replaceable>n</replaceable></filename>
|
||||||
corresponding to the sections that have been translated.</seg>
|
directories, corresponding to the sections that have been
|
||||||
|
translated.</seg>
|
||||||
</seglistitem>
|
</seglistitem>
|
||||||
</segmentedlist>
|
</segmentedlist>
|
||||||
|
|
||||||
<para>Not every
|
<para>Not every
|
||||||
<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> directory will contain all of these directories. It depends
|
<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
|
||||||
on how much translation has been accomplished by that translation
|
directory will contain all of these directories. It depends on
|
||||||
|
how much translation has been accomplished by that translation
|
||||||
team.</para>
|
team.</para>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1 id="structure-document">
|
<sect1 id="structure-document">
|
||||||
<title>Document Specific Information</title>
|
<title>Document Specific Information</title>
|
||||||
|
|
||||||
<para>This section contains specific notes about particular documents
|
<para>This section contains specific notes about particular
|
||||||
managed by the FDP.</para>
|
documents managed by the FDP.</para>
|
||||||
|
|
||||||
<sect2>
|
<sect2>
|
||||||
<title>The Handbook</title>
|
<title>The Handbook</title>
|
||||||
|
|
@ -160,11 +169,12 @@
|
||||||
<para>The Handbook is written to comply with the FreeBSD DocBook
|
<para>The Handbook is written to comply with the FreeBSD DocBook
|
||||||
extended DTD.</para>
|
extended DTD.</para>
|
||||||
|
|
||||||
<para>The Handbook is organized as a DocBook <sgmltag>book</sgmltag>.
|
<para>The Handbook is organized as a DocBook
|
||||||
It is then divided into <sgmltag>part</sgmltag>s, each of which may
|
<sgmltag>book</sgmltag>. It is then divided into
|
||||||
contain several <sgmltag>chapter</sgmltag>s.
|
<sgmltag>part</sgmltag>s, each of which may contain several
|
||||||
<sgmltag>chapter</sgmltag>s are further subdivided into sections
|
<sgmltag>chapter</sgmltag>s. <sgmltag>chapter</sgmltag>s are
|
||||||
(<sgmltag>sect1</sgmltag>) and subsections (<sgmltag>sect2</sgmltag>,
|
further subdivided into sections (<sgmltag>sect1</sgmltag>)
|
||||||
|
and subsections (<sgmltag>sect2</sgmltag>,
|
||||||
<sgmltag>sect3</sgmltag>) and so on.</para>
|
<sgmltag>sect3</sgmltag>) and so on.</para>
|
||||||
|
|
||||||
<sect3>
|
<sect3>
|
||||||
|
|
@ -174,37 +184,39 @@
|
||||||
<filename>handbook</filename> directory.</para>
|
<filename>handbook</filename> directory.</para>
|
||||||
|
|
||||||
<note>
|
<note>
|
||||||
<para>The Handbook's organization may change over time, and this
|
<para>The Handbook's organization may change over time, and
|
||||||
document may lag in detailing the organizational changes. If you
|
this document may lag in detailing the organizational
|
||||||
have any questions about how the Handbook is organized, please
|
changes. If you have any questions about how the Handbook
|
||||||
contact the &a.doc;.</para>
|
is organized, please contact the &a.doc;.</para>
|
||||||
</note>
|
</note>
|
||||||
|
|
||||||
<sect4>
|
<sect4>
|
||||||
<title><filename>Makefile</filename></title>
|
<title><filename>Makefile</filename></title>
|
||||||
|
|
||||||
<para>The <filename>Makefile</filename> defines some variables that
|
<para>The <filename>Makefile</filename> defines some
|
||||||
affect how the SGML source is converted to other formats, and
|
variables that affect how the SGML source is converted to
|
||||||
lists the various source files that make up the Handbook. It then
|
other formats, and lists the various source files that
|
||||||
includes the standard <filename>doc.project.mk</filename> file, to
|
make up the Handbook. It then includes the standard
|
||||||
bring in the rest of the code that handles converting documents
|
<filename>doc.project.mk</filename> file, to bring in the
|
||||||
from one format to another.</para>
|
rest of the code that handles converting documents from
|
||||||
|
one format to another.</para>
|
||||||
</sect4>
|
</sect4>
|
||||||
|
|
||||||
<sect4>
|
<sect4>
|
||||||
<title><filename>book.sgml</filename></title>
|
<title><filename>book.sgml</filename></title>
|
||||||
|
|
||||||
<para>This is the top level document in the Handbook. It contains
|
<para>This is the top level document in the Handbook. It
|
||||||
the Handbook's <link
|
contains the Handbook's <link
|
||||||
linkend="sgml-primer-doctype-declaration">DOCTYPE
|
linkend="sgml-primer-doctype-declaration">DOCTYPE
|
||||||
declaration</link>, as well as the elements that describe the
|
declaration</link>, as well as the elements that
|
||||||
Handbook's structure.</para>
|
describe the Handbook's structure.</para>
|
||||||
|
|
||||||
<para><filename>book.sgml</filename> uses <link
|
<para><filename>book.sgml</filename> uses <link
|
||||||
linkend="sgml-primer-parameter-entities">parameter
|
linkend="sgml-primer-parameter-entities">parameter
|
||||||
entities</link> to load in the files with the
|
entities</link> to load in the files with the
|
||||||
<filename>.ent</filename> extension. These files (described later)
|
<filename>.ent</filename> extension. These files
|
||||||
then define <link linkend="sgml-primer-general-entities">general
|
(described later) then define <link
|
||||||
|
linkend="sgml-primer-general-entities">general
|
||||||
entities</link> that are used throughout the rest of the
|
entities</link> that are used throughout the rest of the
|
||||||
Handbook.</para>
|
Handbook.</para>
|
||||||
</sect4>
|
</sect4>
|
||||||
|
|
@ -212,69 +224,75 @@
|
||||||
<sect4>
|
<sect4>
|
||||||
<title><filename><replaceable>directory</replaceable>/chapter.sgml</filename></title>
|
<title><filename><replaceable>directory</replaceable>/chapter.sgml</filename></title>
|
||||||
|
|
||||||
<para>Each chapter in the Handbook is stored in a file called
|
<para>Each chapter in the Handbook is stored in a file
|
||||||
<filename>chapter.sgml</filename> in a separate directory from the
|
called <filename>chapter.sgml</filename> in a separate
|
||||||
other chapters. Each directory is named after the value of the
|
directory from the other chapters. Each directory is
|
||||||
<literal>id</literal> attribute on the <sgmltag>chapter</sgmltag>
|
named after the value of the <literal>id</literal>
|
||||||
|
attribute on the <sgmltag>chapter</sgmltag>
|
||||||
element.</para>
|
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 [
|
<programlisting><![ CDATA [
|
||||||
<chapter id="kernelconfig">
|
<chapter id="kernelconfig">
|
||||||
...
|
...
|
||||||
</chapter>]]></programlisting>
|
</chapter>]]></programlisting>
|
||||||
|
|
||||||
<para>Then it will be called <filename>chapter.sgml</filename> in
|
<para>Then it will be called
|
||||||
the <filename>kernelconfig</filename> directory. In
|
<filename>chapter.sgml</filename> in the
|
||||||
general, the entire contents of the chapter will be held in this
|
<filename>kernelconfig</filename> directory. In general,
|
||||||
|
the entire contents of the chapter will be held in this
|
||||||
file.</para>
|
file.</para>
|
||||||
|
|
||||||
<para>When the HTML version of the Handbook is produced, this will
|
<para>When the HTML version of the Handbook is produced,
|
||||||
yield <filename>kernelconfig.html</filename>. This is
|
this will yield <filename>kernelconfig.html</filename>.
|
||||||
because of the <literal>id</literal> value, and is not related to
|
This is because of the <literal>id</literal> value, and is
|
||||||
the name of the directory.</para>
|
not related to the name of the directory.</para>
|
||||||
|
|
||||||
<para>In earlier versions of the Handbook the files were stored in
|
<para>In earlier versions of the Handbook the files were
|
||||||
the same directory as <filename>book.sgml</filename>, and named
|
stored in the same directory as
|
||||||
after the value of the <literal>id</literal> attribute on the
|
<filename>book.sgml</filename>, and named after the value
|
||||||
file's <sgmltag>chapter</sgmltag> element.
|
of the <literal>id</literal> attribute on the file's
|
||||||
Now, it is possible to include images in each
|
<sgmltag>chapter</sgmltag> element. Now, it is possible
|
||||||
chapter. Images for each Handbook chapter are stored within
|
to include images in each chapter. Images for each
|
||||||
<filename class="directory">share/images/books/handbook</filename>.
|
Handbook chapter are stored within <filename
|
||||||
Note that localized version of these images should be placed in the same
|
class="directory">share/images/books/handbook</filename>.
|
||||||
directory as the SGML sources for each chapter.
|
Note that localized version of these images should be
|
||||||
Namespace collisions would be inevitable, and it is
|
placed in the same directory as the SGML sources for each
|
||||||
easier to work with several directories with a few files in them
|
chapter. Namespace collisions would be inevitable, and it
|
||||||
than it is to work with one directory that has many files in
|
is easier to work with several directories with a few
|
||||||
it.</para>
|
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
|
<para>A brief look will show that there are many directories
|
||||||
individual <filename>chapter.sgml</filename> files, including
|
with individual <filename>chapter.sgml</filename> files,
|
||||||
<filename>basics/chapter.sgml</filename>,
|
including <filename>basics/chapter.sgml</filename>,
|
||||||
<filename>introduction/chapter.sgml</filename>, and
|
<filename>introduction/chapter.sgml</filename>, and
|
||||||
<filename>printing/chapter.sgml</filename>.</para>
|
<filename>printing/chapter.sgml</filename>.</para>
|
||||||
|
|
||||||
<important>
|
<important>
|
||||||
<para>Chapters and/or directories should not be named in a fashion
|
<para>Chapters and/or directories should not be named in a
|
||||||
that reflects their ordering within the Handbook. This ordering
|
fashion that reflects their ordering within the
|
||||||
might change as the content within the Handbook is reorganized;
|
Handbook. This ordering might change as the content
|
||||||
this sort of reorganization should not (generally) include the
|
within the Handbook is reorganized; this sort of
|
||||||
need to rename files (unless entire chapters are being promoted
|
reorganization should not (generally) include the need
|
||||||
or demoted within the hierarchy).</para>
|
to rename files (unless entire chapters are being
|
||||||
|
promoted or demoted within the hierarchy).</para>
|
||||||
</important>
|
</important>
|
||||||
|
|
||||||
<para>Each <filename>chapter.sgml</filename> file will not be a
|
<para>Each <filename>chapter.sgml</filename> file will not
|
||||||
complete SGML document. In particular, they will not have their
|
be a complete SGML document. In particular, they will not
|
||||||
own DOCTYPE lines at the start of the files.</para>
|
have their own DOCTYPE lines at the start of the
|
||||||
|
files.</para>
|
||||||
|
|
||||||
<para>This is unfortunate as
|
<para>This is unfortunate as it makes it impossible to treat
|
||||||
it makes it impossible to treat these as generic SGML
|
these as generic SGML files and simply convert them to
|
||||||
files and simply convert them to HTML, RTF, PS, and other
|
HTML, RTF, PS, and other formats in the same way the main
|
||||||
formats in the same way the main Handbook is generated. This
|
Handbook is generated. This <emphasis>would</emphasis>
|
||||||
<emphasis>would</emphasis> force you to rebuild the Handbook
|
force you to rebuild the Handbook every time you want to
|
||||||
every time you want to see the effect a change has had on just
|
see the effect a change has had on just one
|
||||||
one chapter.</para>
|
chapter.</para>
|
||||||
</sect4>
|
</sect4>
|
||||||
</sect3>
|
</sect3>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue