OASIS Darwin Information Typing Architecture (DITA) TC

One use case that uses map to specialized
map references involves several separate “books” each developed
independently and each with their own map.  Each map is a different map specialization.
As an example we might use a bookmap and a learningbookmap.

 

At a later time someone wants to create a
new deliverable that includes two or more of these existing “books”. 
So they use a generic map that references each of the specialized maps that
they want to include, something like this:

 

map

title

topicref to bookmap

topicref to leaningbookmap

 

They might well get two separate
frontmatter and backmatter sections, one for each book and that is fine.

 

If we take approach #2 or approach #4, I
think this case works since the composition process has all of the information
that composition of the separate specialized maps had.

 

If we take approach #3, things don’t
work as well because we lose most of the specialized information contained in
the two specialized maps because those maps are referenced from a generic map. 
And while you might replace the generic map with one of the specialized maps, I
don’t think that will always work unless one of the specialized maps is a
superset of the other or at least supports a subset of the elements used in
both specialized maps.

 

   -Jeff

 

 











From: Ogden, Jeff

Sent: Friday, June 12, 2009 2:31
PM

To: 'dita'

Subject: RE: [dita] referencing a
bookmap from a map



 

I’m not sure we’ve made much
progress on resolving the generic map to specialized map referencing issues.
 

 

Here is my summary from earlier in the
week:

 

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

