Re: [dita] Complexity of bookmap content model

[Erik Hennum <ehennum@us.ibm.com>]

Hi, Robert and Paul:

As I recall, the rationale for the chapter / appendix / part aspects of the bookmap model was that:

• An unpartitioned book should be able to have chapters followed by appendices
• A partitioned book should be able to have chapters prior to the first part (in effect, providing an implicit first part without an explicit container) but must put appendices within a part

For what it's worth, having an implicit container prior to the first explicit container seems like a common pattern in DITA.  For instance, the concept body provides block content prior to the first explicit section container.


Hoping that's useful,


Erik Hennum
ehennum@us.ibm.com

Robert D Anderson/Rochester/IBM@IBMUS

Robert D Anderson/Rochester/IBM@IBMUS

06/12/2006 03:11 PM

To	"Paul Prescod" <paul.prescod@xmetal.com>
cc	dita@lists.oasis-open.org
Subject	Re: [dita] Complexity of bookmap content model

Hi Paul,

The decision to allow multiple preface and other types of introductory
material was based on user reviews from an one of my early bookmap
prototypes. The comment was that users wanted an easy way to change the
order of these sections - for example, one group would want a preface
before the abstract, and another wants the opposite. They also wanted an
easy way to control this - such as flipping the order in the source,
instead of using a (still undefined) style document or transform override
to set the order. The only way to allow the order to change was to change
the whole front matter section to *.

Another reason to do it is the one that caused us to allow indexlist*
instead of one optional indexlist -- if you want two types of introductory
sections that each represent preface material, you should probably
specialize both off of preface; however, if we only allow one preface
section, you could not include both specialized elements.

As for the complex chapter/appendix/part model -- I think most of that
carried over from the original bookmap, so I should let the originators
speak to that. The same is true for the lack of <frontmatter> and
<backmatter> groupings - the original model was:
<!ELEMENT bookmap (((%bkbasicinfo;) | (%bkinfo;))?,
                   (%draftintro;)?,
                   (%abstract;)?,
                   (%dedication;)?,
                   (%preface;)?,
                   (%chapter;)*,
                   ( ( (%appendix;)*, (%notices;)? , (%amendments;)? )
                     | (%part;)* ),
                   (%colophon;)?)>

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit
(507) 253-8787, T/L 553-8787

"Paul Prescod" <paul.prescod@xmetal.com> wrote on 06/12/2006 04:29:05 PM:

> Is anyone else concerned about the complexity of this content model?
>
> <!ELEMENT bookmap (((%title;) | (%booktitle;))?,
>                    (%bookmeta;)?,
>                    ( (%booklists;) |
>                      (%draftintro;) |
>                      (%abstract;) |
>                      (%dedication;) |
>                      (%preface;))*,
>                    (%chapter;)*, ( ( (%appendix;)*, (%notices;)?,
> (%specialnotices;)*, (%amendments;)? ) | (%part;)* ),
>                    (%colophon;)?,
>                    (%topicref; | %reltable;)*)>
>
> I don't mind its size as much as its complexity.
>
> Even with validating editors like XMetaL, content models with many
> alternatives can be confusing. "I put an appendix in and now I can't put
> a part in before it. Why not?"
>
> Also: why do we want to allow multiple abstracts, dedications, prefaces,
> etc.
>
> I could imagine something more like:
>
> <!ELEMENT bookmap (title,
>       bookmeta?,
>       frontmatter?,
>       chapter*,
>       part*,
>       backmatter?,
>       colophon?,
>       relationships? )
>
> I would expect the elements frontmatter, backmatter and relationships to
> be topicheads.
>
>  Paul Prescod
>