OASIS Darwin Information Typing Architecture (DITA) TC

Expand all | Collapse all

referencing a bookmap from a map

  • 1.  referencing a bookmap from a map

    Posted 05-28-2009 15:47
    Proposal 12055 is clear about what we do in the specialized map to 
    generic map case and also about the specialized map to specialized 
    map case, but we're not sure what should happen when a generic map 
    references a specialized map.
    
    For example, what should happen in the following case:
    
    map1
    ----
    	topicref to bookmap2
    
    bookmap2
    --------
    	frontmatter
    		booklists
    			Toc
    	part referencing a concept
    		chapter referencing a task
    
    What are the contexts or roles for the elements in bookmap2?  Unchanged?
    Or does the generic topic reference from map1 override the top level 
    topicrefs in bookmap2 so you end up with something effectively like the
    following for bookmap2:
    
    bookmap2
    --------
    	topicref for frontmatter
    		booklists
    			Toc
    	topicref for part referencing a concept
    		chapter referencing a task
    
    
    Keeping things unchanged preserves the specialized information from a
    bookmap,
    but it also allows you to create situations using map references that
    you 
    could not create within a single bookmap (e.g., a chapter within a
    chapter or 
    a part within a topic).  
    
    On the other hand, if the generic topic reference from map1 overrides
    the 
    top level topicrefs in bookmap2, you couldn't create unexpected
    situations, but 
    you lose all of the specialized information from a bookmap because you
    more or 
    less fallback to the lower common denominator of a generic map. 
    


  • 2.  RE: [dita] referencing a bookmap from a map

    Posted 06-05-2009 16:54
    Don,
    
    I've not seen any responses to this.  Can you put it on
    the agenda for our next meeting?
    
    thanks,
    
    paul 
    
    > 


  • 3.  RE: [dita] referencing a bookmap from a map

    Posted 06-05-2009 17:49
    There seems to me to be something inherently wrong about grouping more
    than one bookmap in a map, or grouping bookmaps, maps, and topics
    promiscuously together in a map, and that is the source of these
    conundrums. (Conundra?) 
    
     is designedly generic, or rather 


  • 4.  RE: [dita] referencing a bookmap from a map

    Posted 06-09-2009 14:34
    
    
    
    
    
    
    
    
    
    
    

    One approach to this is to simply say that the context (“chapterness”, “partness”, or …) does not cascade when a generic topic reference is used. Where a generic topic reference is a reference from a topicref or any topicref specialization defined in mapgropup-d  (mostly this just picks up mapref).

     

    The idea is that we don't want to lose the more detailed context that is available from a topicref specialization when maps or branches of maps are referenced using generic topicrefs that contain less information.

     

    This might or might not also be combined with a note that says that such references are discouraged and that implementations MAY, but are NOT REQUIRED to, issue warning messages in such cases.

     

    So,

     

       Topicref to bookmap:

          Chapters in the bookmap maintain their “chapterness”

          Parts in the bookmap maintain their “partness”

     

       Chapter to map:

          Top level topicrefs in the map receive “chapterness”

     

       Part to map

          Top level topicrefs in the map receive “partness”

     

      -Jeff

     

    >



  • 5.  RE: [dita] referencing a bookmap from a map

    Posted 06-09-2009 16:07

    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.

    Michael Priestley, Senior Technical Staff Member (STSM)
    Lead IBM DITA Architect
    mpriestl@ca.ibm.com
    http://dita.xml.org/blog/25



    "Ogden, Jeff" <jogden@ptc.com>

    06/09/2009 10:33 AM

    To
    "dita" <dita@lists.oasis-open.org>
    cc
    Subject
    RE: [dita] referencing a bookmap from a map





    One approach to this is to simply say that the context (“chapterness”, “partness”, or …) does not cascade when a generic topic reference is used. Where a generic topic reference is a reference from a topicref or any topicref specialization defined in mapgropup-d  (mostly this just picks up mapref).
     
    The idea is that we don't want to lose the more detailed context that is available from a topicref specialization when maps or branches of maps are referenced using generic topicrefs that contain less information.
     
    This might or might not also be combined with a note that says that such references are discouraged and that implementations MAY, but are NOT REQUIRED to, issue warning messages in such cases.
     
    So,
     
       Topicref to bookmap:
          Chapters in the bookmap maintain their “chapterness”
          Parts in the bookmap maintain their “partness”
     
       Chapter to map:
          Top level topicrefs in the map receive “chapterness”
     
       Part to map
          Top level topicrefs in the map receive “partness”
     
      -Jeff
     
    >

    > From: Grosso, Paul [mailto:pgrosso@ptc.com]
    > Sent: Friday, June 05, 2009 12:52 PM
    > To: dita
    > Subject: RE: [dita] referencing a bookmap from a map
    >
    > Don,
    >
    > I've not seen any responses to this.  Can you put it on
    > the agenda for our next meeting?
    >
    > thanks,
    >
    > paul
    >
    > >
    Original Message-----

    > > From: Grosso, Paul [mailto:pgrosso@ptc.com]
    > > Sent: Thursday, 2009 May 28 10:44
    > > To: dita
    > > Subject: [dita] referencing a bookmap from a map
    > >
    > >
    > > Proposal 12055 is clear about what we do in the specialized map to
    > > generic map case and also about the specialized map to specialized
    > > map case, but we're not sure what should happen when a generic map
    > > references a specialized map.
    > >
    > > For example, what should happen in the following case:
    > >
    > > map1
    > > ----
    > >   topicref to bookmap2
    > >
    > > bookmap2
    > > --------
    > >   frontmatter
    > >         booklists
    > >               Toc
    > >   part referencing a concept
    > >         chapter referencing a task
    > >
    > > What are the contexts or roles for the elements in bookmap2?
    > > Unchanged?
    > > Or does the generic topic reference from map1 override the top level
    > > topicrefs in bookmap2 so you end up with something
    > > effectively like the
    > > following for bookmap2:
    > >
    > > bookmap2
    > > --------
    > >   topicref for frontmatter
    > >         booklists
    > >               Toc
    > >   topicref for part referencing a concept
    > >         chapter referencing a task
    > >
    > >
    > > Keeping things unchanged preserves the specialized information from a
    > > bookmap,
    > > but it also allows you to create situations using map references that
    > > you
    > > could not create within a single bookmap (e.g., a chapter within a
    > > chapter or
    > > a part within a topic).
    > >
    > > On the other hand, if the generic topic reference from map1 overrides
    > > the
    > > top level topicrefs in bookmap2, you couldn't create unexpected
    > > situations, but
    > > you lose all of the specialized information from a bookmap because you
    > > more or
    > > less fallback to the lower common denominator of a generic map.
    > >
    > > ---------------------------------------------------------------------
    > > 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
     


  • 6.  Re: [dita] referencing a bookmap from a map

    Posted 06-09-2009 16:25
    On 6/9/09 11:06 AM, "Michael Priestley" 


  • 7.  RE: [dita] referencing a bookmap from a map

    Posted 06-09-2009 21:07
    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
    
    > 


  • 8.  Re: [dita] referencing a bookmap from a map

    Posted 06-09-2009 21:23
    On 6/9/09 4:07 PM, "Bruce Nevin (bnevin)" 


  • 9.  RE: [dita] referencing a bookmap from a map

    Posted 06-09-2009 22:02
    
    
    
    
    
    
    
    
    
    
    
    

    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

     

     

    >



  • 10.  Re: [dita] referencing a bookmap from a map

    Posted 06-09-2009 22:21
    On 6/9/09 5:00 PM, "Ogden, Jeff" 


  • 11.  Re: [dita] referencing a bookmap from a map

    Posted 06-09-2009 22:56

    Hi Eliot,

    As a level-set, here's what the spec currently says about format="ditamap":

    http://docs.oasis-open.org/dita/v1.1/OS/langspec/common/theformatattribute.html
    The linked-to resource is a DITA map. It represents a referenced hierarchy at a position within referencing hierarchy, and a referenced relationship table included outside the referencing hierarchy

    So it does, at least to me, read like an explicit behavior. I'd agree that this should be a default behavior, rather than required. But as a default behavior, I think it should preserve the validity of the referencing map as it aggregates, and not create invalid structures.

    Earlier you wrote:
    >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.


    Actually if you want conref you can't use conref - not unless we allow <map> to nest arbitrarily. Note that the description above says to create the referenced hierarchy at the current position, but any referenced relationship table should be included outside. That preserves the validity of the map (which doesn't allow reltable inside a topicref) in a way that isn't possible with conref.

    >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 agree that when processors aren't treating the mapref as an aggregator there's no need to generalize. My concern is for when it is treated like an aggregator, which is at least the default behavior.

    If someone creates an override processor, or a specialized element with overriding processing, they can do what they want. But by default, I think that a topicref to a bookmap that pulls it into a non-valid context should generalize (ie treat it like an unspecialized map) rather than create an aggregate whole that breaks the constraints of the structural specialization.

    Michael Priestley, Senior Technical Staff Member (STSM)
    Lead IBM DITA Architect
    mpriestl@ca.ibm.com
    http://dita.xml.org/blog/25



    Eliot Kimber <ekimber@reallysi.com>

    06/09/2009 06:20 PM

    To
    "Ogden, Jeff" <jogden@ptc.com>, dita <dita@lists.oasis-open.org>
    cc
    Subject
    Re: [dita] referencing a bookmap from a map





    On 6/9/09 5:00 PM, "Ogden, Jeff" <jogden@ptc.com> wrote:

    > 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