RE: [dita] Complexity of bookmap content model

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

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
>