OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [dita] Scenario for cross-deliverable referencing

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

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.



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

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:

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]