RE: [dita] referencing a bookmap from a map

Comments below.

-Jeff

From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Tuesday, June 16, 2009 12:12 PM
To: Ogden, Jeff
Cc: dita
Subject: RE: [dita] referencing a bookmap from a map

>What happens by default shouldn’t matter to the DITA specification. The 1.1 specification is
>entirely silent about these sorts of details. You can sort of guess from the names and some
>of the element descriptions, but that is all you are doing. I think the 1.2 specification
>should remain silent on these sorts of details.

So what is 12055 doing? Are those required behaviors, or just suggested, or something else?

I’m not sure. I think of it as a requirement, that if you use a chapter to reference a topicref that the topicref MUST be treated as a chapter.

But 12055 allows for exceptions, but doesn’t say how exceptions are defined or recognized or even who makes the exceptions (the specification author, the DTD author, the processing implementer, the map author, …). So what is a requirement that allows exceptions? Is that still a requirement or a suggestion or something else? I have no idea.

To clarify:

- I'm suggesting behavior only for aggregating processes - not every possible map process

I understand and agree.

- I'm suggesting behavior that would be a default, not a requirement.

I don’t know what this means. Can a vendor deliver non-default behavior out of the box? Is it just that the default behavior has to be available somehow upon request?

Or to move this into standards language is this something that is required (MUST), strongly recommended (SHOULD), or allowed (MAY)?

I'd actually be happy with being parallel to whatever strength we put behind 12055. Just as long as we're consistent.
- as Robert Anderson noted, if we're going to specify that a <chapter> reference to a bookmap should resolve into a set of <chapter> references to the bookmap's parts, then we should have the same level of specification for what a <topicref> does (and I think it should do something parallel)

I usually push for consistency. 12055 doesn’t directly address this case and so we would be consistent if we said that specialized topic references override generic topic references. And I think that that gives a better result than saying that the referencing topic reference override the referenced topic reference.

- otherwise, how does a user get rid of semantics that don't make sense for the reusing context? for example, a writer reusing a bookmap into an Eclipse TOC who doesn't want "chapter xxx" generated.

Going with the referencing overrides referenced approach doesn’t answer the question. You still need to ask “how does a user get rid of semantics that don’t make sense for the reusing context? For example, a writer reusing a bookmap into an Eclipse TOC that does want “chapter xxx” generated.”

We’ve got two choices (wants vs. doesn’t want or overrides vs. doesn’t override) and we seem to need to pick one or the other. Either way we are left with the same question, how does an author pick the other choice. One solution is to provide an explicit way for the user to make the choice. The other way is to define a set of rules that effectively says that it isn’t reasonable to make the other choice and so we won’t allow it or more likely that we won’t make it easy.

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

dita message