From owner-svn-doc-all@FreeBSD.ORG Tue Nov 26 06:01:00 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 20791268; Tue, 26 Nov 2013 06:01:00 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 0EB4F2431; Tue, 26 Nov 2013 06:01:00 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id rAQ610a2025376; Tue, 26 Nov 2013 06:01:00 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id rAQ6101k025373; Tue, 26 Nov 2013 06:01:00 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201311260601.rAQ6101k025373@svn.freebsd.org> From: Warren Block Date: Tue, 26 Nov 2013 06:01:00 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43248 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 26 Nov 2013 06:01:00 -0000 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$ --> - + + + DocBook Markup @@ -47,10 +51,10 @@ DocBook was originally developed by HaL Computer Systems and O'Reilly & Associates to be a Document Type Definition (DTD) for writing technical documentation - A short history - can be found under - http://www.oasis-open.org/docbook/intro.shtml#d0e41.. - Since 1998 it is maintained by the + A short history can be found under http://www.oasis-open.org/docbook/intro.shtml#d0e41.. + Since 1998 it is maintained by the DocBook Technical Committee. As such, and unlike LinuxDoc and XHTML, DocBook is very heavily oriented towards markup that describes what @@ -89,23 +93,22 @@ &os; Extensions - The &os; Documentation Project has extended the - DocBook DTD with additional elements and - entities. These additions serve to make some of the markup - easier or more precise. + The &os; Documentation Project has extended the DocBook + DTD with additional elements and entities. + These additions serve to make some of the markup easier or more + precise. Throughout the rest of this document, the term DocBook is used to mean the &os;-extended DocBook DTD. - 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;. + 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;. @@ -113,7 +116,8 @@ The additional &os; elements are not (currently) in the Ports Collection. They are stored in the &os; Subversion - tree, as head/share/xml/freebsd.dtd. + tree, as head/share/xml/freebsd.dtd. &os;-specific elements used in the examples below are clearly marked. @@ -142,7 +146,8 @@ - &os; Name Entities + &os; Name + Entities @@ -170,19 +175,22 @@ - Manual Page Entities + Manual Page + Entities &man.ls.1; &man.ls.1; - Usage: &man.ls.1; is the manual page for commandlscommand. + Usage: &man.ls.1; is the manual page + for commandlscommand. &man.cp.1; &man.cp.1; - Usage: The manual page for commandcpcommand is &man.cp.1;. + Usage: The manual page for + commandcpcommand is &man.cp.1;. @@ -191,7 +199,8 @@ command manual page in section sectionnumber - Entities are defined for all the &os; manual + Entities are defined for all the + &os; manual pages. @@ -202,26 +211,30 @@ - &os; Mailing List Entities + &os; Mailing List + Entities &a.doc; &a.doc; - Usage: A link to the &a.doc;. + Usage: A link to the + &a.doc;. &a.questions; &a.questions; - Usage: A link to the &a.questions;. + Usage: A link to the + &a.questions;. &a.listname; link to listname - Entities are defined for all the &os; + Entities are defined for all the &os; mailing lists. @@ -232,7 +245,8 @@ - &os; Document Link Entities + &os; Document + Link Entities @@ -240,15 +254,16 @@ &url.books.handbook; Usage: A link to the ulink url="&url.books.handbook;/advanced-networking.html"Advanced - Networkingulink - chapter of the Handbook. + Networkingulink chapter of the + Handbook. &url.books.bookname; relative path to bookname - Entities are defined for all the &os; + Entities are defined for all the &os; books. @@ -265,7 +280,8 @@ &url.articles.articlename; relative path to articlename - Entities are defined for all the &os; + Entities are defined for all the &os; articles. @@ -276,7 +292,8 @@ - Other Operating System Name Entities + Other Operating + System Name Entities @@ -304,13 +321,15 @@ - Miscellaneous Entities + Miscellaneous + Entities &prompt.root; &prompt.root; - The root user + The root user prompt. @@ -394,11 +413,12 @@ several chapters, possibly with appendices and similar content as well. - The &os; tutorials - are all marked up as articles, while this - document, the - FreeBSD FAQ, - and the FreeBSD + The &os; + tutorials are all marked up as articles, while this + document, the FreeBSD FAQ, + and the FreeBSD Handbook are all marked up as books, for example. @@ -1120,8 +1140,7 @@ main(void) Table borders can be suppressed by setting the frame attribute to none in the informaltable element. For example, - informaltable - frame="none". + informaltable frame="none". Tables Where <literal>frame="none"</literal> @@ -1592,8 +1611,8 @@ This is the file called 'foo2' Appearance: - Install the net/wireshark port to view - network traffic. + Install the net/wireshark port to + view network traffic. @@ -1775,26 +1794,30 @@ This is the file called 'foo2' Appearance: - The local machine can always be referred to by the - name localhost, which will have the IP - address 127.0.0.1. + The local machine can always be referred to by the name + localhost, which will have the IP + address + 127.0.0.1. - The FreeBSD.org + The + FreeBSD.org domain contains a number of different hosts, including - freefall.FreeBSD.org and - bento.FreeBSD.org. + freefall.FreeBSD.org and + bento.FreeBSD.org. When adding an IP alias to an interface (using ifconfig) always use a netmask of - 255.255.255.255 (which can - also be expressed as + 255.255.255.255 + (which can also be expressed as 0xffffffff). The MAC address uniquely identifies every network card in existence. A typical - MAC address looks like - 08:00:20:87:ef:d0. + MAC address looks like 08:00:20:87:ef:d0. @@ -1824,7 +1847,8 @@ This is the file called 'foo2' Appearance: To carry out most system administration functions - requires logging in as root. + requires logging in as + root. @@ -2166,9 +2190,9 @@ This is the file called 'foo2' In a subdirectory of - doc/share/images - named after the document. For example, images for the - Handbook are stored in doc/share/images/books/handbook. + doc/share/images named after the + document. For example, images for the Handbook are stored + in doc/share/images/books/handbook. 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' Image Markup - Images are included as part of a - mediaobject. The - mediaobject can contain other, more - specific objects. We are concerned with two, the - imageobject and the - textobject. + Images are included as part of a mediaobject. + The mediaobject can contain other, more specific + objects. We are concerned with two, the + imageobject and the textobject. Include one imageobject, and two - textobject elements. The - imageobject will point to the name of the - image file without the extension. The - textobject elements contain information - that will be presented to the user as well as, or instead of, - the image itself. + textobject elements. The imageobject + will point to the name of the image file without the + extension. The textobject elements contain + information that will be presented to the user as well as, or + instead of, the image itself. Text elements are shown to the reader in several situations. When the document is viewed in @@ -2293,25 +2314,24 @@ IMAGES+= fig3.png Images and Chapters in Subdirectories Be careful when separating documentation into smaller - files in different directories (see ). + files in different directories (see ). Suppose there is a book with three chapters, and the chapters are stored in their own directories, called chapter1/chapter.xml, chapter2/chapter.xml, and chapter3/chapter.xml. If each chapter - has images associated with it, place - those images in each chapter's subdirectory - (chapter1/, + has images associated with it, place those images in each + chapter's subdirectory (chapter1/, chapter2/, and chapter3/). However, doing this requires including the directory names in the IMAGES variable in the Makefile, and - including the directory name in the - imagedata element in the document - document. + including the directory name in the imagedata + element in the document document. For example, if the book has chapter1/fig1.png, then @@ -2358,11 +2378,11 @@ IMAGES= chapter1/fig1.png crossreference or link. Any portion of the document that will be a link target - must have an xml:id attribute. Assigning an - xml:id to all chapters and sections, even if - there are no current plans to link to them, is a good idea. - These xml:ids can be used as unique anchor - reference points by anyone referring to the + must have an xml:id attribute. Assigning + an xml:id to all chapters and sections, + even if there are no current plans to link to them, is a good + idea. These xml:ids can be used as unique + anchor reference points by anyone referring to the HTML version of the document. @@ -2383,15 +2403,15 @@ IMAGES= chapter1/fig1.png chapter - Use descriptive values for xml:id names. - The values must be unique within the entire document, not just - in a single file. In the example, the subsection - xml:id is constructed by appending text to the - chapter xml:id. This ensures that the - xml:ids 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. + Use descriptive values for xml:id + names. The values must be unique within the entire document, + not just in a single file. In the example, the subsection + xml:id is constructed by appending text to + the chapter xml:id. This ensures that the + xml:ids 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. 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 Crossreferences with <literal>xref</literal> - xref provides the reader with a link to - jump to another section of the document. The target + xref provides the reader with a link to jump to + another section of the document. The target xml:id is specified in the - linkend attribute, and - xref generates the link text - automatically. + linkend attribute, and xref + generates the link text automatically. Using <tag>xref</tag> @@ -2450,11 +2469,9 @@ IMAGES= chapter1/fig1.png xref cannot link to an - xml:id attribute on an - anchor element. The - anchor has no content, so the - xref cannot generate the link - text. + xml:id attribute on an anchor + element. The anchor has no content, so the + xref cannot generate the link text. @@ -2474,11 +2491,10 @@ IMAGES= chapter1/fig1.png Links to the Same Document - link is used to create a link - within the same document. The target xml:id - is specified in the linkend attribute. - This element wraps content, which is used for the link - text. + link is used to create a link within the same + document. The target xml:id is specified + in the linkend attribute. This element + wraps content, which is used for the link text. Using <tag>link</tag> @@ -2509,10 +2525,9 @@ IMAGES= chapter1/fig1.png - link can be used to include links - to the xml:id of an - anchor element, since the - link content defines the link + link can be used to include links to the + xml:id of an anchor element, + since the link content defines the link text. @@ -2520,11 +2535,11 @@ IMAGES= chapter1/fig1.png Linking to Other Documents on the Web - The ulink is used to link to - external documents on the web. The url - attribute is the URL 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. + The ulink is used to link to external + documents on the web. The url attribute + is the URL 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. <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>