Re: [dita] Scenario for cross-deliverable referencing

[Michael Priestley <mpriestl@ca.ibm.com>]

Hi Eliot,

I believed your scenario was covered
in my case of multiple chapters being produced as separate PDFs.

In that scenario, the author of Map
A does not define a key that references a key defined in map B - they simply
include map B's definition of map B's keys, after it has gone through processing
to produce a deliverable-specific version of that key definition.

I believe my scenario shows how cross-deliverable
referencing could work without using map-specific addressing. I believe
map-specific addressing is problematic because it doesn't actually tell
us what the deliverable-specific address will be. You assume some automated
process that will allow automatic association - but I believe that is too
large an assumption to make. If I am addressing content from a deliverable
produced by another team, we would all have to agree on that automatic
processing rule - which requires upfront coordination even greater than
that required to ensure unique keys.

The only time we can know what a deliverable's
addressing scheme will be (ie what the hrefs should resolve to) is when
the deliverable is built. That's why I have a deliverable-specific map
being built as part of the deliverable build, which can then be incorporated
into the keyspace for other deliverables to enable cross-deliverable links
for a given set of deliverables.

Michael Priestley, Senior Technical
Staff Member (STSM)
Lead IBM DITA Architect 
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25

From:	Eliot Kimber <ekimber@reallysi.com>
To:	Michael Priestley/Toronto/IBM@IBMCA, dita <dita@lists.oasis-open.org>
Date:	09/06/2011 11:01 AM
Subject:	Re: [dita] Scenario for cross-deliverable referencing

---

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


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php