Page 1 of 1

Cross-referencing tables in the same topic

Posted: Mon Aug 21, 2017 7:52 pm
by Exotic Hadron
Howdy,

I am trying to create a cross-reference to a table listed in the same topic where I create the reference.

The cross-reference code looks as:

Code: Select all



<p><note>Parameters support full paths and paths relative to the command line tool. For more information about the <codeph>CODE</codeph> parameter, see table <xref href="#table_yhb_3kr_w1b" type="table"/></note></p>
The referenced table looks as:

Code: Select all



<table frame="all" rowsep="1" colsep="1" id="table_yhb_3kr_w1b">
<title>Coding params</title>
<tgroup cols="2" align="left">
...

At build time, I get this error:

Engine name: DITA-OT
Severity: error
Description: [DOTX032E]: Unable to retrieve link text from target: '#table_yhb_3kr_w1b'. If the target is not accessible at build time, or does not have a title, provide the link text inside the reference. The location of this problem was at (File = C:\Users\EH\AppData\Local\Temp\OxygenXMLTemp\ditaTemporaryOutputDir-1503333277382\t1\t2\t3\t4\t5\reference\d\topics\tasks\source_code
The Cross-referencing tables article here says:
Cross-references to tables are accomplished with the xref element with a type attribute of table
...
You cannot cross-reference simple tables, partly because they do not have titles (necessary for labelling the table with a table number.)
My table, however, has a title.

The article also provides an example:

An example of the syntax of a cross-reference to a table with an id attribute of "table_perf_data" in the same topic is:
<xref href="#concept_ej25_perf/table_perf_data" type="table"/>
Besides the ID attribute, the example also references something named as concept_ej25_perf/. It's unclear from the article, what's that? A title? A topic name?

Important note:
When editing in Author mode, the reference is rendered without any problems. I see the link to the referenced table (Oxygen automatically substitutes the referenced ID with the title), and this link is also clickable.

However, after transforming this to a PDF, I get the error above, and the link to the table is rendered as:
see table #unique_170
What am I doing wrong?

Thank you.

Re: Cross-referencing tables in the same topic

Posted: Tue Aug 22, 2017 8:14 am
by Radu
Hi,

In general an xref @href has the format:

Code: Select all

<xref href="path/to/target.dita#topicID/elementID"/>
where the "topicID" is the value of the @id attribute set on the top level root element (usually <topic>, <task>, <concept> or so on).

When referencing in the same file you also need the topic ID:

Code: Select all

<xref href="#topicID/elementID"/>
With the new DITA 1.3 standard which was released about a year ago there is an alternative way of doing a reference in the same document:

Code: Select all

<xref href="#./elementID"/>
but the old one still works.
Basically if you are using DITA OT 2.x for publishing (you can check this out in the Oxygen Preferences->DITA page) you can also use the new DITA 1.3 notation.

Actually the DITA 1.3 specs has a table with lots of reference examples:

https://www.oxygenxml.com/dita/1.3/spec ... ssing.html

About this remark:
When editing in Author mode, the reference is rendered without any problems. I see the link to the referenced table (Oxygen automatically substitutes the referenced ID with the title), and this link is also clickable.
Possibly our link resolution is too permissive, I will try to reproduce this behavior with the latest Oxygen XML Editor 19.0 and if it still exists, we'll fix it.
Also as a best practice instead of manually adding the links you can open the topic in Oxygen in the Author visual editing mode and use our toolbar actions to insert cross references. They always set the proper syntax for the link.

Regards,
Radu