From owner-svn-doc-all@FreeBSD.ORG Tue Nov 26 05:22:35 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 7CF19B83; Tue, 26 Nov 2013 05:22:35 +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 5DA1622C6; Tue, 26 Nov 2013 05:22:35 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id rAQ5MZrZ012563; Tue, 26 Nov 2013 05:22:35 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id rAQ5MZsZ012562; Tue, 26 Nov 2013 05:22:35 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201311260522.rAQ5MZsZ012562@svn.freebsd.org> From: Warren Block Date: Tue, 26 Nov 2013 05:22:35 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43247 - 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 05:22:35 -0000 Author: wblock Date: Tue Nov 26 05:22:34 2013 New Revision: 43247 URL: http://svnweb.freebsd.org/changeset/doc/43247 Log: Correct link examples for DocBook 5.0. 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 03:45:13 2013 (r43246) +++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Tue Nov 26 05:22:34 2013 (r43247) @@ -132,6 +132,13 @@ + + + + + + + @@ -2343,32 +2350,32 @@ IMAGES= chapter1/fig1.png - <literal>id</literal> Attributes + <literal>xml:id</literal> Attributes - Most DocBook elements accept an id + Most DocBook elements accept an xml:id attribute to give that part of the document a unique name. - The id can be used as a target for a + The xml:id can be used as a target for a crossreference or link. Any portion of the document that will be a link target - must have an id attribute. Assigning an - id to all chapters and sections, even if + 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 ids can be used as unique anchor + These xml:ids can be used as unique anchor reference points by anyone referring to the HTML version of the document. - <literal>id</literal> on Chapters and + <title><literal>xml:id</literal> on Chapters and Sections - chapter id="introduction" + chapter xml:id="introduction" titleIntroductiontitle paraThis is the introduction. It contains a subsection, which is identified as well.para - sect1 id="introduction-moredetails" + sect1 xml:id="introduction-moredetails" titleMore Detailstitle paraThis is a subsection.para @@ -2376,12 +2383,12 @@ IMAGES= chapter1/fig1.png chapter - Use descriptive values for id names. + 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 - id is constructed by appending text to the - chapter id. This ensures that the - ids are unique. It also helps both reader + 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. @@ -2389,13 +2396,13 @@ IMAGES= chapter1/fig1.png 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 id attribute. + takes an xml:id attribute. <tag>anchor</tag> paraThis paragraph has an embedded - anchor id="para1"link target in it. It will not + anchor xml:id="para1"link target in it. It will not show up in the document.para @@ -2405,7 +2412,7 @@ IMAGES= chapter1/fig1.png xref provides the reader with a link to jump to another section of the document. The target - id is specified in the + xml:id is specified in the linkend attribute, and xref generates the link text automatically. @@ -2414,7 +2421,7 @@ IMAGES= chapter1/fig1.png Using <tag>xref</tag> Assume that this fragment appears somewhere in a - document that includes the id + document that includes the xml:id example shown above: paraMore information can be found @@ -2443,7 +2450,7 @@ IMAGES= chapter1/fig1.png xref cannot link to an - id attribute on an + xml:id attribute on an anchor element. The anchor has no content, so the xref cannot generate the link @@ -2468,7 +2475,7 @@ IMAGES= chapter1/fig1.png Links to the Same Document link is used to create a link - within the same document. The target id + 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. @@ -2477,7 +2484,7 @@ IMAGES= chapter1/fig1.png Using <tag>link</tag> Assume that this fragment appears somewhere in a - document that includes the id + document that includes the xml:id example. paraMore information can be found in the @@ -2503,7 +2510,7 @@ IMAGES= chapter1/fig1.png link can be used to include links - to the id of an + to the xml:id of an anchor element, since the link content defines the link text. @@ -2520,7 +2527,7 @@ IMAGES= chapter1/fig1.png that will be displayed for the user to activate. - <tag>ulink</tag> to a &os; Documentation Web + <title><tag>link</tag> to a &os; Documentation Web Page Link to the book or article URL @@ -2534,12 +2541,12 @@ IMAGES= chapter1/fig1.png Usage for book links: - paraRead the ulink - url="&url.books.handbook;/svn.html#svn-intro"SVN - introductionulink, then pick the nearest mirror from - the list of ulink - url="&url.books.handbook;/svn-mirrors.html"Subversion - mirror sitesulink.para + paraRead the link + xlink:href="&url.books.handbook;/svn.html#svn-intro"SVN + introductionlink, then pick the nearest mirror from + the list of link + xlink:href="&url.books.handbook;/svn-mirrors.html"Subversion + mirror siteslink.para Appearance: @@ -2551,9 +2558,9 @@ IMAGES= chapter1/fig1.png Usage for article links: paraRead this - ulink url="&url.articles.bsdl-gpl;"article - about the BSD licenseulink, or just the - ulink url="&url.articles.bsdl-gpl;#intro"introductionulink.para + link xlink:href="&url.articles.bsdl-gpl;"article + about the BSD licenselink, or just the + link xlink:href="&url.articles.bsdl-gpl;#intro"introductionlink.para Appearance: @@ -2562,12 +2569,12 @@ IMAGES= chapter1/fig1.png - <tag>ulink</tag> to a &os; Web Page + <tag>link</tag> to a &os; Web Page Usage: paraOf course, you could stop reading this document and go to the - ulink url="&url.base;/index.html"FreeBSD home pageulink instead.para + link xlink:href="&url.base;/index.html"FreeBSD home pagelink instead.para Appearance: @@ -2583,9 +2590,9 @@ IMAGES= chapter1/fig1.png Usage: paraWikipedia has an excellent reference on - ulink - url="http://en.wikipedia.org/wiki/GUID_Partition_Table"GUID - Partition Tablesulink.para + link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"GUID + Partition Tableslink.para Appearance: @@ -2597,8 +2604,8 @@ IMAGES= chapter1/fig1.png URL: paraWikipedia has an excellent reference on - GUID Partition Tables: ulink - url="http://en.wikipedia.org/wiki/GUID_Partition_Table"ulink.para + GUID Partition Tables: link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"link.para Appearance: