Date: Tue, 8 Sep 2015 03:59:03 +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: r47382 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup Message-ID: <201509080359.t883x3hU054853@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 <anchor>, xml:id makes those unnecessary. Remove section about using <link> 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 <uri>. 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 @@ <tag>para</tag>.</para> <example> - <title><tag>para</tag></title> + <title><tag>para</tag> Example</title> <para>Usage:</para> @@ -729,7 +729,7 @@ unattributed).</para> <example> - <title><tag>blockquote</tag></title> + <title><tag>blockquote</tag> Example</title> <para>Usage:</para> @@ -810,7 +810,7 @@ </itemizedlist> <example> - <title><tag>tip</tag> and <tag>important</tag></title> + <title><tag>tip</tag> and <tag>important</tag> Example</title> <para>Usage:</para> @@ -891,7 +891,7 @@ <example> <title><tag>itemizedlist</tag> and - <tag>orderedlist</tag></title> + <tag>orderedlist</tag> Example</title> <para>Usage:</para> @@ -951,7 +951,7 @@ entries.</para> <example xml:id="docbook-markup-variablelist-example"> - <title><tag>variablelist</tag></title> + <title><tag>variablelist</tag> Example</title> <para>Usage:</para> @@ -1013,7 +1013,7 @@ <tag>stepalternatives</tag>.</para> <example> - <title><tag>procedure</tag></title> + <title><tag>procedure</tag> Example</title> <para>Usage:</para> @@ -1093,7 +1093,7 @@ lines may be included.</para> <example> - <title><tag>programlisting</tag></title> + <title><tag>programlisting</tag> Example</title> <para>Usage:</para> @@ -1141,7 +1141,7 @@ main(void) <example> <title><tag>co</tag> and - <tag>calloutlist</tag></title> + <tag>calloutlist</tag> Example</title> <programlisting><tag class="starttag">para</tag>When finished, the program will look like this:<tag class="endtag">para</tag> @@ -1227,7 +1227,7 @@ main(void) one cell in the table.</para> <example> - <title><tag>informaltable</tag></title> + <title><tag>informaltable</tag> Example</title> <para>Usage:</para> @@ -1292,7 +1292,7 @@ main(void) <literal>informaltable frame="none"</literal>.</para> <example> - <title>Tables Where <literal>frame="none"</literal></title> + <title>Table with <literal>frame="none"</literal> Example</title> <para>Appearance:</para> @@ -1388,7 +1388,7 @@ main(void) <example> <title><tag>screen</tag>, <tag>prompt</tag>, - and <tag>userinput</tag></title> + and <tag>userinput</tag> Example</title> <para>Usage:</para> @@ -1447,7 +1447,7 @@ This is the file called 'foo2'</screen> <tag>emphasis</tag>.</para> <example> - <title><tag>emphasis</tag></title> + <title><tag>emphasis</tag> Example</title> <para>Usage:</para> @@ -1474,7 +1474,7 @@ This is the file called 'foo2'</screen> in the example below.</para> <example> - <title>Acronyms</title> + <title><tag>acronym</tag> Example</title> <para>Usage:</para> @@ -1504,7 +1504,7 @@ This is the file called 'foo2'</screen> <tag>quote</tag>.</para> <example> - <title>Quotations</title> + <title><tag>quote</tag> Example</title> <para>Usage:</para> @@ -1543,7 +1543,7 @@ This is the file called 'foo2'</screen> names, when wrapped in <tag>keycombo</tag>.</para> <example> - <title>Keys, Mouse Buttons, and Combinations</title> + <title>Keys, Mouse Buttons, and Combinations Example</title> <para>Usage:</para> @@ -1651,7 +1651,7 @@ This is the file called 'foo2'</screen> <acronym>HTML</acronym>, appear visually better.</para> <example> - <title>Applications, Commands, and Options</title> + <title>Applications, Commands, and Options Example</title> <para>Usage:</para> @@ -1708,7 +1708,7 @@ This is the file called 'foo2'</screen> extension, or a device name, use <tag>filename</tag>.</para> <example> - <title><tag>filename</tag></title> + <title><tag>filename</tag> Example</title> <para>Usage:</para> @@ -1759,7 +1759,7 @@ This is the file called 'foo2'</screen> <literal>port</literal>.</para> <example> - <title><tag>package</tag> Tag</title> + <title><tag>package</tag> Example</title> <para>Usage:</para> @@ -1878,7 +1878,7 @@ This is the file called 'foo2'</screen> </variablelist> <example> - <title><tag>systemitem</tag> and Classes</title> + <title><tag>systemitem</tag> and Classes Example</title> <para>Usage:</para> @@ -1939,6 +1939,35 @@ This is the file called 'foo2'</screen> </example> </sect2> + <sect2 xml:id="docbook-markup-uri"> + <title>Uniform Resource Identifiers + (<acronym>URI</acronym>s)</title> + + <para>Occasionally it is useful to show a + Uniform Resource Identifier (<acronym>URI</acronym>) without + making it an active hyperlink. The <tag>uri</tag> element + makes this possible:</para> + + <example> + <title><tag>uri</tag> Example</title> + + <para>Usage:</para> + + <programlisting><tag class="starttag">para</tag>This <acronym>URL</acronym> shows only as text: + <tag class="starttag">uri</tag>https://www.FreeBSD.org<tag class="endtag">uri</tag>. It does not + create a link.<tag class="endtag">para</tag></programlisting> + + <para>Appearance:</para> + + <para>This <acronym>URL</acronym> shows only as text: + <uri>https://www.FreeBSD.org</uri>. It does not + create a link.</para> + </example> + + <para>To create links, see + <xref linkend="docbook-markup-links"/>.</para> + </sect2> + <sect2 xml:id="docbook-markup-email-addresses"> <title>Email Addresses</title> @@ -1949,7 +1978,7 @@ This is the file called 'foo2'</screen> address into a link.</para> <example> - <title><tag>email</tag> with a Hyperlink</title> + <title><tag>email</tag> with a Hyperlink Example</title> <para>Usage:</para> @@ -1970,7 +1999,7 @@ This is the file called 'foo2'</screen> address.</para> <example> - <title><tag>email</tag> Without a Hyperlink</title> + <title><tag>email</tag> Without a Hyperlink Example</title> <para>Usage:</para> @@ -2012,7 +2041,7 @@ This is the file called 'foo2'</screen> <example> <title><tag>buildtarget</tag> and - <tag>varname</tag></title> + <tag>varname</tag> Example</title> <para>Usage:</para> @@ -2067,7 +2096,7 @@ This is the file called 'foo2'</screen> <tag>literal</tag>.</para> <example> - <title><tag>literal</tag></title> + <title><tag>literal</tag> Example</title> <para>Usage:</para> @@ -2100,7 +2129,7 @@ This is the file called 'foo2'</screen> the user must replace.</para> <example> - <title><tag>replaceable</tag></title> + <title><tag>replaceable</tag> Example</title> <para>Usage:</para> @@ -2151,7 +2180,7 @@ This is the file called 'foo2'</screen> added surrounding the text.</para> <example> - <title><tag>guibutton</tag></title> + <title><tag>guibutton</tag> Example</title> <para>Usage:</para> @@ -2175,7 +2204,7 @@ This is the file called 'foo2'</screen> that appears.</para> <example> - <title><tag>errorname</tag></title> + <title><tag>errorname</tag> Example</title> <para>Usage:</para> @@ -2499,7 +2528,9 @@ IMAGES= chapter1/fig1.png <title>Links</title> <note> - <para>Links are also in-line elements.</para> + <para>Links are also in-line elements. To show a + <acronym>URI</acronym> without creating a link, see + <xref linkend="docbook-markup-uri"/>.</para> </note> <sect2 xml:id="docbook-markup-links-ids"> @@ -2515,12 +2546,12 @@ IMAGES= chapter1/fig1.png 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 + reference points by anyone referring to the <acronym>HTML</acronym> version of the document.</para> <example> <title><literal>xml:id</literal> on Chapters and - Sections</title> + Sections Example</title> <programlisting><tag class="starttag">chapter xml:id="introduction"</tag> <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag> @@ -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.</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 - <tag>anchor</tag>. This element has no content, but - 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 xml:id="para1"</tag>link target in it. It will not - show up in the document.<tag class="endtag">para</tag></programlisting> - </example> </sect2> <sect2 xml:id="docbook-markup-links-crossreferences"> @@ -2570,7 +2588,7 @@ IMAGES= chapter1/fig1.png generates the link text automatically.</para> <example> - <title>Using <tag>xref</tag></title> + <title><tag>xref</tag> Example</title> <para>Assume that this fragment appears somewhere in a document that includes the <literal>xml:id</literal> @@ -2599,84 +2617,33 @@ IMAGES= chapter1/fig1.png <para>The link text is generated automatically from the chapter and section number and <literal>title</literal> elements.</para> - - <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> - </note> </sect2> - <sect2 xml:id="docbook-markup-links-to-same-or-web-documents"> - <title>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</title> - <para>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 + <para>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.</para> - <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> - - <example> - <title>Using <tag>link</tag></title> - - <para>Assume that this fragment appears somewhere in a - document that includes the <literal>xml:id</literal> - example.</para> - - <programlisting><tag class="starttag">para</tag>More information can be found in the - <tag class="starttag">link linkend="introduction"</tag>sample introduction<tag class="endtag">link</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>More specific information can be found in the - <tag class="starttag">link linkend="introduction-moredetails"</tag>sample introduction with more - details<tag class="endtag">link</tag> section.<tag class="endtag">para</tag></programlisting> - - <para>This output will be generated - (<emphasis>emphasized</emphasis> text is used to show the - link text):</para> - - <blockquote> - <para>More information can be found in the - <emphasis>sample introduction</emphasis>.</para> - - <para>More specific information can be found in the - <emphasis>sample introduction with more - details</emphasis> section.</para> - </blockquote> - </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 - text.</para> - </note> - </sect3> - - <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 + <para>The <literal>xlink:href</literal> attribute + is the <acronym>URL</acronym> of the page, + and the content of the element is the text that will be displayed for the user to activate.</para> + <para>In many situations, it is preferable to show the actual + <acronym>URL</acronym> rather than text. This can be done by + leaving out the element text entirely.</para> + <example> <title><tag>link</tag> to a &os; Documentation Web - Page</title> + Page Example</title> <para>Link to the book or article <acronym>URL</acronym> entity. To link to a specific chapter in a book, add a @@ -2687,7 +2654,7 @@ IMAGES= chapter1/fig1.png <acronym>URL</acronym> entities can be found in <filename>doc/share/xml/urls.ent</filename>.</para> - <para>Usage for book links:</para> + <para>Usage for &os; book links:</para> <programlisting><tag class="starttag">para</tag>Read the <tag class="starttag">link xlink:href="&url.books.handbook;/svn.html#svn-intro"</tag>SVN @@ -2705,7 +2672,7 @@ IMAGES= chapter1/fig1.png xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion mirror sites</link>.</para> - <para>Usage for article links:</para> + <para>Usage for &os; article links:</para> <programlisting><tag class="starttag">para</tag>Read this <tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;"</tag>article @@ -2721,7 +2688,7 @@ IMAGES= chapter1/fig1.png </example> <example> - <title><tag>link</tag> to a &os; Web Page</title> + <title><tag>link</tag> to a &os; Web Page Example</title> <para>Usage:</para> @@ -2736,8 +2703,8 @@ IMAGES= chapter1/fig1.png </example> <example> - <title><tag>ulink</tag> to an External Web - Page</title> + <title><tag>link</tag> to an External Web + Page Example</title> <para>Usage:</para> @@ -2759,13 +2726,19 @@ IMAGES= chapter1/fig1.png 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> + <para>The same link can be entered using shorter + notation instead of a separate ending tag:</para> + + <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on + GUID Partition Tables: <tag class="emptytag">link + xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>.<tag class="endtag">para</tag></programlisting> + + <para>The two methods are equivalent. 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>; </example> - </sect3> </sect2> </sect1> </chapter>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201509080359.t883x3hU054853>