Re: [dita] DITA 1.2 suggestion--Inserting a ditamap into a bookmap

[Robert D Anderson <robander@us.ibm.com>]

Hi Paul,

A couple of things -- first, I know that Erik Hennum has spoken of a
<mapref> element as a more general requirement, something that should be
added to the mapgroup domain. I think it's one of the items from 2006
emails that did not get carried through onto the list. I just asked him
about it, and he'll be posting more info about it soon. I think that one of
the domain proposals for 1.2 would allow it to be placed in bookmap without
also putting in <topicref>.

That said - I think that it does actually make sense to use <chapter> to
point to another map. In our early prototypes, many users expected this to
work. They typically have one map that includes a top level topicref, which
is the start of the chapter. Those that have multiple top-level topicrefs
in the target map all expect that the <chapter> reference will cast each
top-level element as a chapter -- there does not really seem to be any
other alternative, other than failure, which is not too user friendly. The
same is true for <part>, which seems to cast each top-level item in the
target map as a part.

I'd worry that replacing these with a <mapref> element would simply cause
us to lose the semantics of the reference - how do we know if the target
represents a chapter or a part? The specialized element is actually
describing the role that this reference plays in the current context. For
example, the chapter element today indicates nothing about the type of a
topic, only that it plays the role of a chapter. Replacing the specialized
element with an element that indicates the type of the target, like mapref
indicating that the target is a map, loses any description of that role. In
a map with more groupings than just part and chapter, this loss would
likely be more severe.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit
(507) 253-8787, T/L 553-8787

"Grosso, Paul" <pgrosso@ptc.com> wrote on 03/19/2007 01:41:14 PM:

> This is a DITA 1.2 suggestion to improve how one inserts
> a ditamap reference into a bookmap.
>
> The problem is that, to reference a ditamap from a bookmap,
> one might have a bookmap that looks like this:
>
>     <bookmap>
>       <chapter href=somefile.ditamap format=ditamap/>
>     </bookmap>
>
> However, this can be very misleading since the things in
> the referenced ditamap file may or may not be chapters.
> Having to use chapter to reference a ditamap from a
> bookmap is therefore very confusing to users.
>
> We could allow topicref in bookmap's everywhere chapter and
> part are currently allowed.  That would permit:
>
>     <bookmap>
>       <topicref href=somefile.ditamap format=ditamap/>
>     </bookmap>
>
> However, allowing topicref would open to door to references
> to other things besides ditamaps.
>
> The preferred solution would be to create something like "mapref"
> as a specialization of topicref with a fixed value for format
> of "ditamap" and possibly a fixed value for scope of "local".
> (I'm less sure about scope, but I can't think of a case where it
> makes sense to have a topicref to a DITA map that isn't available
> at the time of composition.)  That would allow users to enter:
>
>     <bookmap>
>       <mapref href=somefile.ditamap/>
>     </bookmap>
>
> which would be a lot less confusing than the current situation.