| [Thread Prev]
| [Thread Next]
| [Date Next]
| [Thread Index]
| [List Home]
Subject: Re: [dita] Scenario for cross-deliverable referencing
- From: Michael Priestley <firstname.lastname@example.org>
- To: Eliot Kimber <email@example.com>
- Date: Tue, 13 Sep 2011 11:28:23 -0400
You are misunderstanding my case. Hopefully
the examples I provided in a followon email will help.
The authors would be working with a
key definition file that mapped to the source files they need to link to.
At build time, a new map would be created
to pull in the deliverable-specific mappings, overriding the source-time
My approach does assume that a key mapping
file can be produced by the build for a specific deliverable. I don't see
any way to avoid this assumption, since at no other time does a system
know what the key mappings should be for that deliverable - taking into
account things like build parameters, like ditavals to be used.
Your approach also makes some assumptions:
- You are assuming a single production
system for all deliverables. Mine does not.
- You are also assuming a single
scope for all deliverables from a given map. You do not allow for map nesting
or conreffing to allow for larger or smaller scopes, and you explicitly
ignore ditaval. My approach allows for any combination of output conditions.
Michael Priestley, Senior Technical
Staff Member (STSM)
Lead IBM DITA Architect
||Eliot Kimber <firstname.lastname@example.org>
||09/13/2011 11:00 AM
||Re: [dita] Scenario for cross-deliverable
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
processors would generate a map that couple be so included, even if it
sensible to define the authoring in that way. Doing so would be to mandate
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
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
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
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
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
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
the publication, for the simple reason that they want the link to work
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
the problem precisely because it is rendition specific, but the intent
not rendition specific, it is publication-as-authored specific. That is,
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
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
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
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
normal element ID reference from a key reference.
On 9/6/11 10:11 AM, "Michael Priestley" <email@example.com>
> Hi Eliot,
> I believed your scenario was covered in my case of multiple chapters
> produced as separate PDFs.
> In that scenario, the author of Map A does not define a key that references
> key defined in map B - they simply include map B's definition of map
> after it has gone through processing to produce a deliverable-specific
> of that key definition.
> I believe my scenario shows how cross-deliverable referencing could
> without using map-specific addressing. I believe map-specific addressing
> problematic because it doesn't actually tell us what the deliverable-specific
> address will be. You assume some automated process that will allow
> 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
> 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
> what the hrefs should resolve to) is when the deliverable is built.
> I have a deliverable-specific map being built as part of the deliverable
> build, which can then be incorporated into the keyspace for other
> 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 <firstname.lastname@example.org>
> To: Michael Priestley/Toronto/IBM@IBMCA, dita <email@example.com>
> 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
> 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
> working link from the PDF for Map A to the PDF for Map B. There's
> 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
> 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
> of the two PDFs so that if relative URLs are to be constructed, they
> constructed reliably.
> But the essential bit here is having the key definition *as authored*
> unambiguous reference to a key in the scope of Map B's key space.
> 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
> authored--given an unambiguous address, the processing implementation
> exercise in engineering and is uninteresting. If there is no unambiguous
> address then there is no generalized processing that will work except
> accident or unenforceable convention.
> In particular, it *cannot be correct* to author the key definition
> scenario where the URL is to the resource *as rendered*. It must be
> resource *as authored*. That is a fundamental requirement because
> that, you cannot have generic content to which any processing may
> with consistent and predictable results.
> As an author I want to say "I am linking to this *content* thing
> other publication" and I want links to that thing to work correctly
> possible renditions. "Work correctly" is rendition dependent,
> author's intent and their markup is rendition independent.
> On 9/6/11 9:19 AM, "Michael Priestley" <firstname.lastname@example.org>
>> This was my todo from last week's mtg - sorry I'm leaving it to
>> This describes a solution that can be implemented today - I still
>> more work to be done, including:
>> - a general solution for key scoping (but not deliverable-based
>> the boundaries of deliverables are mutable, as I'm trying to show
>> - 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
>> - 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,
>> needs to be resolved as a cross-deliverable link in the single-chapter
>> 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
>> 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
>> 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
>> 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
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
| [Thread Prev]
| [Thread Next]
| [Date Next]
| [Thread Index]
| [List Home]