svn commit: r47382 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup
Warren Block <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
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>
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"