Managing DocBook olinks across releases?

DocBook duck For those handling inter-document links in DocBook-based documentation, a question. What’s the best way to do inter-document link management using only open source software? I’m thinking of olink management for multiple documentation releases, with links between doc sets of different versions.

I have read the chapter on olinking from Bob Stayton’s book. Looks like the syntax for olinks in DocBook 5 now uses xlink:role="http://docbook.org/xlink/role/olink" & xlink:href="targetdoc#targetptr" on any inline element rather than the old targetdoc & targetptr attributes on the <olink> element itself. Perhaps managing inter-document links is now more generic.

Maybe there are best practices to read somewhere on the following:

  • Managing target databases during development (central DB for released doc, in-progress DB for current doc set)
  • Consolidating an overall target database referencing released doc sets
  • Target lookup tools for authors
  • Testing (esp. for broken links)
  • Fixing bugs in the overall target database
  • Handling multiple languages
Where should I start learning about this?
Advertisements

4 Comments

Filed under Docs, Tools

4 responses to “Managing DocBook olinks across releases?

  1. Nat

    Did you ever answer your question?

    I’ve just hit the same issues.

  2. Hi,

    Not yet. I’m wondering if some sort of permalink to the HTML would be enough. Perhaps with a link broker, https://bugster.forgerock.org/jira/browse/DOCS-83, on the server to redirect dynamically if the site layout ever changes.

  3. Nat

    Thanks for that, something to think about.

    I’ve also just applied to join the docbkx-tools google group, which I see you are active in. When you generate your pdf olinks, have you found that collectXrefTargets=only does not work, because it always tries to generate the PDF from the FO? The only way I have been able to get around this is to set collectXrefTargets=yes then ignore the PDF that is generated in this phase (and then generate it again after I have generated the xrefs for all of my books).

    • You are right. I set collectXrefTargets to yes for that reason as you have found, and then generate the PDF a second time to resolve the olinks. With the test working the way I wanted it to, the POM looks like this: https://github.com/markcraig/DOCS-47/blob/master/pom.xml

      Ultimately David Cramer’s solution looks like it will be better than just using docbkx-tools alone if you are also publishing HTML, https://github.com/rackerlabs/olink-maven-plugin. I don’t think he has implemented this quite yet, but he plans to have olinks in PDF that target other documents go to the HTML versions. This avoids broken relative links when someone only downloads a single PDF, or downloads all the PDFs but moves them around.

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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