svn commit: r43248 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup
Warren Block
wblock at FreeBSD.org
Tue Nov 26 06:01:00 UTC 2013
Author: wblock
Date: Tue Nov 26 06:00:59 2013
New Revision: 43248
URL: http://svnweb.freebsd.org/changeset/doc/43248
Log:
Whitespace-only changes, translators please ignore.
Modified:
head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
Modified: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Tue Nov 26 05:22:34 2013 (r43247)
+++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Tue Nov 26 06:00:59 2013 (r43248)
@@ -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 & 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,
- …) 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, …) 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>&man.ls.1;</literal></entry>
<entry>&man.ls.1;</entry>
- <entry>Usage: <literal>&man.ls.1; is the manual page for commandlscommand.</literal></entry>
+ <entry>Usage: <literal>&man.ls.1; is the manual page
+ for commandlscommand.</literal></entry>
</row>
<row>
<entry><literal>&man.cp.1;</literal></entry>
<entry>&man.cp.1;</entry>
- <entry>Usage: <literal>The manual page for commandcpcommand is &man.cp.1;.</literal></entry>
+ <entry>Usage: <literal>The manual page for
+ commandcpcommand is &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>&a.doc;</literal></entry>
<entry><literal>&a.doc;</literal></entry>
- <entry>Usage: <literal>A link to the &a.doc;.</literal></entry>
+ <entry>Usage: <literal>A link to the
+ &a.doc;.</literal></entry>
</row>
<row>
<entry><literal>&a.questions;</literal></entry>
<entry><literal>&a.questions;</literal></entry>
- <entry>Usage: <literal>A link to the &a.questions;.</literal></entry>
+ <entry>Usage: <literal>A link to the
+ &a.questions;.</literal></entry>
</row>
<row>
<entry><literal>&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="&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>&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>&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>&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>
More information about the svn-doc-all
mailing list