Re: [dita] Scenario for cross-deliverable referencing

[Eliot Kimber <ekimber@reallysi.com>]

Unless I'm misunderstanding, this doesn't address my scenario at all.

Given two root maps Map A and Map B, each to be produced as a separate
standalone PDF, the question is:

How does an author of Map A define a key that references a key defined in
Map B's key space? E.g., I define key "key-x-in-map-B" and then author a
reference to that key from some topic used in Map A, e.g.: <xref
keyref="key-x-in-map-B">X in B</xref>.

To process this, the processor has to know what a reference to a specific
key name becomes in the rendered output so that the rendition contains a
working link from the PDF for Map A to the PDF for Map B. There's lots of
ways to implement this, but the most obvious is to have some deterministic
processor that always produces the same result for a given key name/key
space pair so that the processor of Map A can blindly generate references in
Map A's PDF to the eventual corresponding anchors in Map B's PDF.

This might require a run-time parameter that specifies the delivery location
of the two PDFs so that if relative URLs are to be constructed, they can be
constructed reliably.

But the essential bit here is having the key definition *as authored* be an
unambiguous reference to a key in the scope of Map B's key space. I don't
see that we have a way to do that in DITA 1.2.

Note that the only thing I'm concerned with is the markup in the content as
authored--given an unambiguous address, the processing implementation is an
exercise in engineering and is uninteresting. If there is no unambiguous
address then there is no generalized processing that will work except by
accident or unenforceable convention.

In particular, it *cannot be correct* to author the key definition in this
scenario where the URL is to the resource *as rendered*. It must be to the
resource *as authored*. That is a fundamental requirement because without
that, you cannot have generic content to which any processing may be applied
with consistent and predictable results.

As an author I want to say "I am linking to this *content* thing in this
other publication" and I want links to that thing to work correctly in all
possible renditions. "Work correctly" is rendition dependent, but the
author's intent and their markup is rendition independent.

Cheers,

E. 


On 9/6/11 9:19 AM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote:

> 
> This was my todo from last week's mtg - sorry I'm leaving it to the wire.
> 
> This describes a solution that can be implemented today - I still think there
> more work to be done, including:
> 
> -  a general solution for key scoping (but not deliverable-based scoping since
> the boundaries of deliverables are mutable, as I'm trying to show here).
> - a standardized approach for cross-deliverable referencing - if we want to
> encourage this approach, for example, or propose an alternative - but we
> should be providing some guidance to vendors on how to implement so that the
> solution is cross-vendor compatible
> 
> scenario: 
> - we need to produce PDFs for each chapter of a book, as well as a single big
> PDF that contains all chapters
> - the chapters contain cross-references to content in other chapters, which
> needs to be resolved as a cross-deliverable link in the single-chapter PDFs
> but as a local link in the single big PDF case
> - each chapter is represented by a separate map
> - each topicref in the map has a uniquely addressable key (using whatever
> general scoping mechanism we choose to implement)
> - the book as a whole is represented by a master map that pulls in the others
> 
> solution for individual chapter case:
> - for each chapter, execute a partial PDF build, which does not transform the
> content but does preprocess the map to turn each topicref href into a form
> appropriate for the deliverable being produced (ie, including the filename of
> the PDF being produced, with appropriate anchor syntax)
>         this results in a deliverable-specific set of key mappings
> - for each chapter, create a master map that includes the chapter being built
> and then resource-only inclusions of the deliverable-specific maps for all
> other chapters 
> - for each chapter's master map, execute a full PDF build
>         this results in a chapter-level PDF with all links to other chapter
> resolved correctly
> 
> solution for whole book case:
> - build normally 
> 
> Michael Priestley, Senior Technical Staff Member (STSM)
> Lead IBM DITA Architect
> mpriestl@ca.ibm.com
> http://dita.xml.org/blog/25 <http://dita.xml.org/blog/25>

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com