Workspace to enhance cross-referencing


This page serves as a top level resource for the discussion, design, and research related to the enhancement of cross-referencing in DITA.  Most of the actual work takes place on the pages linked to by this article.

Forum Threads

The forum threads related to cross referencing are all placed in the Specializations board. These threads represent the discussion from which the final products are born.

Wiki Pages

Wiki pages are useful when a single articulation of an idea needs to be developed and/or used by many people.  These pages represent distilled articulations of the concepts embedded in the discussion on the forums.  These pages also contain research into how other architectures solve the same problem.


Once we start reaching consensus in the forum discussions, we can start populating this section.


In this area, we collect information which informs our design.  These are for reference, so that we do not re-invent the wheel.  We do not expect to use any of these solutions verbatim.

I'm going to second Deborah's comments in some of the subthreads, with some more specifics:

  • if you're talking about a specialization for eg figref or tableref, that will include some specific support for handling numbering issues in aggregated outputs like PDF, say so
  • right now it sounds as if you're planning to redesign xref from scratch, including adding new attributes, new behaviors, and replacing its existing capabilities for local text definition with something radically different still to be defined.
  • if it really is the latter, then you need to be doing the work through the TC - what you're doing right now sounds like it's an official DITA design activity, but it isn't. I'll also agree with Deborah that, at the TC level, you'd meet a lot of resistance. Most people I work with do not use xref to point to exhibits at all, and the changes you seem to be proposing fly counter to a bunch of existing usage patterns.

Michael Priestley

You're not asking about scope, you're asking about approach.  

My scope is that I want a standard way to reference a handful of already standardized elements.  I want to focus on tables and figures, right behind them are steps and <li>s within <ol>s. Maybe numbered paragraphs too, but I have very little use for that. 

I would imagine that most authors using DITA are bending over backwards to avoid using xref with an exhibit target, for precisely the reasons I'm here: xref is an unconstrained wildcard in the middle of a sentence.   I can write a sentence around any fixed target, but I can't handle that.  The real question is: would those same people still refrain from referencing their exhibits if an adequately specified reference mechanism were available to them?

I started out dancing around the issue, but it's been a year now and it's really getting in the way.  I am one of those people who adopts a promising new technology in the hopes that the major bugs will get ironed out, particularly if it's already at 90% of what I need.

We're deciding what the approach is.  You see, the problem with a failure to specify is that the standard does not get all players on the same page.  Within a day, there were three divergent approaches to solve the same problem, none of which are preferred by the standard. In this context, this is beyond horrible.  It strikes so deeply that a lead player on the reference implementation believes that the element specified to be the orthodox implementation of this task should never appear in  authors' documents. Certainly I get the opposite impression from reading the text of the standard.

Regardless of the approach, my intent is to prepare a proposal (or at least a proposal outline) for submission to the TC.  Whatever changes is going to be an existing element.  I have zero interest in going through all this work just to come up with a completely noninteroperable solution.  None. I've also spent far more time on this than I really should be, and I certainly cannot justify becoming a member of the TC to my boss.  We just need figure references to work predictably.



Right now, you can override any generated xref text by specifying it locally (within the xref).

Generally speaking, I would think the issues of generated text that interferes with a sentence comes up only in PDF or printed output (in online output, you'd just link based on the target's title or locally defined xref text). The possible generated text would be:

  • type of target (eg figure, table, step)
  • number of target (if doing figure numbering etc.) 
  • title of target (eg figure title)
  • page number

 eg See figure 19 "a little figure" on page 126.

 I'm guessing there would be a number of issues to be solved in a design, including translation. But assuming these could be solved, you're looking for a set of recommended behaviors for printed output per target type.

Is that right? If it is, you could write up your desired behaviors for discussion, and ultimately submit them to the TC as suggestions. If the TC accepts them, it would be up to the TC to determine how to implement (if any changes are required other than recommending output choices to consuming processors). 

Michael Priestley

I've been reviewing the discussion in the requirements thread, and I think I get it now: a combo of defined output, plus per-element control over level of output, plus per-deliverable control over what gets numbered and what doesn't.

I could easily see this as a potential enhancement to bookmap and maybe a related domain (so: potential modifications to existing specializations in the DITA spec, but not changes to the core behavior).

On my part, I'd welcome a requirement to the TC to add specialized support for these scenarios. The more complete and descriptive your scenarios are the better. However, I don't think it would be a good idea to over-specify the implementation. The TC has a lot of folks who are immersed in the spec and concerned with things like consistent approaches, element names, etc. that are unlikely to come up as issues for your design. And there's a limit to how much TC folks can participate in design activities outside of the TC (a limit defined both by available time and by OASIS policy).

Michael Priestley Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I