From owner-svn-doc-all@freebsd.org Tue Sep 8 03:59:03 2015 Return-Path: Delivered-To: svn-doc-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 4CAB49C8631; Tue, 8 Sep 2015 03:59:03 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 3C3581497; Tue, 8 Sep 2015 03:59:03 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.70]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id t883x3W7054854; Tue, 8 Sep 2015 03:59:03 GMT (envelope-from wblock@FreeBSD.org) Received: (from wblock@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id t883x3hU054853; Tue, 8 Sep 2015 03:59:03 GMT (envelope-from wblock@FreeBSD.org) Message-Id: <201509080359.t883x3hU054853@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: wblock set sender to wblock@FreeBSD.org using -f From: Warren Block Date: Tue, 8 Sep 2015 03:59:03 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r47382 - 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.20 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, 08 Sep 2015 03:59:03 -0000 Author: wblock Date: Tue Sep 8 03:59:02 2015 New Revision: 47382 URL: https://svnweb.freebsd.org/changeset/doc/47382 Log: Clean up Links section: Remove section about , xml:id makes those unnecessary. Remove section about using to link to the same document. Change ulink reference to link. Add an example showing using an XML empty tag for a link. Add an example of using . Add "Example" to example titles. 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 Mon Sep 7 19:14:37 2015 (r47381) +++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Tue Sep 8 03:59:02 2015 (r47382) @@ -703,7 +703,7 @@ para. - <tag>para</tag> + <tag>para</tag> Example Usage: @@ -729,7 +729,7 @@ unattributed). - <tag>blockquote</tag> + <tag>blockquote</tag> Example Usage: @@ -810,7 +810,7 @@ - <tag>tip</tag> and <tag>important</tag> + <tag>tip</tag> and <tag>important</tag> Example Usage: @@ -891,7 +891,7 @@ <tag>itemizedlist</tag> and - <tag>orderedlist</tag> + orderedlist Example Usage: @@ -951,7 +951,7 @@ entries. - <tag>variablelist</tag> + <tag>variablelist</tag> Example Usage: @@ -1013,7 +1013,7 @@ stepalternatives. - <tag>procedure</tag> + <tag>procedure</tag> Example Usage: @@ -1093,7 +1093,7 @@ lines may be included. - <tag>programlisting</tag> + <tag>programlisting</tag> Example Usage: @@ -1141,7 +1141,7 @@ main(void) <tag>co</tag> and - <tag>calloutlist</tag> + calloutlist Example paraWhen finished, the program will look like this:para @@ -1227,7 +1227,7 @@ main(void) one cell in the table. - <tag>informaltable</tag> + <tag>informaltable</tag> Example Usage: @@ -1292,7 +1292,7 @@ main(void) informaltable frame="none". - Tables Where <literal>frame="none"</literal> + Table with <literal>frame="none"</literal> Example Appearance: @@ -1388,7 +1388,7 @@ main(void) <tag>screen</tag>, <tag>prompt</tag>, - and <tag>userinput</tag> + and userinput Example Usage: @@ -1447,7 +1447,7 @@ This is the file called 'foo2' emphasis. - <tag>emphasis</tag> + <tag>emphasis</tag> Example Usage: @@ -1474,7 +1474,7 @@ This is the file called 'foo2' in the example below. - Acronyms + <tag>acronym</tag> Example Usage: @@ -1504,7 +1504,7 @@ This is the file called 'foo2' quote. - Quotations + <tag>quote</tag> Example Usage: @@ -1543,7 +1543,7 @@ This is the file called 'foo2' names, when wrapped in keycombo. - Keys, Mouse Buttons, and Combinations + Keys, Mouse Buttons, and Combinations Example Usage: @@ -1651,7 +1651,7 @@ This is the file called 'foo2' HTML, appear visually better. - Applications, Commands, and Options + Applications, Commands, and Options Example Usage: @@ -1708,7 +1708,7 @@ This is the file called 'foo2' extension, or a device name, use filename. - <tag>filename</tag> + <tag>filename</tag> Example Usage: @@ -1759,7 +1759,7 @@ This is the file called 'foo2' port. - <tag>package</tag> Tag + <tag>package</tag> Example Usage: @@ -1878,7 +1878,7 @@ This is the file called 'foo2' - <tag>systemitem</tag> and Classes + <tag>systemitem</tag> and Classes Example Usage: @@ -1939,6 +1939,35 @@ This is the file called 'foo2' + + Uniform Resource Identifiers + (<acronym>URI</acronym>s) + + Occasionally it is useful to show a + Uniform Resource Identifier (URI) without + making it an active hyperlink. The uri element + makes this possible: + + + <tag>uri</tag> Example + + Usage: + + paraThis URL shows only as text: + urihttps://www.FreeBSD.orguri. It does not + create a link.para + + Appearance: + + This URL shows only as text: + https://www.FreeBSD.org. It does not + create a link. + + + To create links, see + . + + Email Addresses @@ -1949,7 +1978,7 @@ This is the file called 'foo2' address into a link. - <tag>email</tag> with a Hyperlink + <tag>email</tag> with a Hyperlink Example Usage: @@ -1970,7 +1999,7 @@ This is the file called 'foo2' address. - <tag>email</tag> Without a Hyperlink + <tag>email</tag> Without a Hyperlink Example Usage: @@ -2012,7 +2041,7 @@ This is the file called 'foo2' <tag>buildtarget</tag> and - <tag>varname</tag> + varname Example Usage: @@ -2067,7 +2096,7 @@ This is the file called 'foo2' literal. - <tag>literal</tag> + <tag>literal</tag> Example Usage: @@ -2100,7 +2129,7 @@ This is the file called 'foo2' the user must replace. - <tag>replaceable</tag> + <tag>replaceable</tag> Example Usage: @@ -2151,7 +2180,7 @@ This is the file called 'foo2' added surrounding the text. - <tag>guibutton</tag> + <tag>guibutton</tag> Example Usage: @@ -2175,7 +2204,7 @@ This is the file called 'foo2' that appears. - <tag>errorname</tag> + <tag>errorname</tag> Example Usage: @@ -2499,7 +2528,9 @@ IMAGES= chapter1/fig1.png Links - Links are also in-line elements. + Links are also in-line elements. To show a + URI without creating a link, see + . @@ -2515,12 +2546,12 @@ IMAGES= chapter1/fig1.png 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 + reference points by anyone referring to the HTML version of the document. <literal>xml:id</literal> on Chapters and - Sections + Sections Example chapter xml:id="introduction" titleIntroductiontitle @@ -2545,19 +2576,6 @@ IMAGES= chapter1/fig1.png 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 - anchor. This element has no content, but - takes an xml:id attribute. - - - <tag>anchor</tag> - - paraThis paragraph has an embedded - anchor xml:id="para1"link target in it. It will not - show up in the document.para - @@ -2570,7 +2588,7 @@ IMAGES= chapter1/fig1.png generates the link text automatically. - Using <tag>xref</tag> + <tag>xref</tag> Example Assume that this fragment appears somewhere in a document that includes the xml:id @@ -2599,84 +2617,33 @@ IMAGES= chapter1/fig1.png The link text is generated automatically from the chapter and section number and title elements. - - - 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. - - - Linking to the Same Document or Other Documents on the + <sect2 xml:id="docbook-markup-links-to-web-documents"> + <title>Linking to Other Documents on the Web - The link elements described here allow the writer to - define the link text. It is very important to use descriptive - link text to give the reader an idea of where the link will - take them. Remember that DocBook can be rendered to multiple - types of media. The reader may be looking at a printed book + The link element described here allows the writer to + define the link text. When link text is used, it is very important to be descriptive + to give the reader an idea of where the link goes. + Remember that DocBook can be rendered to multiple + types of media. The reader might be looking at a printed book or other form of media where there are no links. If the link - text is not descriptive enough, the reader may not be able to + text is not descriptive enough, the reader might not be able to locate the linked section. - - 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. - - - Using <tag>link</tag> - - Assume that this fragment appears somewhere in a - document that includes the xml:id - example. - - paraMore information can be found in the - link linkend="introduction"sample introductionlink.para - -paraMore specific information can be found in the - link linkend="introduction-moredetails"sample introduction with more - detailslink section.para - - This output will be generated - (emphasized text is used to show the - link text): - -
- More information can be found in the - sample introduction. - - More specific information can be found in the - sample introduction with more - details section. -
- - - - link can be used to include links to the - xml:id of an anchor element, - since the link content defines the link - text. - - - - - 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 + The xlink:href attribute + is the URL of the page, + and the content of the element is the text that will be displayed for the user to activate. + In many situations, it is preferable to show the actual + URL rather than text. This can be done by + leaving out the element text entirely. + <tag>link</tag> to a &os; Documentation Web - Page + Page Example Link to the book or article URL entity. To link to a specific chapter in a book, add a @@ -2687,7 +2654,7 @@ IMAGES= chapter1/fig1.png URL entities can be found in doc/share/xml/urls.ent. - Usage for book links: + Usage for &os; book links: paraRead the link xlink:href="&url.books.handbook;/svn.html#svn-intro"SVN @@ -2705,7 +2672,7 @@ IMAGES= chapter1/fig1.png xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion mirror sites. - Usage for article links: + Usage for &os; article links: paraRead this link xlink:href="&url.articles.bsdl-gpl;"article @@ -2721,7 +2688,7 @@ IMAGES= chapter1/fig1.png - <tag>link</tag> to a &os; Web Page + <tag>link</tag> to a &os; Web Page Example Usage: @@ -2736,8 +2703,8 @@ IMAGES= chapter1/fig1.png - <tag>ulink</tag> to an External Web - Page + <tag>link</tag> to an External Web + Page Example Usage: @@ -2759,13 +2726,19 @@ IMAGES= chapter1/fig1.png GUID Partition Tables: link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"link.para - Appearance: + The same link can be entered using shorter + notation instead of a separate ending tag: + + paraWikipedia has an excellent reference on + GUID Partition Tables: link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table".para + + The two methods are equivalent. Appearance: Wikipedia has an excellent reference on GUID Partition Tables: http://en.wikipedia.org/wiki/GUID_Partition_Table. -