Since then, Michael has
clarified his proposal (#3), but it is pretty much based on making sure that
the referenced element makes sense in the context of the referenced element,
even if we lose information in the process and even if the elements below the
referenced element don’t make sense in the new context.

 

Eliott’s
proposal (#4) is quite different from Michael’s, and more similar to mine
(#2).

 

Still another approach
(#5) is to simply punt and leave this undefined
in DITA 1.2 much as it was undefined in DITA 1.1 and 1.0. 

 

I’m not sure how best to move toward
a decision, but one possibility is to have a few folks submit use cases and
then ask how well the different proposals work for each. I’ll do one of
those in a separate e-mail message later today or over the weekend.
 I’d encourage others to submit their own use cases.

 

   -Jeff

 

 











From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]

Sent: Tuesday, June 09, 2009 7:41
PM

To: Ogden, Jeff

Cc: dita; Eliot Kimber

Subject: RE: [dita] referencing a
bookmap from a map



 



I think the role of the referencing element is the one thing we're sure
is valid in the referencing context. So we can have a <chapter> element
reference a bookmap, and it becomes a set of chapters; or it can reference an
appendix, and the appendix becomes a chapter. But either way, the semantics of
the referencing element wins over the semantics of the referenced element.


It
does get interesting though in the case here:


http://www.oasis-open.org/committees/download.php/24910/IssueNumber12055.html

>Note: In some cases, preserving the role of the referencing element may
result in out-of-context content. For example, a chapter that references a
>bookmap may pull in <part> elements. Those part elements take on the
role of chapter, but likely contain additional chapter elements. The result in
this >case is implementation specific; processors may treat this as an error
that prevents further processing, issue a warning, or assign new roles to the
>descendants without an error or warning.


That's
still following the rule that the referencing element's semantic wins: the
parts become chapters because the referencing element is a chapter. But the
referenced parts in turn contain chapters, and it's less clear what to do
programmatically that would be safe. Generalizing happens to be safe in this
case, but isn't always going to be safe (eg, what if I'm referencing from a
specialized chapter element that only allows <subchapter> references?).
So I think the recommendation here still holds true - ie that the result is up
to the processor. But it doesn't change the clear guidelines we have for the
simple cases, where the semantic of the referencing element wins every time. 


Maybe
I've been overselling the conref comparison. The key here is that the semantic
of the referencing element is the only semantic we know to be valid in the
current map. If topicref is the referencing element, that's the only thing we
know to be semantically safe. If the reference was done with a <chapter>
element, we'd pull in the target map's contents as <chapter>s. If we
reference with <topicref>, the contents should be pulled in as
<topicref>s.


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
  07:20 PM 
  
  

  

   

    

    
To
    
    

    
Michael Priestley/Toronto/IBM@IBMCA, "Eliot Kimber" <ekimber@reallysi.com> 
    
   
   

    

    
cc
    
    

    
"dita" <dita@lists.oasis-open.org>
    
    
   
   

    

    
Subject
    
    

    
RE: [dita] referencing a bookmap from a map
    
   
  
  
 
  
  

  
 






Michael wrote:

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

 

I realize we are talking about generic map to specialized map
references here, but the above isn’t the behavior that proposal 12055
calls for in the case of a specialized map to a more specialized map reference,
is it?

 

   -Jeff

 

  

 









From: Michael
Priestley [mailto:mpriestl@ca.ibm.com] 

Sent: Tuesday, June 09, 2009 6:56 PM

To: Eliot Kimber

Cc: dita; Ogden, Jeff

Subject: Re: [dita] referencing a bookmap from a map

 



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


I'm saying #2, without bothering to say anything about "bookmap
context"

because that's a processor-specific implementation detail. Either processors

are *obligated* to treat more-specialized topicrefs as generalized to the

level of the referencing topicref (Michael's proposal) or they aren't. If

they aren't, then how they remember what the unspecialized type of a given

topicref is is an implementation detail.


I'm also suggesting that any implementor, e.g., Arbortext, is free to say,

for that implementation, whether a particular case is or isn't meaningful,

so if Editor said "maprefs from <map> to <bookmap> aren't
sensical *to us*"

I would be fine with that. But if it instead "this is the sense it does
make

to us" I would be fine with that too (from a conformance standpoint).


Cheers,


E.


----

 Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.

email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>

office: 610.631.6770 | cell: 512.554.9368

2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403

www.reallysi.com <http://www.reallysi.com>  |
http://blog.reallysi.com

<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>



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

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 

If we feed our existing bookmap processes
a combo map - ie we literally aggregate several of them together, including
multiple backmatters etc. - and we normalize and remove DTDs so there's
no validation issue - do the processes work?

In other words, is there any code in
bookmap that depends on the structural rules of bookmap being followed?
If there are multiple definitions of the book title, for example, does
the code know to take the first one, even though structurally there should
only ever be one? If there are multiple indices, does the index processing
know to look only for index entries within each subsumed bookmap, rather
than the scope of the whole map?

I understand why the use case below
is a nice-to-have - but are we prepared to (re)code every process for specialized
maps to allow for the possibility of aggregation and recursive nesting,
even when explicitly prevented by the specialization? For example, if we
allow <topicref> to <appendix> to retain its <appendix>ness
no matter where we're referencing from, then we are allowing <appendix>
inside <frontmatter>. And <chapter> inside <appendix>.

And if that is ok, then my question
would be - why don't we allow the same arbitrary nesting rule in the DTD?
If we're going to allow reusers to circumvent the content model by reference,
why won't we let them do the same thing without referencing? Either way
we need to add the code to support it, so why the limitation for people
working in just one document?

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/12/2009 02:50 PM




To
"dita" <dita@lists.oasis-open.org>


cc



Subject
RE: [dita] referencing a bookmap from
a map






One use case that uses map
to specialized map references involves several separate “books” each
developed independently and each with their own map.  Each map is
a different map specialization. As an example we might use a bookmap and
a learningbookmap.
 
At a later time someone wants
to create a new deliverable that includes two or more of these existing
“books”.  So they use a generic map that references each of the
specialized maps that they want to include, something like this:
 
map
title
topicref to bookmap
topicref to leaningbookmap
 
They might well get two separate
frontmatter and backmatter sections, one for each book and that is fine.
 
If we take approach #2 or approach
#4, I think this case works since the composition process has all of the
information that composition of the separate specialized maps had.
 
If we take approach #3, things
don’t work as well because we lose most of the specialized information
contained in the two specialized maps because those maps are referenced
from a generic map.  And while you might replace the generic map with
one of the specialized maps, I don’t think that will always work unless
one of the specialized maps is a superset of the other or at least supports
a subset of the elements used in both specialized maps.
 
   -Jeff
 
 



From: Ogden, Jeff 

Sent: Friday, June 12, 2009 2:31 PM

To: 'dita'

Subject: RE: [dita] referencing a bookmap from a map
 
I’m not sure we’ve made much
progress on resolving the generic map to specialized map referencing issues.
 
 
Here is my summary from earlier
in the week:
 
> … 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?
Since then, Michael has clarified
his proposal (#3), but it is pretty much based on making sure that the
referenced element makes sense in the context of the referenced element,
even if we lose information in the process and even if the elements below
the referenced element don’t make sense in the new context.
 
Eliott’s proposal (#4) is
quite different from Michael’s, and more similar to mine (#2).
 
Still another approach (#5)
is to simply punt and leave
this undefined in DITA 1.2 much as it was undefined in DITA 1.1 and 1.0.

 
I’m not sure how best to move
toward a decision, but one possibility is to have a few folks submit use
cases and then ask how well the different proposals work for each. I’ll
do one of those in a separate e-mail message later today or over the weekend.
 I’d encourage others to submit their own use cases.
 
   -Jeff
 
 



From: Michael Priestley [mailto:mpriestl@ca.ibm.com]


Sent: Tuesday, June 09, 2009 7:41 PM

To: Ogden, Jeff

Cc: dita; Eliot Kimber

Subject: RE: [dita] referencing a bookmap from a map
 


I think the role of the referencing element is the one thing we're sure
is valid in the referencing context. So we can have a <chapter> element
reference a bookmap, and it becomes a set of chapters; or it can reference
an appendix, and the appendix becomes a chapter. But either way, the semantics
of the referencing element wins over the semantics of the referenced element.



It does get interesting though in the case here:



http://www.oasis-open.org/committees/download.php/24910/IssueNumber12055.html

>Note: In some cases, preserving the role of the referencing element
may result in out-of-context content. For example, a chapter that references
a >bookmap may pull in <part> elements. Those part elements take
on the role of chapter, but likely contain additional chapter elements.
The result in this >case is implementation specific; processors may
treat this as an error that prevents further processing, issue a warning,
or assign new roles to the >descendants without an error or warning.



That's still following the rule that the referencing element's semantic
wins: the parts become chapters because the referencing element is a chapter.
But the referenced parts in turn contain chapters, and it's less clear
what to do programmatically that would be safe. Generalizing happens to
be safe in this case, but isn't always going to be safe (eg, what if I'm
referencing from a specialized chapter element that only allows <subchapter>
references?). So I think the recommendation here still holds true - ie
that the result is up to the processor. But it doesn't change the clear
guidelines we have for the simple cases, where the semantic of the referencing
element wins every time. 



Maybe I've been overselling the conref comparison. The key here is that
the semantic of the referencing element is the only semantic we know to
be valid in the current map. If topicref is the referencing element, that's
the only thing we know to be semantically safe. If the reference was done
with a <chapter> element, we'd pull in the target map's contents
as <chapter>s. If we reference with <topicref>, the contents
should be pulled in as <topicref>s.



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 07:20 PM






To
Michael Priestley/Toronto/IBM@IBMCA,
"Eliot Kimber" <ekimber@reallysi.com>



cc
"dita" <dita@lists.oasis-open.org>



Subject
RE: [dita] referencing a bookmap from a map

 









Michael wrote: 

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


  

I realize we are talking about generic map to specialized map references
here, but the above isn’t the behavior that proposal 12055 calls for in
the case of a specialized map to a more specialized map reference, is it?


  

   -Jeff 

  

  

 




From: Michael Priestley [mailto:mpriestl@ca.ibm.com] 

Sent: Tuesday, June 09, 2009 6:56 PM

To: Eliot Kimber

Cc: dita; Ogden, Jeff

Subject: Re: [dita] referencing a bookmap from a map

  


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


I'm saying #2, without bothering to say anything about "bookmap context"

because that's a processor-specific implementation detail. Either processors

are *obligated* to treat more-specialized topicrefs as generalized to the

level of the referencing topicref (Michael's proposal) or they aren't.
If

they aren't, then how they remember what the unspecialized type of a given

topicref is is an implementation detail.


I'm also suggesting that any implementor, e.g., Arbortext, is free to say,

for that implementation, whether a particular case is or isn't meaningful,

so if Editor said "maprefs from <map> to <bookmap> aren't
sensical *to us*"

I would be fine with that. But if it instead "this is the sense it
does make

to us" I would be fine with that too (from a conformance standpoint).


Cheers,


E.


----

Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.

email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>

office: 610.631.6770 | cell: 512.554.9368

2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403

www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com

<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>



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

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

On 6/12/09 2:25 PM, "Michael Priestley" 

On 6/12/09 1:50 PM, "Ogden, Jeff" 

>But in fact, as indicated in my note of a few
minutes ago about clarifying

>peer, there is no DITA-defined notion of "publication" nor
is there a way to

>indicate that a given map is only navigation over separate publications
as

>opposed to defining an atomic unit of publication.

The question is what do you want to
happen by default.

By default, currently, a topicref to
another map pulls that map into the processing context. This is not the
only possible result, but it is certainly a possible result. If you do
nothing except create a topicref to another map, and produce output, I
think it is a reasonable default to expect the target map to be pulled
in. It is also perfectly reasonable to override that default.

The question is whether, *by default*,
I should be able to pull in specialized portions of the target map into
contexts *which will break default processing*.

In other words, should the preprocess
step that resolves references across specialized maps allow specialized
content into places where it is not valid?

>In the case where map is only providing navigation
>... 
>That argument alone, is sufficient, I think, to
make it clear that

>disallowing any particular organization of stuff in a map by the spec
would

>be wrong--the sensibleness is entirely a function of the processing

>semantics of the map and not the things included.

You can organize your map any way you want. The question
is, and has been from the start, what to do with the specialized semantics
of the target *when aggregating the content for further processing*. The
fact that other use cases exist is not relevant to this one.

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/12/2009 04:15 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/12/09 1:50 PM, "Ogden, Jeff" <jogden@ptc.com>
wrote:


> One use case that uses map to specialized map references involves

> several separate "books" each developed independently and
each with

> their own map.  Each map is a different map specialization. As
an

> example we might use a bookmap and a learningbookmap.

>

>  

>

> At a later time someone wants to create a new deliverable that includes

> two or more of these existing "books".  So they use
a generic map that

> references each of the specialized maps that they want to include,

> something like this:

>

>  

>

> map

>

> title

>

> topicref to bookmap

>

> topicref to leaningbookmap

>

>  

>

> They might well get two separate frontmatter and backmatter sections,

> one for each book and that is fine.


But in fact this use assumes that the intended (or only allowed) result
is a

single unit of publication.


But in fact, as indicated in my note of a few minutes ago about clarifying

peer, there is no DITA-defined notion of "publication" nor is
there a way to

indicate that a given map is only navigation over separate publications
as

opposed to defining an atomic unit of publication.


In the case where map is only providing navigation, it's hard to argue
that

nesting reference to one bookmap inside a reference to another bookmap
would

be a problem since it's a purely navigation relationship and may simply

indicate a hierarchy (similar to the library navigation trees we had at
the

front of the manuals in the Networking System publications back in my day).


That argument alone, is sufficient, I think, to make it clear that

disallowing any particular organization of stuff in a map by the spec would

be wrong--the sensibleness is entirely a function of the processing

semantics of the map and not the things included.


Cheers,


E.


----

Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.

email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>

office: 610.631.6770 | cell: 512.554.9368

2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403

www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com

<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>



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

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

But I don't think is a case where the spec can have an opinion on default
processing: either generalization is always applied or it's up to the
processor. That says nothing about default processing, or any processing,
only what the effective data values are.

I'm saying that requiring generalization is not the right answer.

The spec can certainly say "processors are welcome to set as their default
processing generalization of more-specialized map components when referenced
in the context of less-specialized map types".

But that's very different from specifying default processing.

On 6/12/09 3:32 PM, "Michael Priestley" 

So with respect to 

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

You are saying that we shouldn't say?
What about the rest of the behaviors prescribed in 12055?

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/12/2009 05:21 PM




To
Michael Priestley/Toronto/IBM@IBMCA


cc
dita <dita@lists.oasis-open.org>,
"Ogden, Jeff" <jogden@ptc.com>


Subject
Re: [dita] referencing a bookmap from
a map






But I don't think is a case where the spec can have
an opinion on default

processing: either generalization is always applied or it's up to the

processor. That says nothing about default processing, or any processing,

only what the effective data values are.


I'm saying that requiring generalization is not the right answer.


The spec can certainly say "processors are welcome to set as their
default

processing generalization of more-specialized map components when referenced

in the context of less-specialized map types".


But that's very different from specifying default processing.


On 6/12/09 3:32 PM, "Michael Priestley" <mpriestl@ca.ibm.com>
wrote:


>> But in fact, as indicated in my note of a few minutes ago about

> clarifying

>> peer, there is no DITA-defined notion of "publication"
nor is there a way

> to

>> indicate that a given map is only navigation over separate publications

> as

>> opposed to defining an atomic unit of publication.

>

> The question is what do you want to happen by default.

>

> By default, currently, a topicref to another map pulls that map into
the

> processing context. This is not the only possible result, but it is

> certainly a possible result. If you do nothing except create a topicref
to

> another map, and produce output, I think it is a reasonable default
to

> expect the target map to be pulled in. It is also perfectly reasonable
to

> override that default.


Here you say "pulls that map in to the processing context"--that
does not,

by itself imply anything about sensibility or validation or the nature
of

that processing, in particular, whether or not the processing treats the
map

as a single effective map or what.


The problem is that the current spec is *seriously underspecified* on this

subject. For example, how does the scope attribute affect this processing,

if at all? The spec is currently silent.


Saying the "target map is pulled in" doesn't say what it means
to be "pulled

in", it only says that the referenced map is processed in the same

"processing context" but we don't say what "processing context"
implies

beyond the rules for key definition *because we can't*.


That is, "in the same processing context" does *not* imply, necessarily,
a

single output result. That seems to be the assumption you are making.


I observe that the language under <mapref> is not consistent with
the

language under format=ditamap:


Mapref: "The hierarchy of the referenced map is merged into the container

map at the position of the reference, and the relationship tables of the

child map are added to the parent map."


Format=ditamap: "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"


These two statements need to be the same or mapref needs to defer entirely

to format=ditamap since it cannot, by itself, change the semantics of

format=ditamap. And since these statements do not unambiguously mean the

same thing, we need to decide which one is correct (if any).


And reading the language of <mapref> I think I have to object to
"merged

into" since that is processing talk. I think it needs to be something
like

"is treated as though it had occurred at the point of reference"
or

something similar (so that the language does not appear to imply a literal

transformation applied to the map).


I think we also need language that clarifies the implication of scope=peer

and scope=external in this case:


- Is peer or external even meaningful?

If they are meaningful:

- Does peer imply key merging?

- Does external imply key merging?


[And I will observe also that as far as I can tell there is no syntax for

one map referencing a key defined in another map that establishes a

separate, independent key namespace (e.g., scope="peer" (maybe)
or

scope="external" (maybe). That's a hole (possibly) in the keyref
design but

it does mean that there's no need to define what it means for one map to

reference a key in another, distinct key space, because it can't happen.


But I would definitely like to have a standard-defined way to reference
one

publication from another publication's map without merging the keys of
the

two maps.

]


> The question is whether, *by default*, I should be able to pull in

> specialized portions of the target map into contexts *which will break

> default processing*.


What is default processing in this context? The Toolkit's implementation
of

bookmap?


The definition of bookmap in the current 1.2 lang spec says nothing about

processing whatsoever. Likewise, the <chapter> element text says
nothing

about it not being meaningful to allow nested chapters (although the content

model does not, of course, allow nested chapters--but without any supporting

prose its impossible to know if that is an arbitrary design decision, a
bug,

or a reflection of a deeply-held conviction that chapters should never
nest

in any possible context.


That is--the language of the current 1.2 draft spec provides little, if
no,

basis for arguing semantics on the basis of processing *because it doesn't

define any* for bookmap.


> In other words, should the preprocess step that resolves references
across

> specialized maps allow specialized content into places where it is
not

> valid?

>

>> In the case where map is only providing navigation

>> ...

>> That argument alone, is sufficient, I think, to make it clear
that

>> disallowing any particular organization of stuff in a map by the
spec

> would

>> be wrong--the sensibleness is entirely a function of the processing

>> semantics of the map and not the things included.

>

> You can organize your map any way you want. The question is, and has
been

> from the start, what to do with the specialized semantics of the target

> *when aggregating the content for further processing*. The fact that
other

> use cases exist is not relevant to this one.

>

> 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/12/2009 04:15 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/12/09 1:50 PM, "Ogden, Jeff" <jogden@ptc.com>
wrote:

>

>> One use case that uses map to specialized map references involves

>> several separate "books" each developed independently
and each with

>> their own map.  Each map is a different map specialization.
As an

>> example we might use a bookmap and a learningbookmap.

>>

>>

>>

>> At a later time someone wants to create a new deliverable that
includes

>> two or more of these existing "books".  So they
use a generic map that

>> references each of the specialized maps that they want to include,

>> something like this:

>>

>>

>>

>> map

>>

>> title

>>

>> topicref to bookmap

>>

>> topicref to leaningbookmap

>>

>>

>>

>> They might well get two separate frontmatter and backmatter sections,

>> one for each book and that is fine.

>

> But in fact this use assumes that the intended (or only allowed) result
is

> a

> single unit of publication.

>

> But in fact, as indicated in my note of a few minutes ago about clarifying

> peer, there is no DITA-defined notion of "publication" nor
is there a way

> to

> indicate that a given map is only navigation over separate publications
as

> opposed to defining an atomic unit of publication.

>

> In the case where map is only providing navigation, it's hard to argue

> that

> nesting reference to one bookmap inside a reference to another bookmap

> would

> be a problem since it's a purely navigation relationship and may simply

> indicate a hierarchy (similar to the library navigation trees we had
at

> the

> front of the manuals in the Networking System publications back in
my

> day).

>

> That argument alone, is sufficient, I think, to make it clear that

> disallowing any particular organization of stuff in a map by the spec

> would

> be wrong--the sensibleness is entirely a function of the processing

> semantics of the map and not the things included.

>

> Cheers,

>

> E.

>

> ----

> Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.

> email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>

> office: 610.631.6770 | cell: 512.554.9368

> 2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403

> www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com

> <http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>

>

>

> ---------------------------------------------------------------------

> 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

>

>


----

Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.

email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>

office: 610.631.6770 | cell: 512.554.9368

2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403

www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com

<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>

Earlier Michael wrote:

 

> So with respect to

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


> You are saying that we shouldn't say? What about the rest of the behaviors
prescribed in 12055?




 

I wrote the paragraph quoted by Michael
above, but I’m guessing that his questions are more directed to Eliot.

 

I want the DTIA TC to make our
expectations explicit when a generic map references a specialized map (or a
generic topicref references a specialized topicref).  I hope we
don’t end up just saying that this behavior is undefined or
implementation dependent, but even that would be better than just being silent
or ambiguous about what the expectation is.

 

I am happy with the behaviors prescribed
in 12055.

 

I don’t think that the behaviors
prescribed in 12055 always give results that conform to the expectations of the
referencing map’s DTD or schema. And that is fine with me.  But in
my view this weakens the arguments that say that we should always generalize
the top level elements in the generic to specialized case to ensure that they
conform.

 

So, I am not in agreement with either Eliot’s
or Michael’s arguments (proposals #3 and #4) and continue to think that
proposal #2 (included again at the end of this note) is a good approach.  

 

Proposal #2 does set some expectations and
makes it at least possible for users to expect similar results from one
implementation to another. Proposal #2 maintains the more detailed information
from the specialized maps and so would allow for, but not require,
generalization by a processor that wanted or needed to do that. It is certainly
the case that unexpected combinations might not produce exactly the results the
user is looking for, but they should produce some results and I would hope that
it would be fairly easy for users to customize existing processors to do what
they want in such situations. I think proposal 12055 already sets the stage for
this in the specialized to specialized map case and so extending this to the
generic to specialized map case is a fairly natural solution. It is certainly
pretty easy to explain (specialized trumps generic).

 

It is possible that my thinking on this is
too much influenced by the implementation we have here at PTC/Arbortext. 
Or perhaps the PTC/Arbortext approach is a good one and can help us figure out
what we want to do here.  Let me describe it and you can decide for
yourselves:

 

The PTC/Arbortext DITA support is divided
into three parts:


 
The syntax called for and
     enforced by the DITA DTDs and XML schemas.
 
The processing semantics called
     for or allowed for by the DITA specification.
 
The styling that is applied to
     the processed result to yield the final composed output.


 

With this approach we’ve divided
processing into two parts, “processing” and “styling”.
This division is admittedly somewhat arbitrary, but useful never-the-less.

 

Processing sets the stage for styling by
implementing the requirements of the DITA specification and otherwise organizing
information so that styling can be easily applied.

 

Styling is mostly about what the output
looks like. It includes those things that the DITA specification does not and
should not mandate such as font family, type, size, color, paper or output
size, number of columns, …. Users should be able to easily customize the
default styling to achieve the results they desire.  Exactly how users do
this will vary from implementation to implementation.

 

Users have a great deal of control over “styling”
and little or no control over “processing” (or at least not much
control unless they are willing to enter into the world of programming).

 

And my thinking on the question of references
from generic to specialized maps has us maintaining as much information as we
can as part of the “processing” steps so that that information
is available during the “styling” steps.  This allows users to
make their own choices about what it is they do or don’t expect and how
they want to “style” any unexpected cases.

 

   -Jeff

 

 











From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]

Sent: Friday, June 12, 2009 5:32
PM

To: Eliot Kimber

Cc: dita; Ogden, Jeff

Subject: Re: [dita] referencing a
bookmap from a map



 



So with respect to


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


You are saying that we shouldn't say? What about the rest of the behaviors
prescribed in 12055?


Michael Priestley, Senior Technical Staff Member (STSM)

Lead IBM DITA Architect

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25 

The following is what I labeled proposal #2:

From: Ogden, Jeff
[mailto:jogden@ptc.com]

Sent: Tuesday, June 09, 2009 10:34
AM

To: dita

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

 

Hi Jeff,

For others following the discussion:
http://www.oasis-open.org/committees/download.php/24910/IssueNumber12055.html

>I want the DITA TC to make
our expectations explicit when a generic map references a 
>specialized map (or a generic
topicref references a specialized topicref).  I hope we don’t 
>end up just saying that
this behavior is undefined or implementation dependent, but even 
>that would be better than
just being silent or ambiguous about what the expectation is.
> 
>I am happy with the behaviors
prescribed in 12055.
> 
>I don’t think that the
behaviors prescribed in 12055 always give results that conform to 
>the expectations of the
referencing map’s DTD or schema. And that is fine with me.  
>But in my view this weakens
the arguments that say that we should always generalize 
>the top level elements
in the generic to specialized case to ensure that they conform.

I don't think it does weaken the argument.
We can always define specialized behaviors for specialized elements. The
question is what is the safest behavior to define as the default for unspecialized
elements that have no other behavior.

>And my thinking on the
question of references from generic to specialized maps has us 
>maintaining as much information
as we can as part of the “processing” steps so that that 
>information is available
during the “styling” steps.  This allows users to make their own

>choices about what it is
they do or don’t expect and how they want to “style” any 
>unexpected cases.

Returning to the questions of my previous
notes - if I fed to your processors a normalized DITA map that consisted
of three concatenated bookmaps, each with their own indexing and TOC behaviors
defined, how would your processors handle them? That's behavior that is
certainly not defined in the spec, because it is a content model that is
not achievable by following the spec. 

I respect the instinct to preserve semantics
rather than discard them. However, if the preserved semantics can trigger
processing rules that will result in broken output, it seems irresponsible
to preserve those semantics without some kind of indication from the user
that specialized behavior is being engaged. An indication like, for example,
the creation of a specialized referencing element.

Michael Priestley, Senior Technical
Staff Member (STSM)

Lead IBM DITA Architect

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25

Michael asked:

> Returning to the questions of my previous notes - if I
fed to your processors a normalized 

> DITA map that consisted of three concatenated bookmaps,
each with their own indexing and 

> TOC behaviors defined, how would your processors handle
them? That's behavior that is 

> certainly not defined in the spec, because it is a
content model that is not achievable by 

> following the spec.




The simple answer is that it works just fine.  The
example I gave in an earlier message was real.

 

The more complicated answer is that if the specialized
topicref elements are “styled”, then we use them as is.  If
they aren’t styled, we generalize back to more basic elements if the base
element is styled and so on until we find a styled element or we run out of
base elements.  This is driven by the styled or unstyled nature of the
elements and not based on which element is the referencing and which is the
referenced element. We use this same approach for the specialized map to
specialized map case and for the generic map to specialized map case. In fact
we use this approach for styling all elements from maps or topics.  The
key thing is that we start out with the more specialized elements and only work
our way back to the more general elements as necessary. Of course it doesn’t
work if you start with a generalized element to begin with.

 

   -Jeff

 

 











From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]

Sent: Monday, June 15, 2009 7:42
PM

To: Ogden, Jeff

Cc: dita

Subject: RE: [dita] referencing a
bookmap from a map



 



Hi Jeff,


For
others following the discussion:

http://www.oasis-open.org/committees/download.php/24910/IssueNumber12055.html


>I want the DITA TC to make our expectations explicit when
a generic map references a 

>specialized map (or a generic topicref references a
specialized topicref).  I hope we don’t 

>end up just saying that this behavior is undefined or
implementation dependent, but even 

>that would be better than just being silent or ambiguous
about what the expectation is.

> 

>I am happy with the behaviors prescribed in 12055.

> 

>I don’t think that the behaviors prescribed in
12055 always give results that conform to 

>the expectations of the referencing map’s DTD or
schema. And that is fine with me.  

>But in my view this weakens the arguments that say that
we should always generalize 

>the top level elements in the generic to specialized case
to ensure that they conform.


I
don't think it does weaken the argument. We can always define specialized
behaviors for specialized elements. The question is what is the safest behavior
to define as the default for unspecialized elements that have no other
behavior.


>And my thinking on the question of references from
generic to specialized maps has us 

>maintaining as much information as we can as part of the
“processing” steps so that that 

>information is available during the “styling”
steps.  This allows users to make their own 

>choices about what it is they do or don’t expect
and how they want to “style” any 

>unexpected cases.


Returning
to the questions of my previous notes - if I fed to your processors a
normalized DITA map that consisted of three concatenated bookmaps, each with
their own indexing and TOC behaviors defined, how would your processors handle
them? That's behavior that is certainly not defined in the spec, because it is
a content model that is not achievable by following the spec. 


I
respect the instinct to preserve semantics rather than discard them. However,
if the preserved semantics can trigger processing rules that will result in
broken output, it seems irresponsible to preserve those semantics without some
kind of indication from the user that specialized behavior is being engaged. An
indication like, for example, the creation of a specialized referencing
element.


Michael
Priestley, Senior Technical Staff Member (STSM)

Lead IBM DITA Architect

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25

Hi Jeff,

Was this the earlier example in question?

map
title
topicref to bookmap
topicref to leaningbookmap
 
It didn't explicitly address TOC and
index behaviors, so I'm going to poke a little more. Is your indexing process
already scoping by containing element (ie if the index is part of the learningbookmap,
then it shouldn't include index entries for bookmap, even if they're part
of the same map)? Or is the indexing process resolved before the topicrefs
are used to combine the hierarchy?

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/15/2009 10:50 PM




To
Michael Priestley/Toronto/IBM@IBMCA


cc
"dita" <dita@lists.oasis-open.org>


Subject
RE: [dita] referencing a bookmap from
a map






Michael asked:
> Returning to the questions of my previous
notes - if I fed to your processors a normalized 
> DITA map that consisted of three concatenated
bookmaps, each with their own indexing and 
> TOC behaviors defined, how would your
processors handle them? That's behavior that is 
> certainly not defined in the spec, because
it is a content model that is not achievable by 
> following the spec.


The simple answer is that it works just fine.
 The example I gave in an earlier message was real.
 
The more complicated answer is that if the
specialized topicref elements are “styled”, then we use them as is.  If
they aren’t styled, we generalize back to more basic elements if the base
element is styled and so on until we find a styled element or we run out
of base elements.  This is driven by the styled or unstyled nature
of the elements and not based on which element is the referencing and which
is the referenced element. We use this same approach for the specialized
map to specialized map case and for the generic map to specialized map
case. In fact we use this approach for styling all elements from maps or
topics.  The key thing is that we start out with the more specialized
elements and only work our way back to the more general elements as necessary.
Of course it doesn’t work if you start with a generalized element to begin
with.
 
   -Jeff
 
 



From: Michael Priestley [mailto:mpriestl@ca.ibm.com]


Sent: Monday, June 15, 2009 7:42 PM

To: Ogden, Jeff

Cc: dita

Subject: RE: [dita] referencing a bookmap from a map
 


Hi Jeff,



For others following the discussion:


http://www.oasis-open.org/committees/download.php/24910/IssueNumber12055.html



>I want the DITA TC to make our expectations explicit when a generic
map references a

>specialized map (or a generic topicref references a specialized topicref).
 I hope we don’t

>end up just saying that this behavior is undefined or implementation
dependent, but even

>that would be better than just being silent or ambiguous about what
the expectation is. 

>

>I am happy with the behaviors prescribed in 12055.


>

>I don’t think that the behaviors prescribed in 12055 always give results
that conform to

>the expectations of the referencing map’s DTD or schema. And that
is fine with me.   

>But in my view this weakens the arguments that say that we should always
generalize

>the top level elements in the generic to specialized case to ensure
that they conform.



I don't think it does weaken the argument. We can always define specialized
behaviors for specialized elements. The question is what is the safest
behavior to define as the default for unspecialized elements that have
no other behavior.



>And my thinking on the question of references from generic to specialized
maps has us

>maintaining as much information as we can as part of the “processing”
steps so that that

>information is available during the “styling” steps.  This allows
users to make their own

>choices about what it is they do or don’t expect and how they want
to “style” any

>unexpected cases.



Returning to the questions of my previous notes - if I fed to your processors
a normalized DITA map that consisted of three concatenated bookmaps, each
with their own indexing and TOC behaviors defined, how would your processors
handle them? That's behavior that is certainly not defined in the spec,
because it is a content model that is not achievable by following the spec.




I respect the instinct to preserve semantics rather than discard them.
However, if the preserved semantics can trigger processing rules that will
result in broken output, it seems irresponsible to preserve those semantics
without some kind of indication from the user that specialized behavior
is being engaged. An indication like, for example, the creation of a specialized
referencing element.



Michael Priestley, Senior Technical Staff Member (STSM)

Lead IBM DITA Architect

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25

The programming domain includes <syntaxdiagram> 
and its children, such as <kwd> and <var> for documenting programming languages. The 
software domain includes alternative elements such as <keyword> and 
<varname> for documenting software products. A CLI is a software product 
that looks like a programming language, bridging 
the two domains. 

 
The syntax of a CLI command documented in 
<reference> using <syntaxdiagram> can be reused entirely or in part 
in various children of <concept> and <task> (albeit not in 
<cmd>). 
 
In a complex CLI, the initial sequence of 
<kwd> elements is documented as a "command name". For example, there are 
too many show commands to document as a single command, so they 
are documented as show x, show y, 
show z, show a b, show p q r, 
etc. These are referred to and linked elsewhere by these complex "command 
names".
 
The difficulty is how to  refer to such a "command 
name" outside of <syntaxdiagram> by reusing those children of 
<syntaxdiagram> that are comprised in it, e.g.  
<kwd>show</kwd></sep><kwd>p</kwd></sep><kwd>q</kwd></sep><kwd>r</kwd>. 

 
Since they are grouped together for all instances of 
that "command name" the natural inclination is to put them in <groupcomp> 
or <groupseq>, but those elements are valid only in <syntaxdiagram> 
or one of its children. 
 
Outside of <syntaxdiagram> the elements that 
comprise the "command name" can be grouped in <synph>, but <synph> 
is not valid in <syntaxdiagram> so the advantages of reuse are 
lost.
 
There are other complications, but this is the heart of 
the matter so I won't burden this note with more 
detail.
 
Surely, this has arisen before. Is there a ready 
solution? Or is there a need to add a grouping element to <syntaxdiagram> 
that can be reused widely?
 
    
/Bruce

One way to approach this issue is to assume that the semantics are simpler in task and in concept than they are in syntax diagram.

In the context of syntax diagram, the semantic goal is to delineate the rules for command usage.

In the context of task, the semantic goal is to direct the reader use a command for a specific purpose. Here, the nuances of command usage are unimportant and--except for varname--can be ignored. For example:

<cmd>Determine the size of the file by entering <cmdname>ls -l</cmdname> <varname>file-name</varname>.</cmd>

The fact that '-l' is an option for the 'ls' command is irrelevant to the reader in this context; therefore that markup can be omitted. Using <option> in this context would be similar to me asking a
 waiter for a glass of H2O instead of asking for a glass of water. If you accept the premise that semantics can vary somewhat among contexts, you may find that cmdname and varname are sufficient for documenting tasks in a CLI environment. I qualify this with 'may' because you could be dealing with something that is inherently complex and does not lend itself to this sort of simplication.

In the context of concept, I can make an argument similar to that for task. In my experience, cmdname is not used nearly as often in concept as it is in task; and, when it is, there is an excellent chance that the concept contains one or more embedded tasks.
 
Bob Thomas

+1 720 201 8260


From: Bruce Nevin (bnevin) <bnevin@cisco.com>
To: dita <dita@lists.oasis-open.org>
Sent: Tuesday, June 16, 2009 6:20:02 AM
Subject: [dita] CLI bridges sw and pr domains




 

The programming domain includes <syntaxdiagram> 
and its children, such as <kwd> and <var> for documenting programming languages. The 
software domain includes alternative elements such as <keyword> and 
<varname> for documenting software products. A CLI is a software product 
that looks like a programming language, bridging 
the two domains. 

 
The syntax of a CLI command documented in 
<reference> using <syntaxdiagram> can be reused entirely or in part 
in various children of <concept> and <task> (albeit not in 
<cmd>). 
 
In a complex CLI, the initial sequence of 
<kwd> elements is documented as a "command name". For example, there are 
too many show commands to document as a single command, so they 
are documented as show x, show y, 
show z, show a b, show p q r, 
etc. These are referred to and linked elsewhere by these complex "command 
names".
 
The difficulty is how to  refer to such a "command 
name" outside of <syntaxdiagram> by reusing those children of 
<syntaxdiagram> that are comprised in it, e.g.  
<kwd>show</kwd></sep><kwd>p</kwd></sep><kwd>q</kwd></sep><kwd>r</kwd>. 

 
Since they are grouped together for all instances of 
that "command name" the natural inclination is to put them in <groupcomp> 
or <groupseq>, but those elements are valid only in <syntaxdiagram> 
or one of its children. 
 
Outside of <syntaxdiagram> the elements that 
comprise the "command name" can be grouped in <synph>, but <synph> 
is not valid in <syntaxdiagram> so the advantages of reuse are 
lost.
 
There are other complications, but this is the heart of 
the matter so I won't burden this note with more 
detail.
 
Surely, this has arisen before. Is there a ready 
solution? Or is there a need to add a grouping element to <syntaxdiagram> 
that can be reused widely?
 
    
/Bruce

That foregoes 
reuse.
 
Our users have the expectation 
of seeing the command syntax in a task step. If they need more information about 
how to use the command or the significance of keywords and arguments (especially 
optional ones), they go to the reference doc, but they typically expect only to 
need a local reminder. Hence, the need of verbatim reuse.
 
For content maintenance, we want 
to be able to find every occurrence of a given "command name", hence the need 
for a "command name" outside as well as inside <syntaxdiagram>, and a 
further motivation for reuse. Likewise for linking, e.g. automatic creation of 
links to the reference document.
 
I proposed putting <synph> 
(or an element specialized from it) in front of <syntaxdiagram> and the 
following keywords and arguments & their groups into <syntaxdiagram>. 
It was objected that this breaks the intended semantics of 
<syntaxdiagram>, but it is the best compromise I have come up with so far. 
<synph> can go in <refsyn> as well as in many other places in all 
topic types. 
 
<synph> does not admit the 
<group*> elements. This could cause a problem for this solution. Bear in 
mind the way that complex command families are broken out into 'as-documented' 
commands, each with a more or less complex 'command name'. In the nature of 
software development, a 'command name' can be interrupted by variables which 
must be part of syntax but are not rendered when the 'command name' is cited or 
referred to elsewhere. There is nothing to prevent a software developer from 
interrupting a 'command name' with a keyword-variable pair or other group, and 
these can be optional. 
 
Ability to use <groupcomp> 
or <groupseq> over the range in which <synph> is valid would solve 
the problem.
 
Alternatively, we could just not 
use <syntaxdiagram>. I am reluctant to endorse the 
logical line of argument from there that this part of DITA was a mistake and 
should be deprecated. XML is about semantics with the details of format 
relegated to rendering, after all.
 
    /Bruce



  

  

  From: Bob Thomas 
  [mailto:bob.thomas@tagsmiths.com]
Sent: Tuesday, June 16, 2009 
  11:00 AM
To: dita
Subject: Re: [dita] CLI bridges sw and 
  pr domains


  

  
One way 
  to approach this issue is to assume that the semantics are simpler in task and 
  in concept than they are in syntax diagram.

In the context of syntax 
  diagram, the semantic goal is to delineate the rules for command 
  usage.

In the context of task, the semantic goal is to direct the 
  reader use a command for a specific purpose. Here, the nuances of command 
  usage are unimportant and--except for varname--can be ignored. For 
  example:

<cmd>Determine the size of the file by entering 
  <cmdname>ls -l</cmdname> 
  <varname>file-name</varname>.</cmd>

The fact that 
  '-l' is an option for the 'ls' command is irrelevant to the reader in this 
  context; therefore that markup can be omitted. Using <option> in this 
  context would be similar to me asking a waiter for a glass of H2O instead of 
  asking for a glass of water. If you accept the premise that semantics can vary 
  somewhat among contexts, you may find that cmdname and varname are sufficient 
  for documenting tasks in a CLI environment. I qualify this with 'may' because 
  you could be dealing with something that is inherently complex and does not 
  lend itself to this sort of simplication.

In the context of concept, I 
  can make an argument similar to that for task. In my experience, cmdname is 
  not used nearly as often in concept as it is in task; and, when it is, there 
  is an excellent chance that the concept contains one or more embedded 
  tasks.

  
 
Bob Thomas

+1 720 201 8260

  


  


  

  

  From: Bruce Nevin (bnevin) 
  <bnevin@cisco.com>
To: 
  dita <dita@lists.oasis-open.org>
Sent: Tuesday, June 16, 2009 6:20:02 
  AM
Subject: [dita] CLI 
  bridges sw and pr domains


  
The programming domain includes 
  <syntaxdiagram> and its children, such as <kwd> and 
  <var> for documenting programming 
  languages. The software domain includes alternative elements such as 
  <keyword> and <varname> for documenting software products. A CLI 
  is a software product that looks like a programming language, bridging the two domains. 
  
 
  
The syntax of a CLI command documented in 
  <reference> using <syntaxdiagram> can be reused entirely or in 
  part in various children of <concept> and <task> (albeit not in 
  <cmd>). 
  
 
  
In a complex CLI, the initial sequence of 
  <kwd> elements is documented as a "command name". For example, there are 
  too many show commands to document as a single command, so 
  they are documented as show x, show y, 
  show z, show a b, show p q 
  r, etc. These are referred to and linked elsewhere by these 
  complex "command names".
  
 
  
The difficulty is how to  refer to such a 
  "command name" outside of <syntaxdiagram> by reusing those children of 
  <syntaxdiagram> that are comprised in it, e.g.  
  <kwd>show</kwd></sep><kwd>p</kwd></sep><kwd>q</kwd></sep><kwd>r</kwd>. 
  
  
 
  
Since they are grouped together for all instances of 
  that "command name" the natural inclination is to put them in 
  <groupcomp> or <groupseq>, but those elements are valid only in 
  <syntaxdiagram> or one of its children. 
  
  
 
  
Outside of <syntaxdiagram> the elements that 
  comprise the "command name" can be grouped in <synph>, but <synph> 
  is not valid in <syntaxdiagram> so the advantages of reuse are 
  lost.
  
 
  
There are other complications, but this is the heart 
  of the matter so I won't burden this note with more 
  detail.
  
 
  
Surely, this has arisen before. Is there a ready 
  solution? Or is there a need to add a grouping element to 
  <syntaxdiagram> that can be reused widely?
  
 
  
    
  /Bruce

Yes, that was the example.

 

How the TOC and the index look are a
styling issues and so the user can set this up to be scoped or not.  Processing
just sets the stage to make that possible.

 

    -Jeff

 

 











From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]

Sent: Monday, June 15, 2009 11:34
PM

To: Ogden, Jeff

Cc: dita

Subject: RE: [dita] referencing a
bookmap from a map



 



Hi Jeff,


Was
this the earlier example in question?


map

title

topicref to bookmap

topicref to leaningbookmap

 

It
didn't explicitly address TOC and index behaviors, so I'm going to poke a
little more. Is your indexing process already scoping by containing element (ie
if the index is part of the learningbookmap, then it shouldn't include index
entries for bookmap, even if they're part of the same map)? Or is the indexing
process resolved before the topicrefs are used to combine the hierarchy?


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/15/2009 10:50 PM 
  
  

  

   

    

    
To
    
    

    
Michael Priestley/Toronto/IBM@IBMCA
    
    
   
   

    

    
cc
    
    

    
"dita"
    <dita@lists.oasis-open.org> 
    
   
   

    

    
Subject
    
    

    
RE: [dita] referencing a bookmap from a map
    
   
  
  
 
  
  

  
 






Michael asked:

> Returning
to the questions of my previous notes - if I fed to your processors a
normalized 

>
DITA map that consisted of three concatenated bookmaps, each with their own
indexing and 

>
TOC behaviors defined, how would your processors handle them? That's behavior
that is 

>
certainly not defined in the spec, because it is a content model that is not
achievable by 

>
following the spec.



The
simple answer is that it works just fine.  The example I gave in an
earlier message was real.

 

The
more complicated answer is that if the specialized topicref elements are
“styled”, then we use them as is.  If they aren’t
styled, we generalize back to more basic elements if the base element is styled
and so on until we find a styled element or we run out of base elements.
 This is driven by the styled or unstyled nature of the elements and not
based on which element is the referencing and which is the referenced element.
We use this same approach for the specialized map to specialized map case and
for the generic map to specialized map case. In fact we use this approach for
styling all elements from maps or topics.  The key thing is that we start
out with the more specialized elements and only work our way back to the more
general elements as necessary. Of course it doesn’t work if you start
with a generalized element to begin with.

 

 
 -Jeff

 

  

 









From: Michael
Priestley [mailto:mpriestl@ca.ibm.com] 

Sent: Monday, June 15, 2009 7:42 PM

To: Ogden, Jeff

Cc: dita

Subject: RE: [dita] referencing a bookmap from a map

 



Hi Jeff,



For others following the discussion: 

http://www.oasis-open.org/committees/download.php/24910/IssueNumber12055.html



>I want the DITA TC to make our expectations explicit when a generic map
references a

>specialized map (or a generic topicref references a specialized topicref).
 I hope we don’t

>end up just saying that this behavior is undefined or implementation
dependent, but even

>that would be better than just being silent or ambiguous about what the
expectation is. 

>

>I am happy with the behaviors prescribed in 12055. 

>

>I don’t think that the behaviors prescribed in 12055 always give
results that conform to

>the expectations of the referencing map’s DTD or schema. And that is
fine with me.   

>But in my view this weakens the arguments that say that we should always
generalize

>the top level elements in the generic to specialized case to ensure that
they conform.



I don't think it does weaken the argument. We can always define specialized
behaviors for specialized elements. The question is what is the safest behavior
to define as the default for unspecialized elements that have no other
behavior.



>And my thinking on the question of references from generic to specialized
maps has us

>maintaining as much information as we can as part of the
“processing” steps so that that

>information is available during the “styling” steps.  This
allows users to make their own

>choices about what it is they do or don’t expect and how they want to
“style” any

>unexpected cases.



Returning to the questions of my previous notes - if I fed to your processors a
normalized DITA map that consisted of three concatenated bookmaps, each with
their own indexing and TOC behaviors defined, how would your processors handle
them? That's behavior that is certainly not defined in the spec, because it is
a content model that is not achievable by following the spec. 



I respect the instinct to preserve semantics rather than discard them. However,
if the preserved semantics can trigger processing rules that will result in
broken output, it seems irresponsible to preserve those semantics without some
kind of indication from the user that specialized behavior is being engaged. An
indication like, for example, the creation of a specialized referencing
element.



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> wrote
on 06/16/2009 10:50:19 AM:


> Yes, that was the example.
>  
> How the TOC and the index look are a styling
issues and so the user

> can set this up to be scoped or not.  Processing just sets the
stage

> to make that possible.


Just to make sure I understand: your existing indexing process takes a
parameter from the user that defines the scope of the index? (the current
book, the current map, the highest-level referencing map...). 

Or by user setting this up do you mean custom coding?

What happens by default? In other words, if I have
two indexlists in two bookmaps that are pulled together into one map, are
the indexlists scoped by default, or not?

Michael Priestley

Comments below.

 

   -Jeff

 











From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]

Sent: Tuesday, June 16, 2009 11:05
AM

To: Ogden, Jeff

Cc: dita

Subject: RE: [dita] referencing a
bookmap from a map



 



"Ogden,
Jeff" <jogden@ptc.com> wrote on 06/16/2009 10:50:19 AM:


> Yes, that was the example.

>  

> How the
TOC and the index look are a styling issues and so the user 

> can set this up to be scoped or not.
 Processing just sets the stage

> to make that possible.



Just to make sure I understand: your existing
indexing process takes a parameter from the user that defines the scope of the
index? (the current book, the current map, the highest-level referencing
map...). 


Or by user
setting this up do you mean custom coding?




One of the PTC products is Arbortext/Styler. 
Styler allows users to specify how documents are styled, how pages are formatted,
and lots of other things.  What is or isn’t included in a TOC or an
index, what they look like, and so on are among the things that can be
specified using Styler.

 

So it isn’t as simple as “takes
a parameter”, but it doesn’t require coding, not even FOSI/FO/XSL coding.

 



What
happens by default? In other words, if I have two indexlists in two bookmaps
that are pulled together into one map, are the indexlists scoped by default, or
not?

 

What happens by default shouldn’t
matter to the DITA specification.  The 1.1 specification is entirely silent
about these sorts of details. You can sort of guess from the names and some of
the element descriptions, but that is all you are doing. I think the 1.2
specification should remain silent on these sorts of details.

 

The key things are that something “reasonable”
happen and that it be possible/easy to customize things so something different
happens if that is desired.  Where what is “reasonable” is
something defined by an implementation or by a user and not something that is mandated
by the specification beyond possibly the vaguest statements such as the ones we’ve
made for other elements (lists should look like lists, paragraphs like
paragraphs, and by extension TOCs like TOCs and indexes like indexes).

 

I think the question we need to answer is
what should processing allow? 

 

I think I could live with your approach,
Michael, if you were to soften it to be something like “processors MAY
generalize” rather than “processors MUST generalize”.

 

And I think the problems we are having
here are similar to other problems we’ve had with the DITA specification,
that we are trying to set things up using our existing syntax when we need a
way for users to specify what it is that they want rather than having that
implied.  So topicref  format=”ditamap” href=”something.ditamap” context=”chapter” might do the trick (someone can come up with a better
name than context.  Or even lockcontext={ “yes” | “no”
} or context={ “override” | “preserve” }.  But
these aren’t things that we can resolve for DITA 1.2.

 

Michael
Priestley

>What happens by default
shouldn’t matter to the DITA specification.  The 1.1 specification
is 
>entirely silent about these
sorts of details. You can sort of guess from the names and some 
>of the element descriptions,
but that is all you are doing. I think the 1.2 specification 
>should remain silent on
these sorts of details.
 
So what is 12055 doing? Are those required
behaviors, or just suggested, or something else?

To clarify:

- I'm suggesting behavior only for aggregating
processes - not every possible map process
- I'm suggesting behavior that would
be a default, not a requirement. I'd actually be happy with being parallel
to whatever strength we put behind 12055. Just as long as we're consistent.

- as Robert Anderson noted, if we're
going to specify that a <chapter> reference to a bookmap should resolve
into a set of <chapter> references to the bookmap's parts, then we
should have the same level of specification for what  a <topicref>
does (and I think it should do something parallel)
- otherwise, how does a user get rid
of semantics that don't make sense for the reusing context? for example,
a writer reusing a bookmap into an Eclipse TOC who doesn't want "chapter
xxx" generated.

Michael Priestley, Senior Technical
Staff Member (STSM)

Lead IBM DITA Architect

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25

Comments below.

 

   -Jeff

 











From: Michael Priestley
[mailto:mpriestl@ca.ibm.com]

Sent: Tuesday, June 16, 2009 12:12
PM

To: Ogden, Jeff

Cc: dita

Subject: RE: [dita] referencing a
bookmap from a map



 



>What happens by default shouldn’t
matter to the DITA specification.  The 1.1 specification is 

>entirely silent about these sorts of details. You can
sort of guess from the names and some 

>of the element descriptions, but that is all you are
doing. I think the 1.2 specification 

>should remain silent on these sorts of details.

 

So
what is 12055 doing? Are those required behaviors, or just suggested, or
something else?




I’m not sure.  I think of it as
a requirement, that if you use a chapter to reference a topicref that the
topicref MUST be treated as a chapter.

 

But 12055 allows for exceptions, but doesn’t
say how exceptions are defined or recognized or even who makes the exceptions (the
specification author, the DTD author, the processing implementer, the map
author, …). So what is a requirement that allows exceptions? Is that
still a requirement or a suggestion or something else? I have no idea.



To clarify:


-
I'm suggesting behavior only for aggregating processes - not every possible map
process 

 

I understand and agree.



- I'm suggesting behavior that would be a default, not
a requirement.

 

I don’t know what this means.  Can
a vendor deliver non-default behavior out of the box?  Is it just that the
default behavior has to be available somehow upon request?

 

Or to move this into standards language is
this something that is required (MUST), strongly recommended (SHOULD), or
allowed (MAY)?

 

 

 I'd actually be happy with being parallel to
whatever strength we put behind 12055. Just as long as we're consistent. 

-
as Robert Anderson noted, if we're going to specify that a <chapter>
reference to a bookmap should resolve into a set of <chapter> references
to the bookmap's parts, then we should have the same level of specification for
what  a <topicref> does (and I think it should do something
parallel) 

 

I usually push for consistency. 12055
doesn’t directly address this case and so we would be consistent if we
said that specialized topic references override generic topic references. And I
think that that gives a better result than saying that the referencing topic
reference override the referenced topic reference.



- otherwise, how does a user get rid of semantics that
don't make sense for the reusing context? for example, a writer reusing a
bookmap into an Eclipse TOC who doesn't want "chapter xxx" generated.


 

Going with the referencing overrides
referenced approach doesn’t answer the question. You still need to ask “how
does a user get rid of semantics that don’t make sense for the reusing
context? For example, a writer reusing a bookmap into an Eclipse TOC that does want “chapter xxx”
generated.”

 

We’ve got two choices (wants vs. doesn’t
want or overrides vs. doesn’t override) and we seem to need to pick one
or the other.  Either way we are left with the same question, how does an
author pick the other choice. One solution is to provide an explicit way for
the user to make the choice.  The other way is to define a set of rules
that effectively says that it isn’t reasonable to make the other choice
and so we won’t allow it or more likely that we won’t make it easy.



Michael Priestley, Senior Technical Staff Member (STSM)

Lead IBM DITA Architect

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25

Hi Jeff,

>We’ve got two choices (wants
vs. doesn’t want or overrides vs. doesn’t override) and we seem to need

>to pick one or the other.
 Either way we are left with the same question, how does an author
pick 
>the other choice. One solution
is to provide an explicit way for the user to make the choice.  
>The other way is to define
a set of rules that effectively says that it isn’t reasonable to make
the 
>other choice and so we won’t
allow it or more likely that we won’t make it easy.

Good summary. I think there's a potential
third solution - it may be stupid, I'm just thinking this through.

What if we preserve semantics, but in
a way that processors can distinguish between ones that are guaranteed
valid (ie schema-supplied) versus ones that aren't (ie derived from other
schemas). Then a processor that is simply doing class-based matching can't
be fooled into accepting invalid content, but a processor that wants to
do more isn't prevented.

For example: topicref to chapter gets
resolved to topicref with outputclass="chapter" . Then a bookmap
processor that knows what's coming can handle it, and one that doesn't,
isn't hit.

Not suggesting that's how to write it
up in the spec - just trying to figure out a way to meet both reqs.

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/16/2009 12:47 PM




To
Michael Priestley/Toronto/IBM@IBMCA


cc
"dita" <dita@lists.oasis-open.org>


Subject
RE: [dita] referencing a bookmap from
a map






Comments below.
 
   -Jeff
 



From: Michael Priestley [mailto:mpriestl@ca.ibm.com]


Sent: Tuesday, June 16, 2009 12:12 PM

To: Ogden, Jeff

Cc: dita

Subject: RE: [dita] referencing a bookmap from a map
 


>What happens by default shouldn’t matter to the DITA specification.
 The 1.1 specification is

>entirely silent about these sorts of details. You can sort of guess
from the names and some

>of the element descriptions, but that is all you are doing. I think
the 1.2 specification

>should remain silent on these sorts of details.


  

So what is 12055 doing? Are those required behaviors, or just suggested,
or something else?


I’m not sure.  I think of
it as a requirement, that if you use a chapter to reference a topicref
that the topicref MUST be treated as a chapter.
 
But 12055 allows for exceptions,
but doesn’t say how exceptions are defined or recognized or even who makes
the exceptions (the specification author, the DTD author, the processing
implementer, the map author, …). So what is a requirement that allows
exceptions? Is that still a requirement or a suggestion or something else?
I have no idea.


To clarify:



- I'm suggesting behavior only for aggregating processes - not every possible
map process 
 
I understand and agree.


- I'm suggesting behavior that would be a default, not a requirement.
 
I don’t know what this means.
 Can a vendor deliver non-default behavior out of the box?  Is
it just that the default behavior has to be available somehow upon request?
 
Or to move this into standards
language is this something that is required (MUST), strongly recommended
(SHOULD), or allowed (MAY)?
 
 
 I'd actually be happy with being
parallel to whatever strength we put behind 12055. Just as long as we're
consistent.

- as Robert Anderson noted, if we're going to specify that a <chapter>
reference to a bookmap should resolve into a set of <chapter> references
to the bookmap's parts, then we should have the same level of specification
for what  a <topicref> does (and I think it should do something
parallel) 
 
I usually push for consistency.
12055 doesn’t directly address this case and so we would be consistent
if we said that specialized topic references override generic topic references.
And I think that that gives a better result than saying that the referencing
topic reference override the referenced topic reference.


- otherwise, how does a user get rid of semantics that don't make sense
for the reusing context? for example, a writer reusing a bookmap into an
Eclipse TOC who doesn't want "chapter xxx" generated.

 
Going with the referencing overrides
referenced approach doesn’t answer the question. You still need to ask
“how does a user get rid of semantics that don’t make sense for the reusing
context? For example, a writer reusing a bookmap into an Eclipse TOC that
does want “chapter xxx” generated.”
 
We’ve got two choices (wants
vs. doesn’t want or overrides vs. doesn’t override) and we seem to need
to pick one or the other.  Either way we are left with the same question,
how does an author pick the other choice. One solution is to provide an
explicit way for the user to make the choice.  The other way is to
define a set of rules that effectively says that it isn’t reasonable to
make the other choice and so we won’t allow it or more likely that we
won’t make it easy.


Michael Priestley, Senior Technical Staff Member (STSM)

Lead IBM DITA Architect

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25

Michael wrote:

> What if we preserve semantics, but in a way that
processors can distinguish 

> between ones that are guaranteed valid (ie
schema-supplied) versus ones that 

> aren't (ie derived from other schemas). Then a
processor that is simply doing 

> class-based matching can't be fooled into accepting
invalid content, but a 

> processor that wants to do more isn't prevented.




This would work fine.

 

It could apply to both the generic to
specialized case and to the specialized to the generic case.

 

At PTC we currently do pretty much this
using a combination of @class and a new attribute we add (@atirds:mapelement),
but we’d benefit from formalizing what we do since what we do now was
developed in a pretty ad hoc fashion.  

 

I don’t think we want to say what
attribute to use, just that the appropriate properties should be available for
use during processing in a fashion that makes sense for the given
implementation.  I suspect that we might want to provide a list to provide
more information, so to extend your example

 

     mapcontext=”topicref
chapter” or mapcontext=”chapter topicref”

 

Are the properties element based or should
we be thinking of something that is more like the class attribute tokens?

 

   mapcontext=”
map/topicref bookmap/chapter “  or mapcontext=” bookmap/chapter
map/topicref “

 

Or is this just an implementation detail
that the specification doesn’t need to worry about?

 

   -Jeff

 

 











From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]

Sent: Tuesday, June 16, 2009 1:40
PM

To: Ogden, Jeff

Cc: dita

Subject: RE: [dita] referencing a
bookmap from a map



 



Hi Jeff,


>We’ve got two choices (wants vs. doesn’t want
or overrides vs. doesn’t override) and we seem to need 

>to pick one or the other.  Either way we are left
with the same question, how does an author pick 

>the other choice. One solution is to provide an explicit
way for the user to make the choice.  

>The other way is to define a set of rules that
effectively says that it isn’t reasonable to make the 

>other choice and so we won’t allow it or more
likely that we won’t make it easy.


Good
summary. I think there's a potential third solution - it may be stupid, I'm
just thinking this through.


What
if we preserve semantics, but in a way that processors can distinguish between
ones that are guaranteed valid (ie schema-supplied) versus ones that aren't (ie
derived from other schemas). Then a processor that is simply doing class-based
matching can't be fooled into accepting invalid content, but a processor that
wants to do more isn't prevented.


For
example: topicref to chapter gets resolved to topicref with
outputclass="chapter" . Then a bookmap processor that knows what's
coming can handle it, and one that doesn't, isn't hit.


Not
suggesting that's how to write it up in the spec - just trying to figure out a
way to meet both reqs.


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/16/2009 12:47 PM 
  
  

  

   

    

    
To
    
    

    
Michael Priestley/Toronto/IBM@IBMCA
    
    
   
   

    

    
cc
    
    

    
"dita"
    <dita@lists.oasis-open.org> 
    
   
   

    

    
Subject
    
    

    
RE: [dita] referencing a bookmap from a map
    
   
  
  
 
  
  

  
 






Comments below.

 

   -Jeff

  

 









From: Michael
Priestley [mailto:mpriestl@ca.ibm.com] 

Sent: Tuesday, June 16, 2009 12:12 PM

To: Ogden, Jeff

Cc: dita

Subject: RE: [dita] referencing a bookmap from a map

 



>What happens by default shouldn’t matter to the DITA specification.
 The 1.1 specification is

>entirely silent about these sorts of details. You can sort of guess from
the names and some

>of the element descriptions, but that is all you are doing. I think the 1.2
specification

>should remain silent on these sorts of details. 

 

So what is 12055 doing? Are those required behaviors, or just suggested, or
something else?


I’m not sure.  I think of it as a requirement,
that if you use a chapter to reference a topicref that the topicref MUST be
treated as a chapter.

 

But 12055 allows for exceptions, but doesn’t say how
exceptions are defined or recognized or even who makes the exceptions (the
specification author, the DTD author, the processing implementer, the map
author, …). So what is a requirement that allows exceptions? Is that
still a requirement or a suggestion or something else? I have no idea.



To clarify:



- I'm suggesting behavior only for aggregating processes - not every possible
map process

 

I understand and agree.



- I'm suggesting behavior that would be a default, not a requirement.

 

I don’t know what this means.  Can a vendor
deliver non-default behavior out of the box?  Is it just that the default
behavior has to be available somehow upon request?

 

Or to move this into standards language is this something
that is required (MUST), strongly recommended (SHOULD), or allowed (MAY)?

 

 

 I'd
actually be happy with being parallel to whatever strength we put behind 12055.
Just as long as we're consistent.

- as Robert Anderson noted, if we're going to specify that a <chapter>
reference to a bookmap should resolve into a set of <chapter> references
to the bookmap's parts, then we should have the same level of specification for
what  a <topicref> does (and I think it should do something
parallel)

 

I usually push for consistency. 12055 doesn’t directly
address this case and so we would be consistent if we said that specialized
topic references override generic topic references. And I think that that gives
a better result than saying that the referencing topic reference override the
referenced topic reference.



- otherwise, how does a user get rid of semantics that don't make sense for the
reusing context? for example, a writer reusing a bookmap into an Eclipse TOC
who doesn't want "chapter xxx" generated.

 

Going with the referencing overrides referenced approach
doesn’t answer the question. You still need to ask “how does a user
get rid of semantics that don’t make sense for the reusing context? For
example, a writer reusing a bookmap into an Eclipse TOC that does want “chapter xxx”
generated.”

 

We’ve got two choices (wants vs. doesn’t want or
overrides vs. doesn’t override) and we seem to need to pick one or the
other.  Either way we are left with the same question, how does an author
pick the other choice. One solution is to provide an explicit way for the user
to make the choice.  The other way is to define a set of rules that
effectively says that it isn’t reasonable to make the other choice and so
we won’t allow it or more likely that we won’t make it easy.



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> wrote
on 06/16/2009 02:00:45 PM:


> Michael wrote:
> > What if we preserve semantics, but in a
way that processors can distinguish 
> > between ones that are guaranteed valid (ie
schema-supplied) versusones that 
> > aren't (ie derived from other schemas).
Then a processor that is

> simply doing 
> > class-based matching can't be fooled into
accepting invalid content, but a 
> > processor that wants to do more isn't prevented.


> This would work fine.
>  
> It could apply to both the generic to specialized
case and to the

> specialized to the generic case.
>  
> At PTC we currently do pretty much this using
a combination of

> @class and a new attribute we add (@atirds:mapelement), but we’d

> benefit from formalizing what we do since what we do now was

> developed in a pretty ad hoc fashion.  
>  
> I don’t think we want to say what attribute
to use, just that the

> appropriate properties should be available for use during processing

> in a fashion that makes sense for the given implementation.  I

> suspect that we might want to provide a list to provide more

> information, so to extend your example

I think for 1.2 we can get away with leaving it open
to the processor, but I do think there are longer-term advantages to formalizing
it. One of the big ones would be cases which used staged processing: for
example, preprocessing DITA content to resolve conrefs etc. so that the
final stage is ready for user-manipulated dynamic publishing. In this case,
the preprocessor could be part of one implementation, and the user's processor
could be part of another implementation. If the user's processor is going
to be useful across multiple repositories of preprocessed content, it needs
to have a predictable (ie standardized) place to look.

>      mapcontext=”topicref chapter”
or mapcontext=”chapter topicref”
>  
> Are the properties element based or should we
be thinking of

> something that is more like the class attribute tokens?
>  
>    mapcontext=” map/topicref bookmap/chapter
“  or mapcontext=”

> bookmap/chapter map/topicref “
>  
> Or is this just an implementation detail that
the specification

> doesn’t need to worry about?

I'm inclined to think they should be more like class
attribute tokens - following the same logic as the recent discussion on
xref type.

But should our examples use attributes that don't
exist in the spec?

Michael Priestley

On 6/12/09 4:31 PM, "Michael Priestley" 

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> wrote on
06/16/2009 07:56:21 AM:


> I see the issue as being very simple: either *require* generalization
of

> referenced topicrefs or *don't*.
>
> If you don't require generalization then there's
nothing more to say beyond

> "it's up to processors to make sense of the result or not, as
they choose".

 
I've been pushing for a required default of using
the referencing topicref's semantic (not the same as generalization). Customized
or specialized processing could override this default.


> I also submit that all discussion of output-specific processing applied
to

> the combined map is not relevant to this discussion, because that
level of

> processing is entirely implementation specific.

Since I believe that the changes you and Jeff want
to make would break existing code, and in fact set up a situation in which
all future code is inherently breakable unless restricted to the simplest
of cascading processing, I do think it's relevant. 
 

> For example, your question about how a processor of a map that references

> two bookmaps handles the indexes of both bookmaps makes several assumptions

> about the nature of the processing that are not warranted, such as
that the

> entire result map is processed as a unit or that index processing
is a

> monolithic process or even that index processing is done at all. 

I am trying to understand and expose the real-world
impact of the choice Jeff is proposing. I think it's entirely appropriate
for me to ask what the impact is for index processing. I say it will break,
and Jeff says it won't. How are we going to resolve this if we don't go
into the details of our assumptions?

I agree with you that this should be customizable,
but I also think that it should work out of the box. And I do think we
are obligated to provide guidance to processors to make something work
by default. 

We do not have to assume that "index processing
is done at all". But we do have to assume that it might be done, and
if it will be done, it should be done in a predictable fashion that doesn't
break in the face of a common markup scenario.  

> If the

> processing happens to be defined such that each referenced bookmap
is still

> processed individually for the purposes of creating say pages from
it, then

> there's no practical problem but I could just as easily implement
a

> multi-bookmap indexing process that produced a master index or a combined

> index or whatever.

If you want to implement this as your behavior, I
have no problem with that. I do have a problem with you stating that all
output processors should support this, in a manner that will be unique
to the processor, without guidance from the spec, for all possible future
specializations of map.


>

> My point is that the semantics of map processing for producing results
is

> simply too unbounded for it to make any sense for the spec to say
anything

> about it.

And yet we already provide extensive documentation
of map processing. And we plan to provide more, as in 12055. 

I agree that people can do lots of crazy unbounded
things with maps. That's why I'm proposing the behavior I've described
(preserve the semantic of the referencing element) as a default, not a
requirement. 

I think you are drawing a black and white picture
(either generalize or not) when there is at least one important shade of
grey here (provide descriptions of default processing). And this shade
of grey in fact encompasses most of the behavior we've already described
for maps (such as link processing, navigation behavior, indexing, etc.).


> Maybe the solution is to simply say:

>

> "When a topicref points to a map with format="ditamap"
the effective

> topicrefs reflect the most-specialized topicrefs involved. Note that
because

> map-to-map references are logical relationships rather than content

> references, it is not a DITA requirement that the effective map conform
to

> the DTD or schema of the referencing map. However, processors may
report

> such maps as processor errors, for example, if a particular combination
of

> maps cannot be processed meaningfully by the processor."

Reporting the error requires the processor to be aware
of content model restrictions, which is normally the job of the DTD or
schema. So either the content will have to be validated again post-aggregation,
or the processor will need to encode awareness of the DTD or schema constraints
that it is assuming applies. This is a radical change to processing pipeline
assumption, at least for me. 


> By always reflecting the most-specialized form no information is lost
but

> normal generalized processing can be applied just as it can for any
other

> specialized elements. By allowing processors to report processor errors
we

> remove the obligation to try to make sense of (to the processor)

> non-sensical cases.

First the processor must be able to detect the nonsensical
case. This will require special coding. Otherwise the nonsensical case
is more likely to produce nonsensical results, than to produce an error.

I'll finish by suggesting that, given the volume of
notes on this subject and the lack of agreement to date, we need to have
a phone call.

Michael Priestley

We are clearly not communicating.

My point is that the spec does not specify rendition processing for maps
(not even for bookmap). Nor should it.

Therefore there is *nothing to say* about the implications of processing
beyond what is said about the effective values of data properties.

There is no sense in which the effective values of properties can "break"
any processing if it is both the case that generalization is not required
and the case that processors can decide what combinations of topicrefs are
or are not meaningful to them.

Since 1.1 allows the case we're discussing (unspecialized topicref to
specialized topicref[s]) any processing that would "break" if we set a
particular rule in DITA 1.2 *is already broken*. There's no sense in which
any rule we set could break processing more. However, we could make a
decision that disallows processing that is currently allowed.

I repeat: the only two questions are:

1. Is generalization *required*?
2. Are processors free to reject maps that provide combinations of
ungeneralized topicrefs that make no sense to that processor?

I think the answer to (1) is "no" and the answer to (2) is "yes".

If there is a desire to make the constraints on bookmaps, in particular,
clearer, then the definition of bookmap needs to be extended beyond it's
current very brief definition.  But that is a separate issue.

I have already observed that the bookmap elements are significantly
underspecified if the intent is for people to understand what, for example,
"chapter" means and why it would be inappropriate to not nest them.

Cheers,

E.


On 6/16/09 9:00 AM, "Michael Priestley" 

Eliot Kimber <ekimber@reallysi.com> wrote on
06/16/2009 10:36:33 AM:


> We are clearly not communicating.

I agree. We need a phone call.

>

> My point is that the spec does not specify rendition processing for
maps

> (not even for bookmap). Nor should it.

http://docs.oasis-open.org/dita/v1.1/OS/langspec/langref/indexlist.html


> I repeat: the only two questions are:

>

> 1. Is generalization *required*?

> 2. Are processors free to reject maps that provide combinations of

> ungeneralized topicrefs that make no sense to that processor?

>

> I think the answer to (1) is "no" and the answer to (2)
is "yes".


I would like to have a general description of how
aggregation works in particular. One of the goals of the 1.2 spec was to
more clearly define these behaviors. It is not limited to bookmap, but
bookmap provides some good illustrations.

Also, I've said several times now that it's not generalization,
and I was wrong to call it that. The rule I'm proposing is that the semantic
of the referencing element should win over the semantic of the referenced
element - even when the referencing element is more general.

> If there is a desire to make the constraints
on bookmaps, in particular,

> clearer, then the definition of bookmap needs to be extended beyond
it's

> current very brief definition.  But that is a separate issue.

I think the constraints on bookmap are actually quite
clear, from a processing perspective. It has a DTD and a schema, which
are the industry-standard ways to express those constraints. The question
is whether - post-aggregation - we should expect those same constraints
to still apply, or whether aggregation by definition is going to be open
to breakage. In other words, will aggregation of maps be able to cope with
new specializations, or will aggregation of maps always require special
coding for each new map doctype? (Or be at risk for causing unanticipated
breakage)?


> I have already observed that the bookmap elements are significantly

> underspecified if the intent is for people to understand what, for
example,

> "chapter" means and why it would be inappropriate to not
nest them.

Thus moving what is currently a DTD constraint into
a human-readable guideline? Or we could set up processing by default to
not create DTD-invalid aggregations.

Michael Priestley

If I may step in to the battle at its most dangerous moment and try to sum
up what I'm thinking after reading all of this thread at once...

First, my assumptions -
* I'm going to talk about bookmap because it is easy to use as an example,
but obviously it's only one case of millions.
* I have been trying more and more to keep processing out of spec
discussions. However, I do find it very useful to help understand the
meaning of how these things are assembled. That said - I'm trying to focus
on the effective result of map references, rather than on how files might
be modified by a processor or how the result might be rendered.

With that out of the way - as I understand it, much of Michael's concern
could be restated as follows: If you are pulling a chapter into another
map, and you want it to remain a chapter, why are you not pulling it in
with a 

Comments below.

 

   -Jeff

 

> 

                                                

					
                                                    

        
                                                
				
                                                

                                                    
                                                        
                                                        Original Message
                                                
                                                Original Message-----


> From: Robert D Anderson [mailto:robander@us.ibm.com]

> Sent: Tuesday, June 16, 2009 10:51 AM

> To: Michael Priestley

> Cc: dita; Eliot Kimber; Ogden, Jeff

> Subject: Re: [dita] referencing a bookmap from a map

> 

> If I may step in to the battle at its most dangerous moment and
try to sum

> up what I'm thinking after reading all of this thread at once...

> 

> First, my assumptions -

> * I'm going to talk about bookmap because it is easy to use as an
example,

> but obviously it's only one case of millions.

> * I have been trying more and more to keep processing out of spec

> discussions. However, I do find it very useful to help understand
the

> meaning of how these things are assembled. That said - I'm trying
to focus

> on the effective result of map references, rather than on how
files might

> be modified by a processor or how the result might be rendered.

> 

> With that out of the way - as I understand it, much of Michael's
concern

> could be restated as follows: If you are pulling a chapter into
another

> map, and you want it to remain a chapter, why are you not pulling
it in

> with a <chapter> element? If you are pulling it in with a
<topicref>

> instead, doesn't that mean that either a) your current map does
not allow

> chapters, or b) you do not want it to be a chapter at this point?
So -

> wouldn't the most appropriate result be to try to treat that
chapter as

> the referencing element?

 

(a) is the case that I’ve been
thinking about. Say you have two maps and one uses “chapter” and
one uses “lesion”. You should be able to crate a deliverable that
includes both, but without creating a new map specialization for the purpose it
is likely that the existing maps will force you to include a chapter as a lesion
or a lesion as a chapter.

 

 

> Item 12055 already states that <chapter> may pull in other
elements, and

> that it casts them as chapter. It gives a specific example of when
this

> may

> produce odd results -- when <chapter> references another
bookmap with

> parts. Those parts are cast as <chapter>; if they in turn
nest chapters,

> you end up with chapters inside chapters, and 12055 says that the
result

> can be warnings, errors, corrective behavior, etc.

> 

> With that example in 12055 - we've established a policy where the

> referencing topicref pushes its role onto the target(s). Children
of the

> target are not touched, and processors can decide how to handle
them when

> the results get wonky.

> 

> 12055 also clarifies the fact that new specialized topicref
elements *may

> define different behaviors for map references*. This is where it
talks

> about the new mapref element, which explicitly does *not* push its
role

> onto the targets.

 

I agree that this is the behavior we want
for mapref, but how does a processor know that this is the behavior that we
want without having to build that behavior into each processor for each new
topicref specialization?

 

And why is the behavior for mapref
different from a topicref with format=”ditamap” or is it?

 

> Given all of that - I am not sure that we need any new rules for
the

> topicref->chapter case. Couldn't it use the same rules? 

 

It could, but should it?  Using the
same rules is simple, but does it allow us to do the sorts of things that we
want to be able to do? I think it prohibits things that we want to do.

 

> I'll try to avoid

> stating this in terms of processing, but somebody else might do a
better

> job:

> * By default -- the referencing element pushes its role onto the
target.

> <chapter> references to <topicref> become chapters,
<topicref> references

> to <chapter> become topicrefs.

> * Children of the target element are not modified

> * If the result does not make sense to you (chapters in chapters,
appendix

> in front matter), you are free to do what you want - error,
recover, etc

 

This makes it impossible to treat a chapter
referenced using a topicref to as a chapter. That isn’t what I want. 

 

We need to hear from some others to see
what they want or learn that they don’t care one way or another.

 

 

> Now awaiting tomatoes...

> 

> Robert D Anderson

> IBM Authoring Tools Development

> Chief Architect, DITA Open Toolkit

> 

> 

> 

>              Michael
Priestley

>              <mpriestl@ca.ibm.

>              com>                                
                      To

>                                        Eliot Kimber <ekimber@reallysi.com>

>              06/16/2009
10:00                                          
cc

>              AM                       
dita <dita@lists.oasis-open.org>,

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

>                                                                    Subject

>                                        Re:
[dita] referencing a bookmap

>