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

I think we are talking at cross purposes.

You are proposing a process that requires an *author* to explicitly include
the intermediate process of a particular rendition process. That is simply
not an acceptable solution because it mixes the domain of authoring (what's
in the content I have and reasonably know about) and the domain of
processing, which is, in the general case, unknowable to authors. I cannot
accept any such solution. My requirement is that the content *as authored*
convey all the information required to express authorial intent and to
enable any processor to do the right thing given access to the content
involved, without recourse to any particular implementation approach. Your
solution does not do that in any way that I can see.

That is, saying "the map author includes an map generated by a rendition
process" is simply not going to work in the general case because not all
processors would generate a map that couple be so included, even if it was
sensible to define the authoring in that way. Doing so would be to mandate a
particular implementation approach.

In my scenario I am creating a map for a specific publication, which
represents an invariant unit of publishing *to one or more rendition types*.
That is, the map is be published to PDF or HTML or EPUB or something as yet
uninvented but each of those renditions will reflect the same content
(ignoring conditional processing).

The author *of a topic* references some target by key. At the time they
author the reference to the key they can't know or care where the ultimate
target of the key might be in the content as authored or in the content as
rendered, for the simple reason that it is unknowable at authoring time.

If they are authoring in the context of a specific map then of course they
can know where the key resolves in the context of that map, but if they are
authoring the topic outside of a map context then they are simply stating
the requirement that there needs to be something at the end of the key in
whatever contexts that topic is used. But they cannot know all the possible
maps the topic might be used by in the future.

The author *of a map* that uses the topic has the responsibility of binding
the key to a resource. If the resource is in the same map, then no problem,
they just create a normal key reference and they're done.

But if the resource is *not* in the same map, *there is nothing they can do
today to indicate their intent to reference a resource in a different map*.

They *do not want* to directly address a thing in a non-DITA rendition of
the publication, for the simple reason that they want the link to work in
all possible renditions and because they, as the author of the map, can't
know the details of the renditions that might come later.

Including the map for a particular rendition of the target map doesn't solve
the problem precisely because it is rendition specific, but the intent is
not rendition specific, it is publication-as-authored specific. That is, the
map author is saying "the target topic is in this other publication,
represented by this other map, regardless of where that map is rendered."

That is my whole point: neither the author of the topic nor the author of
the map can know anything about any potential renditions of the two
publications (root maps) involved. They can only know about the maps *as

A production system *can* know about the maps as rendered, *because it's
rendering them*. It can know what rendition-specific addresses a thing as
authored gets as rendered for a specific rendition. It can know that either
because it did the rendition and remembered the result, however it remembers
it, or because it has a deterministic algorithm for mapping input locations
to result addresses, meaning it can predict what the address as rendered
will be. It knows where the rendered results will be published relative to
each other, so it can construct appropriate relative URIs if necessary.

The DITA standard already defines unambiguous key scopes, namely the root
maps that define key spaces. There is no ambiguity about that. That means
that addressing a root map *as a root map* allows you to address keys in
that key space without having to coordinate key names across key spaces.

The *only thing* we lack is the fragment identifier syntax to distinguish a
normal element ID reference from a key reference.



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

> 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 <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>
>> <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

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