Correct link examples for DocBook 5.0.
This commit is contained in:
Warren Block
parent
9e23c7eb37
commit
4c94da4411
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=43247
1 changed files with 45 additions and 38 deletions
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue