Bug 816794

As part of this we should also ensure that the fixed urls ignore XML elements when being created.

There was discussion about using markup in titles a few years ago (can't find it in the archive), and the conclusion was that it should not be done.

You can't do conditional markup in xref text via Docbook xsl:

http://www.sagehill.net/docbookxsl/CustomXrefs.html

"The mechanism of using gentext templates to generate cross references has one big limitation. The generated text is specified using an attribute in a l:template element in a localization file. An attribute value cannot contain element markup, nor can it alter the cross reference behavior under different contexts."


You can do things to *all* xrefs via xsl customization, but you can't do something to individual xrefs, or arbitarary elements of xrefs, from within the Docbook xml.

So to achieve this you'd have to manipulate the HTML post-publican build, or build with something other than publican.

I believe you've misunderstood something here Josh (or maybe I am). It's not about putting xml elements in xrefs linkend attribute (which is what the link your talking about does). It's about rendering content in the title correctly which is pointed to by a xref. An example of this working can be found at: http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/6/html-single/Beta_Documentation/index.html#About_JAXWS_Web_Services-1

The issue with this bug is that we use a ulink and then create a DOM Text Node as the contents of the ulink (see below for an example). Anything in this text node is then assumed to be pure text when this isn't the case. If you want to see more have a look at the createRelatedTopicULink() method in the DocbookUtils class, that's where the error lies.

<ulink url="http://localhost:8080/TopicIndex/Topic.seam?topicTopicId=1322&selectedTab=Rendered+View">
    "Some <literal>Title</literal>"
</ulink>

As you can see above this has nothing to do with what that link you provided was discussing.

Just for more reference here is an example of what your link was talking about: <xref linked="Some <literal>Hello</literal>" />

I think it's a little bit of both.... :-)

I couldn't find the createRelatedTopicULink() function here: https://github.com/mcasperson/Common-utilities/blob/master/src/main/java/com/redhat/ecs/commonutils/DocBookUtilities.java

Am I looking in the right place? 

You can safely ignore the relevance of the link I posted to this bug, because, if I understand it right, the XREF referred to in the bug title is actually "an internal link implemented using the Docbook <ulink> element".

The example you gave at the end is not accurate. Linkend in <xref> is the id attribute of an element, rather than link text. The link text is generated by dereferencing the id and grabbing the title element.

That Docbook page explains you can't do what you're doing if you use <xref> and the Docbook stylesheets, because the link text is generated as pure text:

"Perhaps you want to change the typographical style for the generated text of a cross reference....You might think the gentext templates would let you customize the style, but they do not. The gentext templates specify text in attributes, and attributes are not permitted to have elements in XML. So you cannot wrap the gentext in HTML or FO elements for formatting."

Note that "attributes" here does not refer to the linkend attribute of the <xref> - that attribute is assigned the id of the target; what it refers to is a little further up the page:

"The generated text is specified using an attribute in a l:template element in a localization file. "

Using <ulink> is a clever way around this limitation.

I take it back, with apologies, after running some tests.

<xref> does actually pull markup embedded in the title element.

and the gentext that the doc refers to is the "Section" and "Chapter" generated text that is added to the element title, rather than the title itself.

It looks like you can turn off the "Section" and "Chapter" gentext (and the X.Y.Z numbers) by using <xref xrefstyle="select:title" linkend="some_id"/>

Sorry for the digression in the bug.

Okay cool and thanks for the extra info. With the xref, I just wrote anything just to try and display what I was talking about.

And btw you had the wrong class. Here is the right one:

https://github.com/mcasperson/Common-utilities/blob/master/src/main/java/com/redhat/ecs/services/docbookcompiling/DocbookUtils.java

Fixed in the repo.

Cause:

The cause of this is because the title was being added as a TextNode which forces all of the text inside to be parsed as text. This is done with in the DocbookUtils.createRelatedTopicULink() method.

Consequence:

The elements in the titles were being processed as plain text when they should have been parsed as XML Elements. The result can be seen from Misty's example in Comment #1.

Fix:

Parse the title as XML using the DocumentBuilder class. Then move all the nodes from that parsed Document into the ulink Element object. If the XML transform fails then just process it as plain text in the format that is already in place.

See Bug #840700 for details regarding removing the XML from fixed urls.

Released in Build 20120817-1046.