Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
robander opened this issue Jun 24, 2015 · 6 comments

Comments

Projects
5 participants
@robander
Copy link
Member

commented Jun 24, 2015

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

This comment has been minimized.

Copy link
Member

commented Jun 24, 2015

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

This comment has been minimized.

Copy link
Member Author

commented Jun 24, 2015

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

This comment has been minimized.

Copy link
Contributor

commented Jan 25, 2016

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

This comment has been minimized.

Copy link
Contributor

commented Jan 26, 2016

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 comment has been minimized.

Copy link

commented Dec 12, 2018

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.

@stale stale bot added the stale label Dec 12, 2018

@stale stale bot closed this Dec 26, 2018

robander added a commit to robander/dita-ot that referenced this issue Feb 21, 2019

Test for conditions in dita-ot#2620 dita-ot#2581 dita-ot#2250 dita-ot…
…#1951

Signed-off-by: Robert D Anderson <robander@us.ibm.com>

@infotexture infotexture added this to To do in 3.3 via automation Feb 26, 2019

@infotexture infotexture added this to the 3.3 milestone Feb 26, 2019

@infotexture

This comment has been minimized.

Copy link
Member

commented Feb 26, 2019

Fixed for 3.3 with #3234.

@infotexture infotexture moved this from To do to Needs review in 3.3 Feb 26, 2019

@infotexture infotexture moved this from Needs review to Done in 3.3 Feb 26, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.