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

[Eliot Kimber <ekimber@contrext.com>]

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