OASIS Darwin Information Typing Architecture (DITA) TC

Hi, I had looked at 
the bookmap implementation earlier and had found it pretty nice, but lately I 
started looking at it from an implementation point of view. 
 
Bang, I was slapped 
in the face. I know it's late in the process, but I thought I should say 
something anyway. 
 
In order to 
allow embedding maps in maps and to ease manipulation of a single map. 
I would suggest that we drop the structure:
 
Bookmap
  
preface
  
chapter
  
chapter
  
chapter
  
appendice
  
appendice
 
And get something 
that is more like:
 
Bookmap
  
Preface
  Chapters 
(specialized from topicgroup?)
     topicref
          
topicref
     topicref
     topicref
  Appendices 
(specialized from topicgroup?)
    
 topicref
     topicref
 
With the current 
structure, if I want to add a level around the first 10 chapters, I have to 
change the element name for all 10 topicrefs that were previously 
identified as chapters. Moreover, it becomes hard to implement maps in maps 
because you get multiple chapter levels.
 
France, who just 
woke up...
 
P.S. Feel free to 
slap me in the face again for bringing this up 
now!!!!



--

No virus found in this outgoing message.

Checked by AVG Free Edition.

Version: 7.5.441 / Virus Database: 268.17.32/677 - Release Date: 2/8/2007 9:04 PM

 

I'm not disagreeing that this is an
issue, but...

