Workspace to enhance cross-referencing
Introduction
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.
- We are working out the requirements for cross referencing to exhibits here: http://dita.xml.org/forum/requirements-thread-xref
-
We flesh out how to specify a solution which meets the requirements here: http://dita.xml.org/forum/specification-strategies-thread-xref-text-cont...
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.
Concepts
Once we start reaching consensus in the forum discussions, we can start populating this section.
Research
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.
Search
Recent Content
- Forum for DITA Users
35 weeks ago - Publishing for DITA
5 years ago - Optimizing the DITA Authoring Experience — Online Course
5 years ago - Linking to another chunked topic
5 years ago - Advanced Reuse Strategies — Online Course
5 years ago - 2019 Content Management Strategies/DITA North America Conference
5 years ago
Subscribe
Scope?
I'm going to second Deborah's comments in some of the subthreads, with some more specifics:
Michael Priestley
The Intent
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.
Is it just output behaviors?
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:
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
PS
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