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

Whitespace-only changes, translators please ignore.

Browse source
This commit is contained in:
Warren Block 2013-11-26 06:00:59 +00:00
parent 4c94da4411
commit 50f9d88b40
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=43248
1 changed files with 144 additions and 124 deletions

268
en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
View file

@ -30,7 +30,11 @@
$FreeBSD$
-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="docbook-markup">
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="docbook-markup">
<title>DocBook Markup</title>
<sect1 xml:id="docbook-markup-introduction">
@ -47,10 +51,10 @@
<para>DocBook was originally developed by HaL Computer Systems and
O'Reilly &amp; Associates to be a Document Type Definition
(<acronym>DTD</acronym>) for writing technical documentation
<footnote><para>A short history
can be found under <link xlink:href="http://www.oasis-open.org/docbook/intro.shtml#d0e41">
http://www.oasis-open.org/docbook/intro.shtml#d0e41</link>.</para></footnote>.
Since 1998 it is maintained by the <link xlink:href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
<footnote><para>A short history can be found under <link
xlink:href="http://www.oasis-open.org/docbook/intro.shtml#d0e41">http://www.oasis-open.org/docbook/intro.shtml#d0e41</link>.</para></footnote>.
Since 1998 it is maintained by the <link
xlink:href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
DocBook Technical Committee</link>. As such, and unlike
LinuxDoc and <acronym>XHTML</acronym>, DocBook is very heavily
oriented towards markup that describes <emphasis>what</emphasis>
@ -89,23 +93,22 @@
<sect1 xml:id="docbook-markup-freebsd-extensions">
<title>&os; Extensions</title>
<para>The &os; Documentation Project has extended the
DocBook <acronym>DTD</acronym> with additional elements and
entities. These additions serve to make some of the markup
easier or more precise.</para>
<para>The &os; Documentation Project has extended the DocBook
<acronym>DTD</acronym> with additional elements and entities.
These additions serve to make some of the markup easier or more
precise.</para>
<para>Throughout the rest of this document, the term
<quote>DocBook</quote> is used to mean the &os;-extended
DocBook <acronym>DTD</acronym>.</para>
<note>
<para>Most of these extensions are not unique to &os;,
it was just felt that they were useful
enhancements for this particular project. Should anyone
from any of the other *nix camps (NetBSD, OpenBSD, Linux,
&hellip;) be interested in collaborating on a standard
DocBook extension set, please contact
&a.doceng;.</para>
<para>Most of these extensions are not unique to &os;, it was
just felt that they were useful enhancements for this
particular project. Should anyone from any of the other *nix
camps (NetBSD, OpenBSD, Linux, &hellip;) be interested in
collaborating on a standard DocBook extension set, please
contact &a.doceng;.</para>
</note>
<sect2 xml:id="docbook-markup-freebsd-extensions-elements">
@ -113,7 +116,8 @@
<para>The additional &os; elements are not (currently) in the
Ports Collection. They are stored in the &os; Subversion
tree, as <link xlink:href="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</link>.</para>
tree, as <link
xlink:href="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</link>.</para>
<para>&os;-specific elements used in the examples below are
clearly marked.</para>
@ -142,7 +146,8 @@
<tbody valign="top">
<row>
<entry namest="entity" nameend="notes">&os; Name Entities</entry>
<entry namest="entity" nameend="notes">&os; Name
Entities</entry>
</row>
<row>
@ -170,19 +175,22 @@
</row>
<row>
<entry namest="entity" nameend="notes">Manual Page Entities</entry>
<entry namest="entity" nameend="notes">Manual Page
Entities</entry>
</row>
<row>
<entry><literal>&amp;man.ls.1;</literal></entry>
<entry>&man.ls.1;</entry>
<entry>Usage: <literal>&amp;man.ls.1; is the manual page for commandlscommand.</literal></entry>
<entry>Usage: <literal>&amp;man.ls.1; is the manual page
for commandlscommand.</literal></entry>
</row>
<row>
<entry><literal>&amp;man.cp.1;</literal></entry>
<entry>&man.cp.1;</entry>
<entry>Usage: <literal>The manual page for commandcpcommand is &amp;man.cp.1;.</literal></entry>
<entry>Usage: <literal>The manual page for
commandcpcommand is &amp;man.cp.1;.</literal></entry>
</row>
<row>
@ -191,7 +199,8 @@
<replaceable>command</replaceable> manual page in
section
<replaceable>sectionnumber</replaceable></emphasis></entry>
<entry>Entities are defined for all the <link xlink:href="&url.base;/cgi/man.cgi">&os; manual
<entry>Entities are defined for all the
<link xlink:href="&url.base;/cgi/man.cgi">&os; manual
pages</link>.</entry>
</row>
@ -202,26 +211,30 @@
</row>
<row>
<entry namest="entity" nameend="notes">&os; Mailing List Entities</entry>
<entry namest="entity" nameend="notes">&os; Mailing List
Entities</entry>
</row>
<row>
<entry><literal>&amp;a.doc;</literal></entry>
<entry><literal>&a.doc;</literal></entry>
<entry>Usage: <literal>A link to the &amp;a.doc;.</literal></entry>
<entry>Usage: <literal>A link to the
&amp;a.doc;.</literal></entry>
</row>
<row>
<entry><literal>&amp;a.questions;</literal></entry>
<entry><literal>&a.questions;</literal></entry>
<entry>Usage: <literal>A link to the &amp;a.questions;.</literal></entry>
<entry>Usage: <literal>A link to the
&amp;a.questions;.</literal></entry>
</row>
<row>
<entry><literal>&amp;a.listname;</literal></entry>
<entry><emphasis>link to
<replaceable>listname</replaceable></emphasis></entry>
<entry>Entities are defined for all the <link xlink:href="&url.books.handbook;/eresources.html#eresources-mail">&os;
<entry>Entities are defined for all the <link
xlink:href="&url.books.handbook;/eresources.html#eresources-mail">&os;
mailing lists</link>.</entry>
</row>
@ -232,7 +245,8 @@
</row>
<row>
<entry namest="entity" nameend="notes">&os; Document Link Entities</entry>
<entry namest="entity" nameend="notes">&os; Document
Link Entities</entry>
</row>
<row>
@ -240,15 +254,16 @@
<entry><literal>&url.books.handbook;</literal></entry>
<entry>Usage: <literal>A link to the ulink
url="&amp;url.books.handbook;/advanced-networking.html"Advanced
Networkingulink
chapter of the Handbook.</literal></entry>
Networkingulink chapter of the
Handbook.</literal></entry>
</row>
<row>
<entry><literal>&amp;url.books.bookname;</literal></entry>
<entry><emphasis>relative path to
<replaceable>bookname</replaceable></emphasis></entry>
<entry>Entities are defined for all the <link xlink:href="&url.doc.langbase;/books/">&os;
<entry>Entities are defined for all the <link
xlink:href="&url.doc.langbase;/books/">&os;
books</link>.</entry>
</row>
@ -265,7 +280,8 @@
<entry><literal>&amp;url.articles.articlename;</literal></entry>
<entry><emphasis>relative path to
<replaceable>articlename</replaceable></emphasis></entry>
<entry>Entities are defined for all the <link xlink:href="&url.doc.langbase;/articles/">&os;
<entry>Entities are defined for all the <link
xlink:href="&url.doc.langbase;/articles/">&os;
articles</link>.</entry>
</row>
@ -276,7 +292,8 @@
</row>
<row>
<entry namest="entity" nameend="notes">Other Operating System Name Entities</entry>
<entry namest="entity" nameend="notes">Other Operating
System Name Entities</entry>
</row>
<row>
@ -304,13 +321,15 @@
</row>
<row>
<entry namest="entity" nameend="notes">Miscellaneous Entities</entry>
<entry namest="entity" nameend="notes">Miscellaneous
Entities</entry>
</row>
<row>
<entry><literal>&amp;prompt.root;</literal></entry>
<entry>&prompt.root;</entry>
<entry>The <systemitem class="username">root</systemitem> user
<entry>The <systemitem
class="username">root</systemitem> user
prompt.</entry>
</row>
@ -394,11 +413,12 @@
several chapters, possibly with appendices and similar content
as well.</para>
<para>The <link xlink:href="&url.base;/docs.html">&os; tutorials</link>
are all marked up as articles, while this
document, the
<link xlink:href="&url.books.faq;/index.html">FreeBSD FAQ</link>,
and the <link xlink:href="&url.books.handbook;/index.html">FreeBSD
<para>The <link xlink:href="&url.base;/docs.html">&os;
tutorials</link> are all marked up as articles, while this
document, the <link
xlink:href="&url.books.faq;/index.html">FreeBSD FAQ</link>,
and the <link
xlink:href="&url.books.handbook;/index.html">FreeBSD
Handbook</link> are all marked up as books, for
example.</para>
@ -1120,8 +1140,7 @@ main(void)
<para>Table borders can be suppressed by setting the
<literal>frame</literal> attribute to <literal>none</literal>
in the <tag>informaltable</tag> element. For example,
<literal>informaltable
frame="none"</literal>.</para>
<literal>informaltable frame="none"</literal>.</para>
<example>
<title>Tables Where <literal>frame="none"</literal></title>
@ -1592,8 +1611,8 @@ This is the file called 'foo2'</screen>
<para>Appearance:</para>
<para>Install the <package>net/wireshark</package> port to view
network traffic.</para>
<para>Install the <package>net/wireshark</package> port to
view network traffic.</para>
</example>
</sect2>
@ -1775,26 +1794,30 @@ This is the file called 'foo2'</screen>
<para>Appearance:</para>
<para>The local machine can always be referred to by the
name <systemitem>localhost</systemitem>, which will have the IP
address <systemitem class="ipaddress">127.0.0.1</systemitem>.</para>
<para>The local machine can always be referred to by the name
<systemitem>localhost</systemitem>, which will have the IP
address
<systemitem class="ipaddress">127.0.0.1</systemitem>.</para>
<para>The <systemitem class="fqdomainname">FreeBSD.org</systemitem>
<para>The
<systemitem class="fqdomainname">FreeBSD.org</systemitem>
domain contains a number of different hosts, including
<systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> and
<systemitem class="fqdomainname">bento.FreeBSD.org</systemitem>.</para>
<systemitem
class="fqdomainname">freefall.FreeBSD.org</systemitem> and
<systemitem
class="fqdomainname">bento.FreeBSD.org</systemitem>.</para>
<para>When adding an <acronym>IP</acronym> alias to an
interface (using <command>ifconfig</command>)
<emphasis>always</emphasis> use a netmask of
<systemitem class="netmask">255.255.255.255</systemitem> (which can
also be expressed as
<systemitem class="netmask">255.255.255.255</systemitem>
(which can also be expressed as
<systemitem class="netmask">0xffffffff</systemitem>).</para>
<para>The <acronym>MAC</acronym> address uniquely identifies
every network card in existence. A typical
<acronym>MAC</acronym> address looks like
<systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para>
<acronym>MAC</acronym> address looks like <systemitem
class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para>
</example>
</sect2>
@ -1824,7 +1847,8 @@ This is the file called 'foo2'</screen>
<para>Appearance:</para>
<para>To carry out most system administration functions
requires logging in as <systemitem class="username">root</systemitem>.</para>
requires logging in as
<systemitem class="username">root</systemitem>.</para>
</example>
</sect2>
@ -2166,9 +2190,9 @@ This is the file called 'foo2'</screen>
<listitem>
<para>In a subdirectory of
<filename>doc/share/images</filename>
named after the document. For example, images for the
Handbook are stored in <filename>doc/share/images/books/handbook</filename>.
<filename>doc/share/images</filename> named after the
document. For example, images for the Handbook are stored
in <filename>doc/share/images/books/handbook</filename>.
Images that work for multiple translations are stored in
this upper level of the documentation file tree.
Generally, these are images that can be used unchanged in
@ -2180,20 +2204,17 @@ This is the file called 'foo2'</screen>
<sect2 xml:id="docbook-markup-image-markup">
<title>Image Markup</title>
<para>Images are included as part of a
<tag>mediaobject</tag>. The
<tag>mediaobject</tag> can contain other, more
specific objects. We are concerned with two, the
<tag>imageobject</tag> and the
<tag>textobject</tag>.</para>
<para>Images are included as part of a <tag>mediaobject</tag>.
The <tag>mediaobject</tag> can contain other, more specific
objects. We are concerned with two, the
<tag>imageobject</tag> and the <tag>textobject</tag>.</para>
<para>Include one <tag>imageobject</tag>, and two
<tag>textobject</tag> elements. The
<tag>imageobject</tag> will point to the name of the
image file without the extension. The
<tag>textobject</tag> elements contain information
that will be presented to the user as well as, or instead of,
the image itself.</para>
<tag>textobject</tag> elements. The <tag>imageobject</tag>
will point to the name of the image file without the
extension. The <tag>textobject</tag> elements contain
information that will be presented to the user as well as, or
instead of, the image itself.</para>
<para>Text elements are shown to the reader in several
situations. When the document is viewed in
@ -2293,25 +2314,24 @@ IMAGES+= fig3.png
<title>Images and Chapters in Subdirectories</title>
<para>Be careful when separating documentation into smaller
files in different directories (see <xref linkend="xml-primer-include-using-gen-entities"/>).</para>
files in different directories (see <xref
linkend="xml-primer-include-using-gen-entities"/>).</para>
<para>Suppose there is a book with three chapters, and the
chapters are stored in their own directories, called
<filename>chapter1/chapter.xml</filename>,
<filename>chapter2/chapter.xml</filename>, and
<filename>chapter3/chapter.xml</filename>. If each chapter
has images associated with it, place
those images in each chapter's subdirectory
(<filename>chapter1/</filename>,
has images associated with it, place those images in each
chapter's subdirectory (<filename>chapter1/</filename>,
<filename>chapter2/</filename>, and
<filename>chapter3/</filename>).</para>
<para>However, doing this requires including the directory
names in the <varname>IMAGES</varname> variable in the
<filename>Makefile</filename>, <emphasis>and</emphasis>
including the directory name in the
<tag>imagedata</tag> element in the document
document.</para>
including the directory name in the <tag>imagedata</tag>
element in the document document.</para>
<para>For example, if the book has
<filename>chapter1/fig1.png</filename>, then
@ -2358,11 +2378,11 @@ IMAGES= chapter1/fig1.png
crossreference or link.</para>
<para>Any portion of the document that will be a link target
must have an <literal>xml:id</literal> attribute. Assigning an
<literal>xml:id</literal> to all chapters and sections, even if
there are no current plans to link to them, is a good idea.
These <literal>xml:id</literal>s can be used as unique anchor
reference points by anyone referring to the
must have an <literal>xml:id</literal> attribute. Assigning
an <literal>xml:id</literal> to all chapters and sections,
even if there are no current plans to link to them, is a good
idea. These <literal>xml:id</literal>s can be used as unique
anchor reference points by anyone referring to the
<acronym>HTML</acronym> version of the document.</para>
<example>
@ -2383,15 +2403,15 @@ IMAGES= chapter1/fig1.png
<tag class="endtag">chapter</tag></programlisting>
</example>
<para>Use descriptive values for <literal>xml:id</literal> names.
The values must be unique within the entire document, not just
in a single file. In the example, the subsection
<literal>xml:id</literal> is constructed by appending text to the
chapter <literal>xml:id</literal>. This ensures that the
<literal>xml:id</literal>s are unique. It also helps both reader
and anyone editing the document to see where the link is
located within the document, similar to a directory
path to a file.</para>
<para>Use descriptive values for <literal>xml:id</literal>
names. The values must be unique within the entire document,
not just in a single file. In the example, the subsection
<literal>xml:id</literal> is constructed by appending text to
the chapter <literal>xml:id</literal>. This ensures that the
<literal>xml:id</literal>s are unique. It also helps both
reader and anyone editing the document to see where the link
is located within the document, similar to a directory path to
a file.</para>
<para>To allow the user to jump into a specific portion of the
document, even in the middle of a paragraph or an example, use
@ -2410,12 +2430,11 @@ IMAGES= chapter1/fig1.png
<sect2 xml:id="docbook-markup-links-crossreferences">
<title>Crossreferences with <literal>xref</literal></title>
<para><tag>xref</tag> provides the reader with a link to
jump to another section of the document. The target
<para><tag>xref</tag> provides the reader with a link to jump to
another section of the document. The target
<literal>xml:id</literal> is specified in the
<literal>linkend</literal> attribute, and
<tag>xref</tag> generates the link text
automatically.</para>
<literal>linkend</literal> attribute, and <tag>xref</tag>
generates the link text automatically.</para>
<example>
<title>Using <tag>xref</tag></title>
@ -2450,11 +2469,9 @@ IMAGES= chapter1/fig1.png
<note>
<para><tag>xref</tag> cannot link to an
<literal>xml:id</literal> attribute on an
<tag>anchor</tag> element. The
<tag>anchor</tag> has no content, so the
<tag>xref</tag> cannot generate the link
text.</para>
<literal>xml:id</literal> attribute on an <tag>anchor</tag>
element. The <tag>anchor</tag> has no content, so the
<tag>xref</tag> cannot generate the link text.</para>
</note>
</sect2>
@ -2474,11 +2491,10 @@ IMAGES= chapter1/fig1.png
<sect3 xml:id="docbook-markup-links-to-same-document">
<title>Links to the Same Document</title>
<para><tag>link</tag> is used to create a link
within the same document. The target <literal>xml:id</literal>
is specified in the <literal>linkend</literal> attribute.
This element wraps content, which is used for the link
text.</para>
<para><tag>link</tag> is used to create a link within the same
document. The target <literal>xml:id</literal> is specified
in the <literal>linkend</literal> attribute. This element
wraps content, which is used for the link text.</para>
<example>
<title>Using <tag>link</tag></title>
@ -2509,10 +2525,9 @@ IMAGES= chapter1/fig1.png
</example>
<note>
<para><tag>link</tag> can be used to include links
to the <literal>xml:id</literal> of an
<tag>anchor</tag> element, since the
<tag>link</tag> content defines the link
<para><tag>link</tag> can be used to include links to the
<literal>xml:id</literal> of an <tag>anchor</tag> element,
since the <tag>link</tag> content defines the link
text.</para>
</note>
</sect3>
@ -2520,11 +2535,11 @@ IMAGES= chapter1/fig1.png
<sect3 xml:id="docbook-markup-links-to-web-documents">
<title>Linking to Other Documents on the Web</title>
<para>The <tag>ulink</tag> is used to link to
external documents on the web. The <literal>url</literal>
attribute is the <acronym>URL</acronym> of the page that the
link points to, and the content of the element is the text
that will be displayed for the user to activate.</para>
<para>The <tag>ulink</tag> is used to link to external
documents on the web. The <literal>url</literal> attribute
is the <acronym>URL</acronym> of the page that the link
points to, and the content of the element is the text that
will be displayed for the user to activate.</para>
<example>
<title><tag>link</tag> to a &os; Documentation Web
@ -2550,9 +2565,11 @@ IMAGES= chapter1/fig1.png
<para>Appearance:</para>
<para>Read the <link xlink:href="&url.books.handbook;/svn.html#svn-intro">SVN
<para>Read the <link
xlink:href="&url.books.handbook;/svn.html#svn-intro">SVN
introduction</link>, then pick the nearest mirror from
the list of <link xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion
the list of <link
xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion
mirror sites</link>.</para>
<para>Usage for article links:</para>
@ -2564,8 +2581,10 @@ IMAGES= chapter1/fig1.png
<para>Appearance:</para>
<para>Read this <link xlink:href="&url.articles.bsdl-gpl;">article
about the BSD license</link>, or just the <link xlink:href="&url.articles.bsdl-gpl;#intro">introduction</link>.</para>
<para>Read this
<link xlink:href="&url.articles.bsdl-gpl;">article
about the BSD license</link>, or just the <link
xlink:href="&url.articles.bsdl-gpl;#intro">introduction</link>.</para>
</example>
<example>
@ -2579,8 +2598,8 @@ IMAGES= chapter1/fig1.png
<para>Appearance:</para>
<para>Of course, you could stop reading this document and go
to the <link xlink:href="&url.base;/index.html">FreeBSD home
page</link> instead.</para>
to the <link xlink:href="&url.base;/index.html">FreeBSD
home page</link> instead.</para>
</example>
<example>
@ -2596,8 +2615,8 @@ IMAGES= chapter1/fig1.png
<para>Appearance:</para>
<para>Wikipedia has an excellent reference on
<link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
<para>Wikipedia has an excellent reference on <link
xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
Partition Tables</link>.</para>
<para>The link text can be omitted to show the actual
@ -2609,8 +2628,9 @@ IMAGES= chapter1/fig1.png
<para>Appearance:</para>
<para>Wikipedia has an excellent reference on
GUID Partition Tables: <uri xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">http://en.wikipedia.org/wiki/GUID_Partition_Table</uri>.</para>
<para>Wikipedia has an excellent reference on GUID Partition
Tables: <uri
xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">http://en.wikipedia.org/wiki/GUID_Partition_Table</uri>.</para>
</example>
</sect3>
</sect2>