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

Support key based linking from phrase-like elements #2961

merged 1 commit into from May 17, 2018


3 participants

robander commented May 14, 2018

Signed-off-by: Robert D Anderson


Adds support for key based linking in PDF to phrase like elements that currently ignore the link.

Currently, a key resolves to a link target on keyword, xref, or term, the generated PDF uses that link.

The following elements will pick up key text, but the link is ignored:

  • <cite>
  • <ph>
  • <dt>
  • programming domain specializations with custom processing: pr-d: option, parmname, apiname, pt
  • software domain specializations with custom processing: msgnum, cmdname, varname
  • UI domain specializations with custom processing: uicontrol, wintitle

The <keyword> element in 3.0 uses logic to determine if key based links are present, and if so whether to use specified link text or grab it from a local target. If there is a link, this results in <fo:basic-link>, otherwise it results in <fo:inline>.

The proposed solution here moves that processing into a mode template so that it can be reused. Attributes are passed in with $copyAttributes; all appropriate attribute sets for these inline elements onto are placed onto <fo:inline>, which is passed in with that variable, and any passed attributes are then added to the link or inline element. This means all current styles are preserved.

In addition, topicmerge had to be updated to allow for @href on ph, cite, and dt, otherwise @href values that resolve to local DITA topics are left with generated DITA topic names rather than using internal IDs in the merged file.

Motivation and Context

Originally reported by one of my customers, who was using <cite keyref="target"> to create a citation, but was not getting a link. I tried adding @keyref to a few more elements when testing, and realized it only worked for a few elements today. I extended the test to cover all of the phrase-like elements that might include a link with the key, as shown in the test case below.

How Has This Been Tested?

Unit / integration tests pass, but that is expected because there is minimal testing for the merged / FO output.

Test case includes the following elements, which covers most phrase-like elements that take keyref; I think the only one I left out was menucascade because that's just a container for uicontrol elements that are now processed correctly.

Type of Changes

Really a bug fix because this should always have worked, but treating it as a feature because it was a hole in core PDF functionality.

@robander robander self-assigned this May 14, 2018

@robander robander added this to To Do in 3.1 via automation May 14, 2018

@robander robander moved this from To Do to Review in 3.1 May 15, 2018


This comment has been minimized.


raducoravu commented May 15, 2018

This also looks like it could solve:


This comment has been minimized.


robander commented May 15, 2018

@raducoravu yes, that looks like the issue.

I started working on the issue as soon as my own customers reported it with <cite> and didn't look through the backlog to see related issues. I don't see any other duplicates now (but that's expected as I think you'd have looked for them before opening 2025).


jelovirt requested changes May 17, 2018 edited

Generally speaking I don't like that add another layer of indirection to inline element processing, but this makes implementing linking elements easier.

<xsl:apply-templates select="." mode="inlineTextOptionalKeyref">
<xsl:with-param name="copyAttributes" as="element()?"><fo:inline xsl:use-attribute-sets="option"/></xsl:with-param>

This comment has been minimized.


jelovirt May 17, 2018


Type should element() as this will always have that element. Same for there cases that have this same issue.

This comment has been minimized.


jelovirt May 17, 2018


I wonder if it would be clearer if the element we used to pass the attributes was e.g.

<wrapper xsl:use-attribute-sets="option"/>

or something that's not a DITA or FO element.

Support key based linking from phrase-like elements
Signed-off-by: Robert D Anderson <>

@robander robander merged commit a016bb8 into dita-ot:develop May 17, 2018

2 checks passed

DCO All commits have a DCO sign-off from the author
continuous-integration/travis-ci/pr The Travis CI build passed

3.1 automation moved this from Review to Done May 17, 2018

@robander robander deleted the robander:feature/linkcite branch May 17, 2018

@robander robander added this to the Next milestone May 17, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment