Pages: 1
Author Topic: Cross reference to a target element with ID works in PDF but not in Eclipse/HTML  (Read 6336 times)

Posts: 19

« on: July 25, 2011, 08:26:39 PM »

If I create a cross ref like this:


to a target like this:

<entry id="yyyy_Prop">YYYY Property</entry>

(with "entry" being a cell in a table) works in the PDF output, but not in either Webhelp or Eclipse HTML output.

In the PDF, the link goes right to that target id in the table, but in the HTML it just goes to the xxxx_properties.xml page, at the top of the page.

I created it by inserting a cross reference, selecting the target file, and then selecting that particular ID, which was offered as a choice if I selected "All" as the ID type in the link dialog box.

For the xref the format is set to "dita", the scope is set to "local", and the type is "topic".

Anyone know how to make this work for both PDF and Eclipse?

XMetal Author 6.0 with Render X XEP
Derek Read
Program Manager (XMetaL)

Posts: 2621

« Reply #1 on: July 26, 2011, 12:05:16 PM »

In order to get a browser to jump to a specific part in a document the HTML needs an "anchor" in addition to the link that is inserted for the <xref> itself. Anchors in HTML use the <a> element. The DITA Open Toolkit is generating links in the HTML properly, however, it is not inserting a corresponding <a> for the <td> element.

What needs to appear in the HTML output is something like the following (roughly the same as the other types of anchors the DITA OT generates for HTML output):

   <td><a name="topic2__yyyy_Prop"><!-- --></a>YYYY Property</td>

Note that I have simplified the HTML above for clarity. The DITA OT actually puts in a lot more attributes.

The simplest workaround I can think of that requires making no modifications to the DITA OT is to:
  1. Wrap the contents of the <entry> inside another element that the DITA OT does insert an anchor for when linked to.
      This includes <p>. So you will then have this type of content:
      <entry><p id="yyyy_Prop">YYYY Property</p></entry>
  2. Create the xref so that it points to the <p>.

The proper fix (to support your xrefs as written) would be to modify the DITA OT so that it does insert <a name="someID"> elements when you link to a table <entry> element. You may wish to submit a request for this to the DITA OT project at SourceForge. Note that in my testing it seems that some browsers (notably FireFox) will not take you to an anchor located directly inside a <tr>, only inside a <td>. This is relevant because for all other elements the DITA OT's logic is to place the <a> just before the opening tag of the element being linked to, in this case before the <td> (not inside the <td>). That would result in an anchor that would not work for some browsers. I think a special case would need to be made in the DITA OT so that such an anchor is inserted inside the <td>.

I have not tested this with Eclipse, but since it ultimately consumes HTML as well the issue must be similar.
« Last Edit: July 26, 2011, 12:10:37 PM by Derek Read » Logged

Posts: 19

« Reply #2 on: July 26, 2011, 12:31:06 PM »

Thanks for that, I had just discovered that wrapping the table text in a <p> </p> tag does in fact create a link that works in both PDF and HTML output, but your more detailed explanation about why is very useful.

One little thing that threw me off is that at the start of this I did have the entries in paragraphs, as in <entry><p> text here </p> </entry>, but when I selected the <p> element and assigned the ID there, it assigned the ID to the entry, not the paragraph.

Which makes sense, since it's going to assign the ID to whatever element your cursor is in when you add the ID. To assign the ID to the paragraph you have to just put the cursor inside of it, because if you select it, you're really located in the <entry> tag instead. I was changing the code by hand to move the id from the <entry> tags into the <p> tags, until I realized that.

I guess what you describe could be the ultimate fix, but for me just telling everyone that we have to put table entries inside of paragraph tags, and the right way to assign the ID, seems close enough.

This does all work in Eclipse by the way which as you say is really just HTML, and it works with Chrome and Firefox, takes me right to the specific table cell.

Thanks again,
Pages: 1
Jump to:  

email us