RE: [dita] Complexity of bookmap content model

[Robert D Anderson <robander@us.ibm.com>]

As nobody else seems to be responding, I'll go ahead and say that I support
the changes that Paul suggested. I think it would make the bookmap more
usable.

Paul, I notice you questioned what to do with appendix elements (and
presumably other back-matter elements) inside the part tag. With the new
<backmatter> tag to hold these, did you expect to move back matter out of
the part element? If so, I think the new structures you're suggesting would
look more-or-less like this:
<!ELEMENT bookmap (title, bookmeta?,
      frontmatter?, chapter*, part*, backmatter?,
      colophon?, reltable* )>

<!ELEMENT frontmatter (booklists | draftintro |
       abstract | dedication | preface | topicref)*>

<!ELEMENT backmatter (appendix*, notices?
       specialnotices*, amendments?, topicref* )>

<!ELEMENT part (topicmeta?, chapter*)>

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/14/2006 03:11:24 PM:

> I think that being able to put specialized "special chapters" where-ever
> you want is a pretty big benefit, so I'm glad you pointed out that
> advantage of a model with a more explicit structure.
>
> I'll throw out another benefit. In editors with a "collapse element"
> construct, it would be great to be able to collapse the whole front
> matter or back matter at once.
>
>  -----Original Message-----
> > From: Robert D Anderson [mailto:robander@us.ibm.com]
> > Sent: Wednesday, June 14, 2006 12:53 PM
> > To: Paul Prescod
> > Cc: dita@lists.oasis-open.org
> > Subject: RE: [dita] Complexity of bookmap content model
> >
> > Hi Paul,
> >
> > I will not argue against any of the proposals, except for one thing on
> a
> > technical basis. The map model does not allow reltables to appear
> except
> > as
> > children of the map, so they cannot go in a grouping element at the
> end.
> >
> > The topicref element at the end was created based on user feedback
> that
> > asked for a place to define sections we might not have thought of. So,
> it
> > is not just intended for relationships - it is also intended for
> generic
> > other sections, which would require updated processing in order to
> appear
> > in the right spot. Maybe you would want to change the <relationships>
> > element at the end of bookmap to something like this (probably with a
> > better name than otherbooksections)?
> > <!ELEMENT bookmap (title,
> >                          bookmeta?,
> >                          frontmatter?,
> >                          chapter*,
> >                          part*,
> >                          backmatter?,
> >                          colophon?,
> >                          otherbooksections?,
> >                          reltable* )>
> >
> > Alternatively, with elements grouped into front and back matter, it
> > probably makes more sense to have a topicref* inside each of those
> > sections. This would allow special sections where they belong. Without
> the
> > front and back groupings, we had to pick only one location to include
> > topicref*.
> >
> > 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/14/2006 02:13:52
> PM:
> >
> > > Let me ask this again in a few ways.
> > >
> > >  1. Do current bookmap users see this content model as complex?
> > >
> > >  2. If not, how do you manage the complexity in your head? How do
> you
> > > remember what elements can go in what places?
> > >
> > >  3. Is there anyone out there who would argue against simplifying
> the
> > > model on a technical or usability basis?
> > >
> > >  4. Is there anyone who would argue against simplifying it on a
> > > procedural basis ("too late. Will slow us down?")
> > >
> > >  5. What do people think about the particular simplification
> proposal at
> > > the bottom? Putting aside issues of title, the main ideas are
> > >
> > >  * group front-matter and backmatter into their own (topichead-like)
> > > elements.
> > >
> > >  * to group the portion of the tree designed for creating
> relationships
> > > but not generating the table of contents (to help make the TOC
> > > predictable)
> > >
> > > =====
> > >
> > > Note the sort of document that the current model can generate:
> > >
> > > <bookmap>
> > >
> > > <title></title>
> > >    <part><appendix></appendix><appendix></appendix></part>
> > >    <part><chapter></chapter><chapter></chapter></part>
> > >    <colophon/>
> > >    <topicref></topicref>
> > >    <topicref></topicref>
> > >    <topichead></topichead></bookmap>
> > >
> > >  * Chapters after appendices.
> > >  * Topicrefs after colophon.
> > >  * Topicheads after the colophon
> > >
> > > What should a TOC generator do with a topicref after the appendices
> and
> > > colophon are done?
> > >
> > > Are the appendices within parts before chapters meant to be gathered
> for
> > > the end of the book or published in-place in the middle of the
> document?
> > >
> > > > -----Original Message-----
> > > > From: Paul Prescod [mailto:paul.prescod@xmetal.com]
> > > > Sent: Monday, June 12, 2006 2:29 PM
> > > > To: dita@lists.oasis-open.org
> > > > Subject: [dita] Complexity of bookmap content model
> > > >
> > > > 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
> > >
>