What’s the right link for the job?!?
Posted: Fri Jul 12, 2013 11:53 pm
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.
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*...)