diff --git a/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml index dd3012e145..0eca499b2f 100644 --- a/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml @@ -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>