Keyref breaks with peer topic, relative path, topic in sub-directory

[robander]

I've got a key definition with @scope="peer", linking to a topic with a relative path. I've also got a topic in a sub-directory.

When the key is referenced in a <reltable> and pushes a link into the subdirectory, the path is adjusted properly, link resolves. When the key is referenced directly from that topic, the link is not adjusted, and is broken.

To reproduce, add this to the end of hierarchy.ditamap:

<keydef keys="peerhtml" href="../peerdir/file.html" navtitle="peer html file in peerdir" scope="peer" format="html"/>
<keydef keys="peerdita" href="../peerdir/file.dita" navtitle="peer DITA file in peerdir" scope="peer" format="dita"/>
<reltable>
  <relrow>
    <relcell>
      <topicref href="tasks/garagetaskoverview.xml" type="concept"/>
    </relcell>
    <relcell>
      <topicref keyref="peerhtml"/>
      <topicref keyref="peerdita"/>
    </relcell>
  </relrow>
</reltable>

Then add this reference into tasks\garagetaskoverview.xml:

<related-links>
  <linklist>
    <title>links in the topic (broken paths)</title>
    <link keyref="peerdita"/>
    <link keyref="peerhtml"/>
  </linklist>
</related-links>

[drmacro]

What is your expectation for this type of peer reference to a topic? (or to an HTML file for that matter). Given that the spec through 1.3 does not really say what it means to make a peer reference (except now for peer references to maps in 1.3), I'm genuinely curious what the behavior is that you want or expect.

I'm not sure what I would expect in that case--a reference to a topic with no other context can only be interpreted as being part of the publication represented by the root map that contains the topicref to the topic, but "peer" suggests that the topic is not a first-class citizen of the publication. In that case, what is it? Is the topic rendered in isolation as a standalone publication? Is it treated as a provisional part of the current publication (since peerness tends to imply potential unavailability of the source file).

[robander]

If I have a local file reference, such as href="../otherdir/file.dita", and that reference is moved to another directory, the path is adjusted so that it remains valid. This happens whether that reference is moved around / generated based on map-based-linking or (in this case) keyref.

I expect that if I have a file reference with a relative path (even if @scope="peer" is used), the path will be adjusted in the same way. In the DITA-OT temp directory, after keys are resolved, where everything still reflects the original source directory organization, this means that (regardless of what directory my topics sit in) all uses of keyref="peerfile" still refer to the same resource.

How that ends up getting resolved likely differs based on your final output and assumptions made by your processor. Native DITA-OT to XHTML preserves file structure and naming, meaning I can generate a "publication" in one directory, using keys to address a topic that I know will be in a peer book in a peer directory. That's the real-world case we encountered; a publication tries to link to something like ../otherbook/overview.dita. The output generated in folder "thisbook" is a peer to "otherbook". Links generated by a reltable work - the key is resolved in the map, map-based-linking pushes the link into sub-directories, always adjusting so that the local path is consistent. Links generated directly in the topic are not adjusted based on directory, after which ../otherbook/overview.dita appears to reference a topic somewhere within the current publication.

Basic idea being - the relative-path reference should continue to resolve to the same resource, wherever the reference is moved. Arguably the same is true for local files referenced as @scope="external", though I have not seen a real-world case where that was a good idea. Then leave it up to the final rendering to figure out how to manage the peer link, as if it had been authored in the topic. Peer/external objects referenced using an absolute path couldn't / shouldn't be modified, because the reference is equally valid no matter where it ends up.

[shaneataylor]

I am seeing the same behavior for key references to non-DITA resources without using @scope='peer':

• key is defined in docs/samples/index.ditamap and points to docs/samples/example.xml
• the root map for processing is located in docs
• keyref in reltable correctly resolves path from docs/userguide/topic.dita to target as ../samples/example.xml
• keyrefs in <xref> and <coderef> elements in docs/userguide/topic.dita resolve incorrectly to samples/example.xml (effectively, docs/userguide/samples/example.xml)

Note: I see the same behavior whether the key is defined with @href="example.xml" or @href="../samples/example.xml"

[shaneataylor]

I believe org.dita.dost.module.KeyrefModule isn't correctly resolving the paths, but I don't have the Java-fu to fix it.

I suspect this step is meant to use the results of the earlier mapref relative path resolution (in the "mapref" target) but that seems not to be happening.

[stale]

This issue has been automatically marked as stale because it has not been updated recently. It will be closed soon if no further activity occurs. Thank you for your contributions.

[infotexture]

Fixed for 3.3 with #3234.