Re: [dita] Issue #29: How best to handle <mapresources>? Feedback wanted.

[Kristen James Eberlein <kris@eberleinconsulting.com>]

Eliot, in your code sample, what benefit do you get from <mapresources>? 
Seems as if <topicgroup> serves the basic purpose ...

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 10/2/2019 7:18 PM, Eliot Kimber wrote:
> I vote for adding mapresources to mapgroup domain.
>
> My use case relative to bookmap is having submaps for chapters where 
> each chapter is a separate keyscope scope and has its own keydefs, e.g.:
>
> <chapter keyscope=" install" keys="installation" href="topic-12355.dita">
> <topicmeta>
> <navtitle>Installation</navtitle>
> </topicmeta>
> <mapresources>
> <topicgroup>
> <topicmeta>
> <navtitle>Images</navtitle>
> </topicmeta>
> <keydef keys="illus-remove-cover" format="jpg"
> href="media/illustrations/image-2343342.jpg"
> />
> </topicgroup>
> </mapresources>
> <topicref keys="install-prep" href="topic-452342.dita"/>
> <topicref keys="install-process" href="topic-452344.dita"/>
> </chapter>
>
> In my personal DITA use I often define a specialization named 
> "keydefs" and then use that as we are proposing to use mapresources.
>
> It would be a natural constraint to allow <mapresources> only as the 
> first child of specific topicref types (chapter, part, etc.) if map 
> authoring needs to be that constrained.
>
> One thing to keep in mind is that map authoring by its nature 
> generally requires a deeper understanding of how DITA maps work, which 
> usually means that the map author doesn't need as much guidance, 
> meaning it's usually not worth the effort to setup constraints for 
> maps as compared to topics, where it's usually very important. For the 
> typical map author a simple convention or pre-defined template 
> document is usually sufficient.
>
> Cheers,
>
> E.
>
> --
> Eliot Kimber
> http://contrext.com
>
> ïOn 10/2/19, 4:26 PM, "Kristen James Eberlein" 
> <dita@lists.oasis-open.org on behalf of kris@eberleinconsulting.com> 
> wrote:
>
> One of the goals of proposal #29, "Update bookmap" is to provide
> an intuitive location in a bookmap for map authors to locate
> resource-only objects such as:
> * Key definition maps
> * Subject scheme maps
> * Topics that hold information for constructing PDF cover pages
> We have several options for how handle the <mapresources>
> element:
> 1. Define this element directly in <bookmap>. (In this
> case, I think it should be named <bookmapresources>).
> 2. Define this element in a new domain. I don't think we want to
> do this, since we have an existing map domain.
> 3. Add this element to the map group domain.
> So, given these two option, which is the correct choice for the
> TC?
> I don't have the answer, but I can suggest the framework in
> which we can make the answer. I think we need to focus on
> the user experience for map authors and information architects and
> ask the following questions:
> * How useful will a <mapresources> element be in map? Will
> it solve any existing problems? Make anything easier?
> * Will having <mapresources> available everywhere that
> <topicref> is available add to element overload for
> authors? Make developing maps more difficult?
> If having a <mapresources> element in the map group domain
> solves problems/meets real user requirements, then I can support
> that.
> If we only have theoretical use cases for adding
> <mapresources> to the map group domain, then I'll advocate
> for simply adding <bookmapresources> to bookmap.mod. We know
> that bookmap design has inherent flaws, and remember that the goal
> of the bookmap update proposal is "to remediate problems without
> breaking backwards compatibility."
> --
> Best,
> Kris
> Kristen James Eberlein
> Chair, OASIS DITA Technical Committee
> Principal consultant, Eberlein Consulting
> www.eberleinconsulting.com <http://www.eberleinconsulting.com>
> +1 919 622-1501; kriseberlein (skype)
> ---------------------------------------------------------------------
> 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