Re: [dita] referencing a bookmap from a map

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

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

Eliot Kimber <ekimber@reallysi.com> wrote on
06/16/2009 07:56:21 AM:

> I see the issue as being very simple: either *require* generalization
of
> referenced topicrefs or *don't*.
>
> If you don't require generalization then there's
nothing more to say beyond
> "it's up to processors to make sense of the result or not, as
they choose".
 
I've been pushing for a required default of using
the referencing topicref's semantic (not the same as generalization). Customized
or specialized processing could override this default.

> I also submit that all discussion of output-specific processing applied
to
> the combined map is not relevant to this discussion, because that
level of
> processing is entirely implementation specific.

Since I believe that the changes you and Jeff want
to make would break existing code, and in fact set up a situation in which
all future code is inherently breakable unless restricted to the simplest
of cascading processing, I do think it's relevant. 
 
> For example, your question about how a processor of a map that references
> two bookmaps handles the indexes of both bookmaps makes several assumptions
> about the nature of the processing that are not warranted, such as
that the
> entire result map is processed as a unit or that index processing
is a
> monolithic process or even that index processing is done at all. 

I am trying to understand and expose the real-world
impact of the choice Jeff is proposing. I think it's entirely appropriate
for me to ask what the impact is for index processing. I say it will break,
and Jeff says it won't. How are we going to resolve this if we don't go
into the details of our assumptions?

I agree with you that this should be customizable,
but I also think that it should work out of the box. And I do think we
are obligated to provide guidance to processors to make something work
by default. 

We do not have to assume that "index processing
is done at all". But we do have to assume that it might be done, and
if it will be done, it should be done in a predictable fashion that doesn't
break in the face of a common markup scenario.  

> If the
> processing happens to be defined such that each referenced bookmap
is still
> processed individually for the purposes of creating say pages from
it, then
> there's no practical problem but I could just as easily implement
a
> multi-bookmap indexing process that produced a master index or a combined
> index or whatever.

If you want to implement this as your behavior, I
have no problem with that. I do have a problem with you stating that all
output processors should support this, in a manner that will be unique
to the processor, without guidance from the spec, for all possible future
specializations of map.

> 
> My point is that the semantics of map processing for producing results
is
> simply too unbounded for it to make any sense for the spec to say
anything
> about it.

And yet we already provide extensive documentation
of map processing. And we plan to provide more, as in 12055. 

I agree that people can do lots of crazy unbounded
things with maps. That's why I'm proposing the behavior I've described
(preserve the semantic of the referencing element) as a default, not a
requirement. 

I think you are drawing a black and white picture
(either generalize or not) when there is at least one important shade of
grey here (provide descriptions of default processing). And this shade
of grey in fact encompasses most of the behavior we've already described
for maps (such as link processing, navigation behavior, indexing, etc.).

> Maybe the solution is to simply say:
> 
> "When a topicref points to a map with format="ditamap"
the effective
> topicrefs reflect the most-specialized topicrefs involved. Note that
because
> map-to-map references are logical relationships rather than content
> references, it is not a DITA requirement that the effective map conform
to
> the DTD or schema of the referencing map. However, processors may
report
> such maps as processor errors, for example, if a particular combination
of
> maps cannot be processed meaningfully by the processor."

Reporting the error requires the processor to be aware
of content model restrictions, which is normally the job of the DTD or
schema. So either the content will have to be validated again post-aggregation,
or the processor will need to encode awareness of the DTD or schema constraints
that it is assuming applies. This is a radical change to processing pipeline
assumption, at least for me. 

> By always reflecting the most-specialized form no information is lost
but
> normal generalized processing can be applied just as it can for any
other
> specialized elements. By allowing processors to report processor errors
we
> remove the obligation to try to make sense of (to the processor)
> non-sensical cases.

First the processor must be able to detect the nonsensical
case. This will require special coding. Otherwise the nonsensical case
is more likely to produce nonsensical results, than to produce an error.

I'll finish by suggesting that, given the volume of
notes on this subject and the lack of agreement to date, we need to have
a phone call.

Michael Priestley