OASIS Darwin Information Typing Architecture (DITA) TC

  • 1.  Re: [dita] Issue #29: How best to handle

    Posted 10-02-2019 23:46
    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


  • 2.  RE: [dita] Issue #29: How best to handle

    Posted 10-03-2019 14:47
    I tend to agree with Eliot, mostly because I like the additional semantic precision and the convenience of not having to set the processing role. Bill Burns Content Architect Healthwise bburns@healthwise.org www.healthwise.org 208.331.6917 (office) 208.345.1897 (fax)


  • 3.  Re: [dita] Issue #29: How best to handle

    Posted 10-03-2019 14:52
    Not to speak for Eliot, but I think it's a matter of readability and cleanliness. It's the same reason we have <topichead>; you could just use <topicref> with no @href, but this expresses the intent more clearly. <mapresources> is cleaner than <topicgroup processing-role="resource-only">. I think it makes sense in mapgroup. Many groups I've encountered that are using keys would benefit from an official container for key definitions. Chris ïOn 10/2/19, 7:46 PM, "dita@lists.oasis-open.org on behalf of Kristen James Eberlein" <dita@lists.oasis-open.org on behalf of kris@eberleinconsulting.com> wrote: 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 > > > > > --------------------------------------------------------------------- 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 The content of this email and any attached files are intended for the recipient specified in this message only. It may contain information that is confidential, proprietary, privileged, and/or exempt from disclosure under applicable law. It is strictly forbidden to share any part of this message with any third party or rely on any of its contents, without the written consent of the sender. If you received this message by mistake, please reply to this message and follow with deletion of the original message, any copies and all attachments, so that Oberon Technologies can ensure such a mistake does not occur in the future.


  • 4.  Re: [dita] Issue #29: How best to handle

    Posted 10-03-2019 15:24
    I certainly agree that <mapresources> is semantically more precise. I personally like it and would use it, but want to make sure that we consider the impact of adding another element that will be available everywhere that <topicref> is. I posted on dita-users asking for feedback about <mapresources>, and got the following response from Radu Coravu: ------------------------ "I clearly see the benefit for [<mapresources>] in a bookmap, as now we need to place all those key definitions in the frontmatter. But maybe for a plain DITA <map> [<mapresources>] might not make that much sense, it would increase the complexity of the choices you need to make when you want to add a new element on the first level of the DITA Map. So somehow I would see the place of this element only directly after the bookmap <topicmeta> element, so maybe avoid allowing it in any place where a topicref is allowed. -------------------------- If we go down the path of adding <mapresources> to the map group domain, do we want to consider constraining map to restrict where <mapresources> is allowed? 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/3/2019 10:52 AM, Chris Nitchie wrote: Not to speak for Eliot, but I think it's a matter of readability and cleanliness. It's the same reason we have <topichead>; you could just use <topicref> with no @href, but this expresses the intent more clearly. <mapresources> is cleaner than <topicgroup processing-role="resource-only">. I think it makes sense in mapgroup. Many groups I've encountered that are using keys would benefit from an official container for key definitions. Chris ïOn 10/2/19, 7:46 PM, "dita@lists.oasis-open.org on behalf of Kristen James Eberlein" <dita@lists.oasis-open.org on behalf of kris@eberleinconsulting.com> wrote: 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 > > > > > --------------------------------------------------------------------- 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 The content of this email and any attached files are intended for the recipient specified in this message only. It may contain information that is confidential, proprietary, privileged, and/or exempt from disclosure under applicable law. It is strictly forbidden to share any part of this message with any third party or rely on any of its contents, without the written consent of the sender. If you received this message by mistake, please reply to this message and follow with deletion of the original message, any copies and all attachments, so that Oberon Technologies can ensure such a mistake does not occur in the future.


  • 5.  Re: [dita] Issue #29: How best to handle

    Posted 10-03-2019 15:28
      |   view attached




    If
    we go down the path of adding <mapresources> to the map group domain,
    do
    we want to consider constraining map to restrict where <mapresources>
    is
    allowed?





    There are entirely logical arguments for the beginning, the end, and (in the case of something large and horrid) per-chapter.  I don't think constraining location is of net benefit.




    I would not want to see <mapresources> excluded from map; sometimes the bookmap is the top level grouping of three or four levels of component maps, and the larger component maps, the children and grandchilden of the bookmap, can easily need their own definitions.












    Graydon Saunders  Publishing Solutions Developer     Precision
    Content  
    Email:   graydon@precisioncontent.com     www.precisioncontent.com

     




     

    Unlock the Knowledge in Your Enterprise


    This email and any files transmitted with it are confidential and intended solely for the use of the individual or entity to whom they are addressed.
    If you are not the intended recipient you are notified that disclosing, copying, distributing or taking any action in reliance on the contents of this information is strictly prohibited.   Please
    notify us by return email if you have received this email in error.  2019, Precision Content Authoring Solutions Inc, Mississauga, Ontario, Canada









    From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> on behalf of Kristen James Eberlein <kris@eberleinconsulting.com>
    Sent: 03 October 2019 11:23
    To: DITA TC <dita@lists.oasis-open.org>
    Subject: Re: [dita] Issue #29: How best to handle <mapresources>? Feedback wanted.
     


    I certainly agree that <mapresources> is semantically more precise. I

    personally like it and would use it, but want to make sure that we
    consider the impact of adding another element that will be available
    everywhere that <topicref> is.

    I posted on dita-users asking for feedback about <mapresources>, and got
    the following response from Radu Coravu:

    ------------------------

    "I clearly see the benefit for [<mapresources>] in a bookmap, as now we
    need to place
    all those key definitions in the frontmatter.

    But maybe for a plain DITA <map> [<mapresources>] might not make that
    much sense, it
    would increase the complexity of the choices you need to make when you
    want to add a new element on the first level of the DITA Map.

    So somehow I would see the place of this element only directly after the
    bookmap <topicmeta> element, so maybe avoid allowing it in any place
    where a topicref is allowed.

    --------------------------

    If we go down the path of adding <mapresources> to the map group domain,
    do we want to consider constraining map to restrict where <mapresources>
    is allowed?

    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/3/2019 10:52 AM, Chris Nitchie wrote:
    > Not to speak for Eliot, but I think it's a matter of readability and cleanliness. It's the same reason we have <topichead>; you could just use <topicref> with no @href, but this expresses the intent more clearly. <mapresources> is cleaner than <topicgroup
    processing-role="resource-only">. I think it makes sense in mapgroup. Many groups I've encountered that are using keys would benefit from an official container for key definitions.
    >
    > Chris
    >
    > ïOn 10/2/19, 7:46 PM, "dita@lists.oasis-open.org on behalf of Kristen James Eberlein" <dita@lists.oasis-open.org on behalf of kris@eberleinconsulting.com> wrote:
    >
    >
    >      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= >
    >      > <topicmeta>
    >      > <navtitle>Installation</navtitle>
    >      > </topicmeta>
    >      > <mapresources>
    >      > <topicgroup>
    >      > <topicmeta>
    >      > <navtitle>Images</navtitle>
    >      > </topicmeta>
    >      > <keydef keys="illus-remove-cover" format="jpg"
    >      > href= >
    >      > />
    >      > </topicgroup>
    >      > </mapresources>
    >      > <topicref keys="install-prep" href= >
    >      > <topicref keys="install-process" href= >
    >      > </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
    >      >
    >      >
    >      >
    >      >
    >      >
    >
    >      ---------------------------------------------------------------------
    >      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
    >
    >
    >
    > The content of this email and any attached files are intended for the recipient specified in this message only. It may contain information that is confidential, proprietary, privileged, and/or exempt from disclosure under applicable law. It is strictly forbidden
    to share any part of this message with any third party or rely on any of its contents, without the written consent of the sender. If you received this message by mistake, please reply to this message and follow with deletion of the original message, any copies
    and all attachments, so that Oberon Technologies can ensure such a mistake does not occur in the future.

    ---------------------------------------------------------------------
    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









  • 6.  Re: [dita] Issue #29: How best to handle

    Posted 10-03-2019 15:37
    Yes exactly. If the element is available at all I would want to use it generally for the purpose of organizing resource-only keydefs. I usually define such a specialization in my own map specializations (i.e., D4P). Cheers, E. -- Eliot Kimber http://contrext.com ïOn 10/3/19, 9:52 AM, "Chris Nitchie" <dita@lists.oasis-open.org on behalf of chris.nitchie@oberontech.com> wrote: Not to speak for Eliot, but I think it's a matter of readability and cleanliness. It's the same reason we have <topichead>; you could just use <topicref> with no @href, but this expresses the intent more clearly. <mapresources> is cleaner than <topicgroup processing-role="resource-only">. I think it makes sense in mapgroup. Many groups I've encountered that are using keys would benefit from an official container for key definitions. Chris ïOn 10/2/19, 7:46 PM, "dita@lists.oasis-open.org on behalf of Kristen James Eberlein" <dita@lists.oasis-open.org on behalf of kris@eberleinconsulting.com> wrote: 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 > > > > > --------------------------------------------------------------------- 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 The content of this email and any attached files are intended for the recipient specified in this message only. It may contain information that is confidential, proprietary, privileged, and/or exempt from disclosure under applicable law. It is strictly forbidden to share any part of this message with any third party or rely on any of its contents, without the written consent of the sender. If you received this message by mistake, please reply to this message and follow with deletion of the original message, any copies and all attachments, so that Oberon Technologies can ensure such a mistake does not occur in the future.


  • 7.  Re: [dita] Issue #29: How best to handle

    Posted 10-03-2019 17:53
    I agree with adding it to the map domain, so it's available from either map or bookmap. Not everyone uses bookmap. I have a few authors that insist on using map to organize their structures, because they want to get away from the book paradigm (even semantically). Having a specific location to define keys that should be valid in the context of map would be very useful. We do currently just assign the topic-based keys on topicref, but assigning additional keys in the context of the map would be nice. Thanks, --Scott ïOn 10/3/19, 9:37 AM, "dita@lists.oasis-open.org on behalf of Eliot Kimber" <dita@lists.oasis-open.org on behalf of ekimber@contrext.com> wrote: Yes exactly. If the element is available at all I would want to use it generally for the purpose of organizing resource-only keydefs. I usually define such a specialization in my own map specializations (i.e., D4P). Cheers, E. -- Eliot Kimber https://urldefense.proofpoint.com/v2/url?u=http-3A__contrext.com&d=DwIFaQ&c=P3aKjizb3qsxp0SERaL2sw&r=YQWdLfM9mekBOdoMmoBdn9RgyqIHrveGolBbb4_uGWQ&m=0Ec9nMDHMcR-meGf0v-8c1gNpn0ralhcpN6wq-ZSXsc&s=Q1_RoafjB0aOB07oUfwN3bHNLbjx4wgM1JFqQN-RNxA&e= On 10/3/19, 9:52 AM, "Chris Nitchie" <dita@lists.oasis-open.org on behalf of chris.nitchie@oberontech.com> wrote: Not to speak for Eliot, but I think it's a matter of readability and cleanliness. It's the same reason we have <topichead>; you could just use <topicref> with no @href, but this expresses the intent more clearly. <mapresources> is cleaner than <topicgroup processing-role="resource-only">. I think it makes sense in mapgroup. Many groups I've encountered that are using keys would benefit from an official container for key definitions. Chris On 10/2/19, 7:46 PM, "dita@lists.oasis-open.org on behalf of Kristen James Eberlein" <dita@lists.oasis-open.org on behalf of kris@eberleinconsulting.com> wrote: 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 > https://urldefense.proofpoint.com/v2/url?u=http-3A__contrext.com&d=DwIFaQ&c=P3aKjizb3qsxp0SERaL2sw&r=YQWdLfM9mekBOdoMmoBdn9RgyqIHrveGolBbb4_uGWQ&m=0Ec9nMDHMcR-meGf0v-8c1gNpn0ralhcpN6wq-ZSXsc&s=Q1_RoafjB0aOB07oUfwN3bHNLbjx4wgM1JFqQN-RNxA&e= > > 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 < https://urldefense.proofpoint.com/v2/url?u=http-3A__www.eberleinconsulting.com&d=DwIFaQ&c=P3aKjizb3qsxp0SERaL2sw&r=YQWdLfM9mekBOdoMmoBdn9RgyqIHrveGolBbb4_uGWQ&m=0Ec9nMDHMcR-meGf0v-8c1gNpn0ralhcpN6wq-ZSXsc&s=ElDCTazuoiZctWF7X--lYKTGAePmSNvixt7__T6noq8&e= > > +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://urldefense.proofpoint.com/v2/url?u=https-3A__www.oasis-2Dopen.org_apps_org_workgroup_portal_my-5Fworkgroups.php&d=DwIFaQ&c=P3aKjizb3qsxp0SERaL2sw&r=YQWdLfM9mekBOdoMmoBdn9RgyqIHrveGolBbb4_uGWQ&m=0Ec9nMDHMcR-meGf0v-8c1gNpn0ralhcpN6wq-ZSXsc&s=0he0T1ulEtrxls2FWOs16JtUaE6Ka04yn0eCOTifhvI&e= > > > > > --------------------------------------------------------------------- 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://urldefense.proofpoint.com/v2/url?u=https-3A__www.oasis-2Dopen.org_apps_org_workgroup_portal_my-5Fworkgroups.php&d=DwIFaQ&c=P3aKjizb3qsxp0SERaL2sw&r=YQWdLfM9mekBOdoMmoBdn9RgyqIHrveGolBbb4_uGWQ&m=0Ec9nMDHMcR-meGf0v-8c1gNpn0ralhcpN6wq-ZSXsc&s=0he0T1ulEtrxls2FWOs16JtUaE6Ka04yn0eCOTifhvI&e= The content of this email and any attached files are intended for the recipient specified in this message only. It may contain information that is confidential, proprietary, privileged, and/or exempt from disclosure under applicable law. It is strictly forbidden to share any part of this message with any third party or rely on any of its contents, without the written consent of the sender. If you received this message by mistake, please reply to this message and follow with deletion of the original message, any copies and all attachments, so that Oberon Technologies can ensure such a mistake does not occur in the future. --------------------------------------------------------------------- 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://urldefense.proofpoint.com/v2/url?u=https-3A__www.oasis-2Dopen.org_apps_org_workgroup_portal_my-5Fworkgroups.php&d=DwIFaQ&c=P3aKjizb3qsxp0SERaL2sw&r=YQWdLfM9mekBOdoMmoBdn9RgyqIHrveGolBbb4_uGWQ&m=0Ec9nMDHMcR-meGf0v-8c1gNpn0ralhcpN6wq-ZSXsc&s=0he0T1ulEtrxls2FWOs16JtUaE6Ka04yn0eCOTifhvI&e=