Date: Tue, 26 Nov 2013 05:22:35 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> 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 Message-ID: <201311260522.rAQ5MZsZ012562@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 @@ <colspec colname="entity"/> <colspec colname="expandsto"/> <colspec colname="notes"/> + <thead> + <row> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + </thead> <tbody valign="top"> <row> @@ -2343,32 +2350,32 @@ IMAGES= chapter1/fig1.png </note> <sect2 xml:id="docbook-markup-links-ids"> - <title><literal>id</literal> Attributes</title> + <title><literal>xml:id</literal> Attributes</title> - <para>Most DocBook elements accept an <literal>id</literal> + <para>Most DocBook elements accept an <literal>xml:id</literal> attribute to give that part of the document a unique name. - The <literal>id</literal> can be used as a target for a + The <literal>xml:id</literal> can be used as a target for a crossreference or link.</para> <para>Any portion of the document that will be a link target - must have an <literal>id</literal> attribute. Assigning an - <literal>id</literal> to all chapters and sections, even if + 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>id</literal>s can be used as unique anchor + 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> - <title><literal>id</literal> on Chapters and + <title><literal>xml:id</literal> on Chapters and Sections</title> - <programlisting><tag class="starttag">chapter id="introduction"</tag> + <programlisting><tag class="starttag">chapter xml:id="introduction"</tag> <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag> <tag class="starttag">para</tag>This is the introduction. It contains a subsection, which is identified as well.<tag class="endtag">para</tag> - <tag class="starttag">sect1 id="introduction-moredetails"</tag> + <tag class="starttag">sect1 xml:id="introduction-moredetails"</tag> <tag class="starttag">title</tag>More Details<tag class="endtag">title</tag> <tag class="starttag">para</tag>This is a subsection.<tag class="endtag">para</tag> @@ -2376,12 +2383,12 @@ IMAGES= chapter1/fig1.png <tag class="endtag">chapter</tag></programlisting> </example> - <para>Use descriptive values for <literal>id</literal> names. + <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>id</literal> is constructed by appending text to the - chapter <literal>id</literal>. This ensures that the - <literal>id</literal>s are unique. It also helps both reader + <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> @@ -2389,13 +2396,13 @@ IMAGES= chapter1/fig1.png <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 <tag>anchor</tag>. This element has no content, but - takes an <literal>id</literal> attribute.</para> + takes an <literal>xml:id</literal> attribute.</para> <example> <title><tag>anchor</tag></title> <programlisting><tag class="starttag">para</tag>This paragraph has an embedded - <tag class="emptytag">anchor id="para1"</tag>link target in it. It will not + <tag class="emptytag">anchor xml:id="para1"</tag>link target in it. It will not show up in the document.<tag class="endtag">para</tag></programlisting> </example> </sect2> @@ -2405,7 +2412,7 @@ IMAGES= chapter1/fig1.png <para><tag>xref</tag> provides the reader with a link to jump to another section of the document. The target - <literal>id</literal> is specified in the + <literal>xml:id</literal> is specified in the <literal>linkend</literal> attribute, and <tag>xref</tag> generates the link text automatically.</para> @@ -2414,7 +2421,7 @@ IMAGES= chapter1/fig1.png <title>Using <tag>xref</tag></title> <para>Assume that this fragment appears somewhere in a - document that includes the <literal>id</literal> + document that includes the <literal>xml:id</literal> example shown above:</para> <programlisting><tag class="starttag">para</tag>More information can be found @@ -2443,7 +2450,7 @@ IMAGES= chapter1/fig1.png <note> <para><tag>xref</tag> cannot link to an - <literal>id</literal> attribute on 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 @@ -2468,7 +2475,7 @@ IMAGES= chapter1/fig1.png <title>Links to the Same Document</title> <para><tag>link</tag> is used to create a link - within the same document. The target <literal>id</literal> + 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> @@ -2477,7 +2484,7 @@ IMAGES= chapter1/fig1.png <title>Using <tag>link</tag></title> <para>Assume that this fragment appears somewhere in a - document that includes the <literal>id</literal> + document that includes the <literal>xml:id</literal> example.</para> <programlisting><tag class="starttag">para</tag>More information can be found in the @@ -2503,7 +2510,7 @@ IMAGES= chapter1/fig1.png <note> <para><tag>link</tag> can be used to include links - to the <literal>id</literal> of an + to the <literal>xml:id</literal> of an <tag>anchor</tag> element, since the <tag>link</tag> content defines the link text.</para> @@ -2520,7 +2527,7 @@ IMAGES= chapter1/fig1.png that will be displayed for the user to activate.</para> <example> - <title><tag>ulink</tag> to a &os; Documentation Web + <title><tag>link</tag> to a &os; Documentation Web Page</title> <para>Link to the book or article <acronym>URL</acronym> @@ -2534,12 +2541,12 @@ IMAGES= chapter1/fig1.png <para>Usage for book links:</para> - <programlisting><tag class="starttag">para</tag>Read the <tag class="starttag">ulink - url="&url.books.handbook;/svn.html#svn-intro"</tag>SVN - introduction<tag class="endtag">ulink</tag>, then pick the nearest mirror from - the list of <tag class="starttag">ulink - url="&url.books.handbook;/svn-mirrors.html"</tag>Subversion - mirror sites<tag class="endtag">ulink</tag>.<tag class="endtag">para</tag></programlisting> + <programlisting><tag class="starttag">para</tag>Read the <tag class="starttag">link + xlink:href="&url.books.handbook;/svn.html#svn-intro"</tag>SVN + introduction<tag class="endtag">link</tag>, then pick the nearest mirror from + the list of <tag class="starttag">link + xlink:href="&url.books.handbook;/svn-mirrors.html"</tag>Subversion + mirror sites<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -2551,9 +2558,9 @@ IMAGES= chapter1/fig1.png <para>Usage for article links:</para> <programlisting><tag class="starttag">para</tag>Read this - <tag class="starttag">ulink url="&url.articles.bsdl-gpl;"</tag>article - about the BSD license<tag class="endtag">ulink</tag>, or just the - <tag class="starttag">ulink url="&url.articles.bsdl-gpl;#intro"</tag>introduction<tag class="endtag">ulink</tag>.<tag class="endtag">para</tag></programlisting> + <tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;"</tag>article + about the BSD license<tag class="endtag">link</tag>, or just the + <tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;#intro"</tag>introduction<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -2562,12 +2569,12 @@ IMAGES= chapter1/fig1.png </example> <example> - <title><tag>ulink</tag> to a &os; Web Page</title> + <title><tag>link</tag> to a &os; Web Page</title> <para>Usage:</para> <programlisting><tag class="starttag">para</tag>Of course, you could stop reading this document and go to the - <tag class="starttag">ulink url="&url.base;/index.html"</tag>FreeBSD home page<tag class="endtag">ulink</tag> instead.<tag class="endtag">para</tag></programlisting> + <tag class="starttag">link xlink:href="&url.base;/index.html"</tag>FreeBSD home page<tag class="endtag">link</tag> instead.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -2583,9 +2590,9 @@ IMAGES= chapter1/fig1.png <para>Usage:</para> <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on - <tag class="starttag">ulink - url="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>GUID - Partition Tables<tag class="endtag">ulink</tag>.<tag class="endtag">para</tag></programlisting> + <tag class="starttag">link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>GUID + Partition Tables<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -2597,8 +2604,8 @@ IMAGES= chapter1/fig1.png URL:</para> <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on - GUID Partition Tables: <tag class="starttag">ulink - url="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag><tag class="endtag">ulink</tag>.<tag class="endtag">para</tag></programlisting> + GUID Partition Tables: <tag class="starttag">link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag><tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201311260522.rAQ5MZsZ012562>