More on managing DocBook olinks

DocBook duck Since the end of last week, I have been looking at how to do inter-document links in DocBook. So far

XLink-style links, <link xlink:href="../some/other/doc.xml#anchor">, appear not to be touched by the stylesheets. In the HTML I seem to get <a href="../some/other/doc.xml#anchor">.

I suppose Xlink resolution is too difficult. Granted, such links break for documents not in the workspace. Seems like a standard pattern would be, however, to link mostly to documents in the workspace, then have a few links to other stable documents outside. At which point <link xlink:href=""> would be good enough for most purposes. (I have olinked across doc sets in the past where the tools team was maintaining software to help writers resolve links. That was a luxury, though.)

Olinks I have failed to get working so far. I have tried the following, for example:

<para>After you install OpenDJ, see
the <citetitle
Administration Guide</citetitle>
for instructions on using the

Here’s the relevant entry from the target database document (mostly made by hand until someone has time to dig into this RFE):

<dir name="admin-guide">
 <dir name="OpenDJ-Admin-Guide">
  <document targetdoc="admin-guide">
   <div element="book" href="OpenDJ-Admin-Guide.html
    "number="" targetptr="admin-guide">
    <ttl>OpenDJ 3.0.0-SNAPSHOT
     Administration Guide</ttl>
    <xreftext>OpenDJ 3.0.0-SNAPSHOT
     Administration Guide</xreftext>

The resulting link in the HTML:

<em class="citetitle"><a
 class="citetitle">OpenDJ Administration

If the <dir> stuff is not used, why should I bother to specify it as suggested in The Complete Guide? Maybe I misread something.

Still looking at how to do this.


1 Comment

Filed under Docs, Tools

One response to “More on managing DocBook olinks

  1. Hmm, I guess baseuri is a required attribute on document. If I update the target database document to include the baseuri attribute on document elements, then I can get the olink to work.

    Not sure how that will be better in practice for links to released docs than going directly to the HTML version.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s