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.
This commit is contained in:
Warren Block
parent
34e6f56fcc
commit
98ecd8f450
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=47382
1 changed files with 90 additions and 117 deletions
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue