RE: [dita] referencing a bookmap from a map

There are two classes of users here. Authors and implementers.

Different authors will feel differently about being allowed or prohibited from shooting themselves in the foot. And they may feel differently still before and after shooting themselves in the foot.

Implementers (like me) are looking for some guidance. Should we keep authors from shooting themselves in the foot, warn them, but let them shoot themselves in the foot if they wish, or just let them shoot themselves in the foot without any warning. And if we let them shoot themselves in the foot, should different implementations always shoot the same foot or can some implementations shoot the left foot while others shoot the right, while still others shoot the head? As an implementer, what I want to avoid is having someone say that after we shot them in the right foot that we should have shot them in the left foot because that is what some other implementation does or what the DITA specification calls for.

To get back to DITA maps, it would seem that we have some choices, but I'm losing track of who is pushing for what:

1) Make map to bookmap illegal, Bruce's original approach, now withdrawn.

2) Allow map to bookmap, where the bookmap context is not overridden by the map, my proposal from earlier today, still on the table.

3) Michael's proposal that I'm not sure I understand, but which would have map references behave more like conref and so presumably more specialized topicrefs would be generalized to less specialized topicrefs, or pretty much the opposite of approach #2 (Michael, correct me if I got your proposal wrong).

4) Eliot's proposal, which I'm not sure I understand, but which seems to be "anything goes" leaving it up to the implementers (Eliot, correct me if I got your proposal wrong). . Eliot would proposal #2 allow you to do what you want to do?

What did I miss?

And of course I’m not really talking about map to bookmap, but really generic map to specialized map (or more likely generic topicref to specialized topicref).

Proposal 12055 doesn't actually call for, but allows some unusual sequences for bookmap to bookmap references (chapters within chapters). Is anyone proposing that we reopen any of the decisions made as part of proposal 12055? I wasn’t. It seems as if Michael might be? I’m less sure about Eliot. Eliot, does proposal 12055 prohibit anything that you want to be able to do?

In his note Michael said something about the need to move reltables. This is the first I'd head about that. Reltables can occur at the top level in the hierarchy in maps and not just at the end. The placement of reltables in bookmaps is more restricted. I'm not sure why. But given what proposal 12055 says, you could certainly get reltables in unexpected places as far as a bookmap is concerned using a bookmap to map reference. I assumed as implementers that we just had to cope with that as best we can.

And, finally, does “maprefness” cascade from a specialized map to a specialized map or to a generic map as would seem to be called for by proposal 12055? Is a mapref more like a topicref with @format=”ditamap” than it is like a chapter with @format=”ditamap”? How does an implementation tell the difference between mapref and chapter by just looking at the DTD or schema? Are there any other specialized topicrefs similar to mapref that need special consideration as far as proposal 12055 goes?

-Jeff

> -----Original Message-----

> From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]

> Sent: Tuesday, June 09, 2009 5:07 PM

> To: dita

> Subject: RE: [dita] referencing a bookmap from a map

> I withdraw my objection, which was semantic in nature.

> There have long been two philosophies of software design as regards

> responsibility. One is the UNIX approach, where you can do pretty much

> anything and shooting oneself in the foot is not prevented, perhaps

> being considered a learning experience. The other, in contrast to this

> anarchic situation, is the old PDP-11 or Nazi approach where the the

> Thou Shalts and the Thou shalt nots are spelled out and enforced. The

> unruly and the ruly.

> DTD and schema are inherently ruly, but map/topicref is generic, not

> restricted as to what kinds of things can be aggregated in a single map.

> As we saw in the discussion of aggregated editing, map/topicref escapes

> validation constraints (the targets can only be presumed each severally

> to have been validated). As matters currently stand, foot-shooting is

> not prohibited, and the consequences thereof are pretty much left up to

> the inventiveness (or not) of the implementor.

> If we leave it this way, it would be kind of us to identify combinations

> of topicref targets that should be avoided, such as those that have the

> effect of allowing chapters to nest, and point them out in the spec.

> /Bruce

> > -----Original Message-----

> > From: Eliot Kimber [mailto:ekimber@reallysi.com]

> > Sent: Tuesday, June 09, 2009 12:25 PM

> > To: Michael Priestley; Ogden, Jeff

> > Cc: dita

> > Subject: Re: [dita] referencing a bookmap from a map

> >

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

> >

> > > Hi Jeff,

> > >

> > >> Topicref to bookmap:

> > >> Chapters in the bookmap maintain their ?chapterness?

> > >> Parts in the bookmap maintain their ?partness?

> > >

> > > If we think of a mapref as being parallel to a conref (basically a

> > > shorthand for "pull the target hierarchy into this point in this

> > > hierarchy, but push reltables to the end because they're

> > not allowed

> > > within a hierarchy") then we should discard the chapterness - just

> > > like we discard <step>ness when we conref from a <li>.

> > >

> > > Otherwise we allow chapters to nest, and break any bookmap

> > processors

> > > that are expecting DTD-validated content.

> >

> > My initial reaction to this is that it is unnecessarily

> > restrictive because map-to-map relationships are not really

> > conref relationships (if you want conref, use conref) but

> > looser composition (of compound map) relationships where the

> > relevant constraints and processing implications cannot be

> > known in advance.

> >

> > That is, when processing a map, a processor need not create a

> > literal new map, but simply process the referenced map as it

> > exists, with knowledge of the referencing context. In that

> > case, the fact that the referenced topicref is a bookmap

> > chapter may or may not be relevant and the user may or may not care.

> >

> > I think part of this discussion may result from an inherent

> > bit of fuzziness in the design of map-to-map references,

> > which is that there is no necessary well-defined thing that

> > is the target of the reference to which, for example, a type

> > check could be applied.

> >

> > That is, there is no requirement that a referenced map have

> > exactly one root topicref. In the case where there is no

> > single root topicref, there is nothing to which a topicref

> > could be unambiguously checked except the map element itself,

> > but the map element is not reliably distinguishing (consider

> > the L&T map domain, which allows the inclusion of very

> > specialized topicrefs into an otherwise unspecialized <map> element).

> >

> > So I think we are obligated to say that map-to-map references

> > are unconstrained by the spec and its up to processors to

> > decide what is or isn't meaningful for a give use instance.

> >

> > Certainly in my "library map" use case, where I want a map

> > that points to multiple bookmaps, my intent is clear and I

> > can implement processing that makes it sensible, and that

> > processing will almost certainly not be to treat the entire

> > map as a single virtual map instance document but to treat

> > the library map as a set of navigations to the otherwise

> > individual bookmaps.

> > There's nothing in the current DITA language that lets me

> > express this intent directly (unless it's possibly

> > scope="peer" on a map-to-map reference, but scope="peer" is

> > seriously underspecified in the 1.2 spec as currently drafted

> > and certainly doesn't address this particular question).

> >

> > I would be very uncomfortable saying that processors are

> > *obligated* to treat references to specialized topicrefs as

> > generalized. I would be OK with saying they *can* treat them

> > as generalized.

> >

> > I would also be OK with saying that the type= attribute can

> > indicate the type of the top-level topicrefs a given

> > map-to-map reference effectively addresses, e.g.:

> >

> > <topicref href=""mybookchaptermap.ditamap"" type="chapter"/>

> >

> > If this form of type= was required in order to preserve the

> > specialized nature in processing referenced topicrefs, I

> > would be OK with that, since it doesn't preclude the

> > functionality but does make intent clearer and enables

> > designers to build in constraints in specializations.

> >

> > Cheers,

> >

> > E.

> >

> > ----

> > Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.

> > email: ekimber@reallysi.com <mailto:ekimber@reallysi.com>

> > office: 610.631.6770 | cell: 512.554.9368 2570 Boulevard of

> > the Generals | Suite 213 | Audubon, PA 19403 www.reallysi.com

> > <http://www.reallysi.com> | http://blog.reallysi.com

> > <http://blog.reallysi.com> | www.rsuitecms.com

> > <http://www.rsuitecms.com>

> >

> > ---------------------------------------------------------------------

> > To unsubscribe from this mail list, you must leave the OASIS

> > TC that generates this mail. Follow this link to all your

> > TCs in OASIS at:

> > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgr

> > oups.php

> >

> ---------------------------------------------------------------------

> To unsubscribe from this mail list, you must leave the OASIS TC that

> generates this mail. Follow this link to all your TCs in OASIS at:

> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

dita message