What’s the right link for the job?!?

[Zearin]

Okay. So, I have a DocBook project. It’s a single book. XInclude is used. The DocBook source is contained in a shallow directory hierarchy (2 levels deep at maximum).

The target output is a small XHTML5 (chunked) website.

The content consists of a bunch of design patterns. They are organized into categories (directories), and there are lots of references between them. (E.g., “This pattern is a variation on «some other pattern»...”.)

I am having an astonishingly difficult time linking these documents together. I want the link text to be generated. I also want the generated text to come from the target document’s title. And I really, really don’t want to have to go through all my documents and add @xml:ids to everything. (I will, if I have to. But...it's 2013. I think software should be able to handle a simple use case like grabbing the target’s title by now. )

I’ve been checking and re-checking DocBook XSL: The Complete Guide and DocBook 5: The Definitive Guide.

From DocBook 5: TDG, the link element is described as “the semantic equivalent of HTML’s <a href="...">...</a>.” I want these links’ text to be generated, so I think link isn’t what I’m looking for.

From reading both of the above sources, the semantics of xref suggest that it’s only intended for linking within a document.

From DocBook XSL: TCG, this table of linking examples suggests that olink is what I’m looking for.

So I tried it...

...and Oxygen is giving me a validation error.

• Problem #1: Validation. According to Norm’s TDG, I’m pretty sure that I shouldn’t be getting any error because of this. The olink's position is /section/section/para/olink, and para is listed as a possible parent of olink.
• Problem #2: WTF is the correct way to link??? I love the richness of DocBook’s grammar. But I’m taken aback that after spending half of my day trying to accomplish a (conceptually) very simple task, I still can’t figure it out. (I understand that DocBook 5 carries some older linking attributes in addition to the XLink attributes, but that’s not the part that is confusing the hell out of me. Why are there so many different link elements? Why is figuring out the correct one to choose such a chore? *grr*...)

[sorin_ristache]

Hi Zearin,

I think xref would be the correct linking element for you. Because you group the XML files together in one book the title cannot be extracted automatically at the xref insertion location. This will be available in one of the next versions of Oxygen, maybe even in 15.1 (the next version), when we plan to extend the Master Files support to XML files. This Master Files support will detect the XML file which includes all the other ones using XInclude (in your case the XML file with the <book> element) and will allow linking between the different modules by starting to parse from the master XML file and detecting all the possible link targets and listing them in the dialog box for inserting a link in Author editing mode, when the toolbar button Cross reference (xref) is called in a Docbook file.

Anyway you cannot avoid marking all the possible link target modules by adding the xml:id attribute (in Docbook 5.0) on the parent element of title (section, chapter, etc). This is necessary because the title that is extracted automatically from the target module for the link (section, chapter, etc) and is inserted at the location of the link element (xref) needs to also be updated automatically when the title is changed in the target section or chapter. Otherwise it would be just a static text, a result of a one-time extraction processing which would not be updated when the target section title is modified.

So unfortunately the automatic extraction of the target section title and insertion of this title at the location of the link is not implemented yet in a Docbook document. This feature is already available in Oxygen only for DITA bookmaps but I guess that does not help you.


Regards,
Sorin

[Zearin]

Hi Zearin,

Hi Sorin!

I think xref would be the correct linking element for you.

If that’s what will work, I’ll use it.

However, isn’t this somewhat in contradiction of its semantic purpose? (I don’t mean to be difficult. It’s just important to me to know when I am using something for its intended purpose, and when I’m deviating from its intended purpose—and why I’m doing so.)

Because you group the XML files together in one book the title cannot be extracted automatically at the xref insertion location. This will be available in one of the next versions of Oxygen, maybe even in 15.1 (the next version), when we plan to extend the Master Files support to XML files. This Master Files support will detect the XML file which includes all the other ones using XInclude (in your case the XML file with the <book> element) and will allow linking between the different modules by starting to parse from the master XML file and detecting all the possible link targets and listing them in the dialog box for inserting a link in Author editing mode, when the toolbar button Cross reference (xref) is called in a Docbook file.

Okay. I’ll keep an eye on that.

I remember when Master Files support came out, and when I read about what it would do, I was very excited for the functionality. But I haven’t really used it much yet, so I’m not as familiar with its benefits as I would like.

Perhaps it’s time I start.

Anyway you cannot avoid marking all the possible link target modules by adding the xml:id attribute (in Docbook 5.0) on the parent element of title (section, chapter, etc). This is necessary because the title that is extracted automatically from the target module for the link (section, chapter, etc) and is inserted at the location of the link element (xref) needs to also be updated automatically when the title is changed in the target section or chapter.

...Right, but I’m still not sure why that requires an @xml:id. Am I writing the markup as if the XIncludes have already been processed?

(If so, that’s been a major part of my confusion. Knowing the answer to this will probably really help.)

Otherwise it would be just a static text, a result of a one-time extraction processing which would not be updated when the target section title is modified.

So unfortunately the automatic extraction of the target section title and insertion of this title at the location of the link is not implemented yet in a Docbook document.

By “not implemented yet in a Docbook document”, are you referring to functionality provided by the DocBook XSL library, or further enhancements provided by Oxygen itself?

This feature is already available in Oxygen only for DITA bookmaps but I guess that does not help you.

That’s okay. I know I asked a lot of questions in this post, but your reply is still quite helpful!

Thanks very much.

—Zearin

[sorin_ristache]

Hi,

However, isn’t this somewhat in contradiction of its semantic purpose? (I don’t mean to be difficult. It’s just important to me to know when I am using something for its intended purpose, and when I’m deviating from its intended purpose—and why I’m doing so.)

The xref element is used for links in the same document. You want to link to other module, included in the same document with XInclude, but that does not make the module external to the document. It is still the same Docbook document.

...Right, but I’m still not sure why that requires an @xml:id. Am I writing the markup as if the XIncludes have already been processed?

(If so, that’s been a major part of my confusion. Knowing the answer to this will probably really help.)

It requires an ID value because that is the requirement for the xref/@linkend values. In Docbook 5 I think the only attribute for adding an ID value is xml:id.

You are writing the markup as if you are editing one Docbook document. This is what an XML tool should do for you: help you see all the modules integrated as one single document and allow you to link between modules without caring when the XInclude elements are processed, because that is what you will get as the output of a Docbook transformation: one document with all modules integrated. As I said that is already available in Oxygen for inserting links in DITA topics (grouped in a single document by a DITA map) but not yet for inserting links in Docbook modules (grouped in a document with XInclude elements).

By “not implemented yet in a Docbook document”, are you referring to functionality provided by the DocBook XSL library, or further enhancements provided by Oxygen itself?

I mean not implemented in Oxygen yet. Linking between modules when editing the modules and extracting automatically the title of the target module for inserting it at the location of the link is a feature of the editor tool (Oxygen XML Editor in our case), not a feature of the Docbook XSL stylesheets. The XSL stylesheets only take care of the generation of the output format (PDF, XHTML, Webhelp, etc).


Regards,
Sorin

[Zearin]

The xref element is used for links in the same document. You want to link to other module, included in the same document with XInclude, but that does not make the module external to the document. It is still the same Docbook document.

You are writing the markup as if you are editing one Docbook document. This is what an XML tool should do for you: help you see all the modules integrated as one single document and allow you to link between modules without caring when the XInclude elements are processed, because that is what you will get as the output of a Docbook transformation: one document with all modules integrated. As I said that is already available in Oxygen for inserting links in DITA topics (grouped in a single document by a DITA map) but not yet for inserting links in Docbook modules (grouped in a document with XInclude elements).

Ahhhh. Okay. I finally get it.

One last follow-up question:

Is it possible to deliberately NOT include certain Docbook modules in order to keep them “separate”? (That is, even though they are part of the same book, they aren’t included, and require a link—just as navigating from one page of a website to another requires following a link, even though they are part of the same overall website.)

[sorin_ristache]

Hi,

That is decided by linking a module or not into the main file (the file containing the root <book> element) using XInclude. If a module is not linked in the main file using XInclude then it is separate, otherwise it is part of the document.


Regards,
Sorin

[John_Tait]

I found the answers really helpful here. The DocBook 5 documentation is excellent, but it covers a number of legacy cases. I had the same problem with choosing how to build modular documents and cross-reference the modules.

Using

Code: Select all

<xref linkend="foo">

with

Code: Select all

<element xml:id="foo"> 

and a document constructed with Xinclude works really well and it's simple.

John

[sorin_ristache]

Hi John,

The Master Files support is surely helpful in such cases. You may find this video demo helpful too Please let us know if you encounter errors or difficulties in using that.


Regards,
Sorin

[John_Tait]

Thanks. The Master Files works really well - I'm using a "set" as the top level. I can just pick the cross-references from a list. It's "invisible" to me if where the actual xincluded file is.

DocBook 5 now appears to work as well as DITA for me for producing modular documentation. The chunked HTML output is very nice.

A smaller question: is there a reason why "set" isn't included under Framework Templates/DocBook 5?

It wasn't a big deal becuse I just modified another template, but I did expect to find "set" in there.

John

[sorin_ristache]

Hi John,

I think the set element is not used too much in Docbook documents. We will probably add a template for new Docbook set documents in a future version.


Regards,
Sorin