| 2.1. Linking in DocBook | ||
|---|---|---|
|
2. Editing DocBook Documents |  |
| 2.1. Linking in DocBook | ||
|---|---|---|
|
|
2. Editing DocBook Documents | |
DocBook actually provides a variety of linking mechanisms, but xxe does not offer all of them as options to insert into your documents. It's when you are doing linking that you are likely to be most aware of the fact that DocBook is, underneath it all, XML. Even more important than the specific tags used to support linking are the attributes:
Like the id attribute in
modern HTML, this can be attached to any
element to serve as an anchor - a mnemonic name for that
location within the document.
Used to link to an xml:id within the same document (not
necessarily the same web page when the document is being
converted to multi-page formats such as "pages" or "slides").
This is rather like the HTML usage href="#...", but
with linkends you do not give the
'#'.
Used to link to web URLs outside the document set.
Essentially identical to the HTML href.
Used to link to other documents within the same document
set. You name the document you want to link to using the same
targetdoc that you assigned to it
in the sitemap. The
DocBook tools will use the information in the sitemap to
determine the equivalent URL to insert into any generated web
pages.
Can be used in conjunction with a targetdoc to specify a location (an xml:id) within the target document that
you want to link to.
For consistency, the same attributes are used, without the
namespaces, in other linking contexts within this tool set. Both the
course
outline and the html output format allow the use of href to link outside of the document set and
targetdoc/targetptr to link within the document
set.
The actual link forms that you can insert into your documents with xxe are links and olinks.
A link is used for links that
do not refer to other documents within the document set. It can
be used as well for documents within the document set that do
not have their own targetdoc entry
in the sitemap (typically, source code pages or pages of HTML
that are copied "as is" rather than transformed via the HTML
output form).
A link takes the linkend attribute to link within the
same document. It takes the xlink:href attribute to link to anything
else.
The easiest way to create a link in xxe is to
highlight the text that you want to use as a link and use the
"" button in the toolbar.
Use the attribute boxes in the right column to set the values of
the linkend or the xlink:href attributes.
An olink links to other
documents within the document set that have been assigned a targetdoc name in the sitemap. The
advantage offered by olinks is that you don't need to know
exactly where the web pages of the target document will be
located, which depends both on how the directories were arranged
and on the output form(s) selected for that document.
An olink uses the targetdoc and, optionally, the targetptr attributes to name the
location to which the link points.
There are two ways to create an olink in xxe:
Select a phrase to serve as the linking text. Hit
^T or select the
button to wrap this text in
an element, Type "olink" (Actually, you only need to type
the first couple of letters till the list of options
narrows down to the one you want.) and hit
Enter. Use the attribute boxes in the
right column to set the values of the targetdoc and targetptr attributes.
With no text selected, position the text cursor
where you wish to place the link. Hit ^I or select the
Insert button to insert an element at that point. Type
"olink" (Actually, you only need to type the first couple
of letters till the list of options narrows down to the
one you want.) and hit Enter. Use the
attribute boxes in the right column to set the values of
the targetdoc and targetptr attributes.
Because you have not supplied any text to serve as
the actual link, when the olink
is processed the tools will consult the sitemap, then
fetch the title of the target document and insert that
title as the text for the link.
|
|
 |
|
| 2. Editing DocBook Documents |  |  |  |
2.2. Source Code Highlighting |