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] referencing a bookmap from a map

If I may step in to the battle at its most dangerous moment and try to sum
up what I'm thinking after reading all of this thread at once...

First, my assumptions -
* I'm going to talk about bookmap because it is easy to use as an example,
but obviously it's only one case of millions.
* I have been trying more and more to keep processing out of spec
discussions. However, I do find it very useful to help understand the
meaning of how these things are assembled. That said - I'm trying to focus
on the effective result of map references, rather than on how files might
be modified by a processor or how the result might be rendered.

With that out of the way - as I understand it, much of Michael's concern
could be restated as follows: If you are pulling a chapter into another
map, and you want it to remain a chapter, why are you not pulling it in
with a <chapter> element? If you are pulling it in with a <topicref>
instead, doesn't that mean that either a) your current map does not allow
chapters, or b) you do not want it to be a chapter at this point? So -
wouldn't the most appropriate result be to try to treat that chapter as the
referencing element?

Item 12055 already states that <chapter> may pull in other elements, and
that it casts them as chapter. It gives a specific example of when this may
produce odd results -- when <chapter> references another bookmap with
parts. Those parts are cast as <chapter>; if they in turn nest chapters,
you end up with chapters inside chapters, and 12055 says that the result
can be warnings, errors, corrective behavior, etc.

With that example in 12055 - we've established a policy where the
referencing topicref pushes its role onto the target(s). Children of the
target are not touched, and processors can decide how to handle them when
the results get wonky.

12055 also clarifies the fact that new specialized topicref elements *may
define different behaviors for map references*. This is where it talks
about the new mapref element, which explicitly does *not* push its role
onto the targets.

Given all of that - I am not sure that we need any new rules for the
topicref->chapter case. Couldn't it use the same rules? I'll try to avoid
stating this in terms of processing, but somebody else might do a better
* By default -- the referencing element pushes its role onto the target.
<chapter> references to <topicref> become chapters, <topicref> references
to <chapter> become topicrefs.
* Children of the target element are not modified
* If the result does not make sense to you (chapters in chapters, appendix
in front matter), you are free to do what you want - error, recover, etc

Now awaiting tomatoes...

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit

             Michael Priestley                                             
             com>                                                       To 
                                       Eliot Kimber <ekimber@reallysi.com> 
             06/16/2009 10:00                                           cc 
             AM                        dita <dita@lists.oasis-open.org>,   
                                       "Ogden, Jeff" <jogden@ptc.com>      
                                       Re: [dita] referencing a bookmap    
                                       from a map                          

Michael Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect

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
> "it's up to processors to make sense of the result or not, as they

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
> the combined map is not relevant to this discussion, because that level
> 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
> about the nature of the processing that are not warranted, such as that
> 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
> processed individually for the purposes of creating say pages from it,
> 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

> 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
> 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
> map-to-map references are logical relationships rather than content
> references, it is not a DITA requirement that the effective map conform
> the DTD or schema of the referencing map. However, processors may report
> such maps as processor errors, for example, if a particular combination
> 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
> 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

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