The extra layer has poor fallback behaviour
when the bookmap is processed as a regular map (e.g., when being published
to HTML Help or something else that isn't bookish).  The standard
would have to be more explicit about how a topicgroup gets rendered when
it is in the ToC (see http://tech.groups.yahoo.com/group/dita-users/message/3312
for one discussion about this). 

(Can you specialize a domain element
like topicgroup into a structural element like chapter?  I thought
that you can't.  But topicgroup is pretty basic so it could be faked
by just leaving off the href, which is all a topicgroup really is.)

Would it be possible to permit both
forms of markup that France quoted?  The presence or absence of an
href attribute could indicate which was intended.  Critically, then
DITA 1.1 wouldn't be delayed.  On the other hand, there are still
mapref issues with the proposed markup, and I promised I wouldn't bring
those up until post-1.1.

--

Deborah Pickett

Deborah_Pickett@moldflow.com





"France Baril"
<France.Baril@ixiasoft.com> 
2007-02-10 08.59




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


cc



Subject
[dita] Bookmap implementation






Hi, I had looked at the bookmap implementation
earlier and had found it pretty nice, but lately I started looking at it
from an implementation point of view. 
 
Bang, I was slapped in the face. I know it's
late in the process, but I thought I should say something anyway. 
 
In order to allow embedding maps in maps
and to ease manipulation of a single map. I would suggest that we drop
the structure:
 
Bookmap
  preface
  chapter
  chapter
  chapter
  appendice
  appendice
 
And get something that is more like:
 
Bookmap
  Preface
  Chapters (specialized from topicgroup?)
     topicref
          topicref
     topicref
     topicref
  Appendices (specialized from topicgroup?)
     topicref
     topicref
 
With the current structure, if I want to
add a level around the first 10 chapters, I have to change the element
name for all 10 topicrefs that were previously identified as chapters.
Moreover, it becomes hard to implement maps in maps because you get multiple
chapter levels.
 
France, who just woke up...
 
P.S. Feel free to slap me in the face again
for bringing this up now!!!!

--

No virus found in this outgoing message.

Checked by AVG Free Edition.

Version: 7.5.441 / Virus Database: 268.17.32/677 - Release Date: 2/8/2007
9:04 PM

France might 
not have been the only person sleeping,  removing the chapter element and 
defining chapter-level 
information as descendants of chapter group does seem like a good 
suggestion, albeit a late suggestion.
 
Implementing 
a model for promoting, demoting content and adding and removing topicrefs and 
submaps is simpler in the second example than the first.
 
<chapter 
href="a.xml"><topicref/></chapter>
<chapter 
href=" b.xml"/>
<chapter 
href="c.ditamap"/>
 
<chaptergroup>
    <topicref 
href="a.xml"><topicref/></topicref>
    <topicref href="b.xml"/>
    <topicref href="c.ditamap"/>
</chaptergroup>

Refer to "bookmap.mod" for the 
element declaration of chapter and entity declaration  for % 
chapter-atts, I won't bother duplicating that information here, but folks 
can look at the bookmap.mod themselves to see the definitions.
Chapter does not 
contain special chapter-level metadata or markup which forces the specialization 
of  <topicref> to <chapter>.
If a chapter 
element does not carry any special chapter-specific metadata,  one could 
define a chapter's positionally rather than literally, i.e. the  first 
level topicref inside a chapter group is rendered as a chapter.   

 
The problem is timing; the design was 
approved and the DTD's are done.    I'm not sure if anything can 
be done for 1.1, or whether other TC members find this is an important 
issue.
 
And to play devil's advocate, if the group 
who designed bookmap could discuss some of the advantages of the current design 
on the list, it would be useful to have a better understanding of the underlying 
design decisions that were made.
 

Yas Etessam
 
 
 
 



  

  

  From: France Baril 
  [mailto:France.Baril@ixiasoft.com]
Sent: Friday, February 09, 2007 
  2:00 PM
To: dita@lists.oasis-open.org
Subject: Bookmap 
  implementation


  

  
Hi, I had looked 
  at the bookmap implementation earlier and had found it pretty nice, but lately 
  I started looking at it from an implementation point of view. 
  
  
 
  
Bang, I was 
  slapped in the face. I know it's late in the process, but I thought I should 
  say something anyway. 
  
 
  
In order to 
  allow embedding maps in maps and to ease manipulation of a single 
  map. I would suggest that we drop the structure:
  
 
  
Bookmap
  
  
  preface
  
  
  chapter
  
  
  chapter
  
  
  chapter
  
  
  appendice
  
  
  appendice
  
 
  
And get something 
  that is more like:
  
 
  
Bookmap
  
  
  Preface
  
  Chapters 
  (specialized from topicgroup?)
  
     topicref
  
          
  topicref
  
     topicref
  
     topicref
  
  Appendices 
  (specialized from topicgroup?)
  
    
   topicref
  
     topicref
  
 
  
With the current 
  structure, if I want to add a level around the first 10 chapters, I have to 
  change the element name for all 10 topicrefs that were previously 
  identified as chapters. Moreover, it becomes hard to implement maps in 
  maps because you get multiple chapter levels.
  
 
  
France, who just 
  woke up...
  
 
  
P.S. Feel free to 
  slap me in the face again for bringing this up 
  now!!!!


  
--
No virus found in this outgoing message.
Checked by 
  AVG Free Edition.
Version: 7.5.441 / Virus Database: 268.17.32/677 - 
  Release Date: 2/8/2007 9:04 PM

Yas Etessam wrote:
> France might not have been the only person sleeping,  removing the 
> chapter element and defining chapter-level information as descendants of 
> chapter group does seem like a good suggestion, albeit a late suggestion.

I was sleeping too. I agree with France's analysis and would prefer a 
"chapters" (or "bookbody") wrapper--that is how I structure all of my 
book-ish schemas.

I have the same complaint about DocBook.

Given that there is no (official) legacy for bookmaps, I think we have a 
little more room to make this change if we can get consensus quickly.

Cheers,

E.
-- 
W. Eliot Kimber
Professional Services
Innodata Isogen
8500 N. Mopac, Suite 402
Austin, TX 78759
(214) 954-5198

ekimber@innodata-isogen.com
www.innodata-isogen.com

I'm a little bit worried about the precedent of creating containers, so
that we can continue copying/pasting the other elements unchanged. This is
really going to be an issue with every map specialization. You will often
want to provide context when you reference a topic - indicate that when you
point to a topic at this location in this map, it plays a specific role.
Specialization is the normal DITA mechanism for doing this, so it seems
normal to me to point directly to a topic with a specialized topicref.
We've got some pretty heavily specialized maps in use that do the same
thing, and have not had any problems with them. I would think that changing
this will cause people to shy away from similar useful specializations in
the future.

So, I'd rather not toss out the existing model. I think that the issue of
adding a new parent topic to the chapter will come up seldom enough that
many people will not want to deal with the extra container. Keeping the
individual chapter elements does also provide a usability gain for large
bookmaps, because - when scrolling through that map in an editor that gives
you an XML view - it is easier to identify where you are (something I have
run in to working with the language reference).

The fact that there are at least a couple of bookmap implementations
available, and that users of those have not complained, seems to indicate
that this is not a critical problem. I think rather than changing the
markup to force users into grouping elements, I would tend to prefer the
solution Deborah suggested on Sunday (if I understood it correctly) -- that
is, 

Hi, France, Yas, and Eliot:


I have a bit of concern about pushing the role semantic up to the container.  By rights, shouldn't the role semantic be associated directly with the <topicref> element via specialization?  Putting the role semantic on the container does work in this case because book roles are fundamentally top-down, but applied generally, that approach would result in deeper structures with a much higher markup to content ratio.


A more general solution might be to enhance specialization so a specialized element could acquire or shed contextual roles without limiting reuse.


The other point is that, if people conref from a bookmap into an ordinary map, generalization should enable that reuse because chapterref can revert to topicref.


Would it be better to build in the container legacy for this special case?  Or to work on the long-term solution and, in the mean time, reuse from a bookmap into an ordinary map?



Hoping that's useful,



Erik Hennum

ehennum@us.ibm.com