Re: [docbook-apps] Please respond: adding generic sibling to high-level book components

["Michael(tm) Smith" <smith@sideshowbarker.net>]

Scott Hudson <scott.hudson@flatironssolutions.com>, 2007-02-22 21:28 -0700:

> The issue with calling it frontmatter or endmatter, is that they are 
> allowed anywhere in book (at the chapter level).

I'm not sure what you mean by "they". As far as the existing
elements under discussion, as far as I know, we've only been
discussing Ackno and Dedication.

Ackno can currently occur only at the end of Article. And though
the content model for Book does currently allow Dedication
anywhere, that's just because it also allows toc, glossary,
chapter, index, etc., anywhere in any mix/combination.

The docs for dedication actually say, "A Dedication is a section
at the very beginning of a book (before any other body matter)".

I guess there's some historical rationale for Book having the
free-for-all structure that it does, but as long was we have the
option of making backward-incompatiable changes, we always have
the choice to make Dedication and Acknowledgements allowed only at
the end or beginning (if that's what we wanted to do).

In DocBook 4 Article, does have a de facto structural division
for back matter:

  article ::=
  ((%div.title.content;)?,
   articleinfo?,tocchap?,lot*,
   (%bookcomponent.content;),
   (%nav.class;|%appendix.class;|colophon|ackno)*)

The back matter is (%nav.class;|%appendix.class;|colophon|ackno)*
-- where nav.class is toc|lot|index|glossary|bibliography

And a DocBook 5 Article also has a structural division for front matter:

  element article {
    db.article.attlist,
    db.article.info,
    db.navigation.components*,
    ((db.all.blocks+, db.article.components?)
     | db.article.components),
    (db.appendix | db.navigation.components | db.ackno | db.colophon)*
  }

-- the front matter being db.naviation.components (which is
bibliography|glossary|index|toc).

Anyway, I'm not advocating adding front-matter or back-matter
structural divisions in book. It would be a lot easier just to add
Acknowledgements where Dedication is currently allowed.

> The current model for children of book will let you have an
> appendix followed by a preface followed by a glossary followed
> by chapters and an index if you want! So frontmatter could be at
> the end, and endmatter could be at the beginning!

I suspect there is some reasonable historical rationale for book
lacking front-matter and back-matter structural divisions.
Anyway, I can't recall ever seeing a complaint from users about
it, so I guess we ought to keep it the way it is and if any when
we add Acknowledgements or other new components, just toss them
into the mix with the others (which is db.components pattern in
the DocBook 5 grammar/schema).

> All this really arose from trying to request a new element for 
> endorsements (dedication isn't really appropriate, neither is preface).

You mean Acknowledgements, right?

> Another good example: What if you had a book with a forward,
> introduction and a preface? there aren't elements for forward or
> introduction, so how would you handle these?

With Preface. The Preface element has a required Title child. The
heading generated for it is "Preface" only if you explicitly title
it that way.

And you can have multiple Preface instances in a single doc, so
you can to <preface><title>Forward and <preface><title>Introduction

To quote the docs:

  Preface is a preface or forward in a Book. The Preface element
  may appear more than once and should be used for all
  introductory chapter-like material. For example, a Book might
  have both a Foreward and an Introduction. Both should be tagged
  as Prefaces in DocBook.

The issue with preface, forward, and introduction is that there's
really no clear difference among them. They are all used by
different authors for the same thing. One author's Forward is what
another author might consider a Preface.

I know there are style guides (Chicago Manual, etc.) that probably
prescribe differences between what a Preface and a Forward should
be but authors in the real world use/abuse them for the same purpose.

On the other hand, Acknowledgements and Dedication have specific
specialized purposes that are different from just being general
introductions or prefaces or forwards to a book.

In the case of a dedication for work written in English, the
content typically has the following characteristics:

  - if a book contains a dedication, it almost always occurs near
    the beginning of the book
  - a dedication is almost always untitled
  - a dedication  has as its complete contents something very
    short (usually a single paragraph) that starts either with the
    phrase "This book is dedicated to..." or simply simply just a
    phrase like "For FooBar, who made it all possible"

An Acknowledgements section is different in that it has the
following characteristics:

  - acknowlegements may occur either near the beginning or the end
    of a book
  - acknowledgements are almost always titled
  - the contents of an acknowledgements section may be quite long;
    for example, in, say, a work that includes code snippets from
    other copyrighted books or screenshots from multiple programs,
    the Acknowledgements section may contain statements like:

      Page 519. The screenshot from the program FooBar is
      Copyright 2007 by the FooBar Company and is used with
      permission.

      Page 543. The "HogeMoge" code snippet is Copyright 2005 by
      the HogeMoge Project and is used with permission.

    Such kinds of Acknowledgements sections can run to multiple
    pages.

I know some authors might use Acknowledgements to mark up what is
really a dedication, but I don't think any author is going to use
a dedication to mark up acknowledgements.

So what I'd assert why we need a separate element for Dedication is:

  - a dedication is very different from a preface; while a preface
    is typically titled and runs to some lenght, a dedication is
    typically untitled and contains only a very short text
    starting with "For..."

And what I'd assert about why we need a separate element for
Acknowledgements:

  - acknowledgements, like prefaces, are typically titled

  - acknowledgments have a more specific type of content than
    a general preface; for example, acknowledgements often contain
    statements about permissions granted to reproduce things like
    code snippets and screenshots

  - acknowledgments occur either near the beginning or end of a book

  - for an acknowledgements section that occurs at the beginning
    of a book, a possible case could be made for just marking it up
    using Preface with the title Acknowledgements, though some
    authors might see that as shoe-horning Acknowledgements in
    somewhere where doesn't it doesn't naturally fit

  - for an acknowledgments section that occurs at the end of a
    book, and author could use Appendix with the title
    Acknowledgments -- but I think many authors would see that as
    an even worse shoe-horning into a poor fit than marking up
    Acknowledgements with Preface would be; for one thing, when
    processed with, for example, the DocBook XSLT stylesheets,
    that markup is going to produce something like:

      Appendix A: Acknowledgements

   I've never seen a book that had an acknowledgements section
   that was a labeled appendix like that. So I don't think marking
   up an acknowledgements section as a class of appendix would be
   a good way to go.

So I think there's a good case for saying that it would be useful
to have a new Acknowledgements element that's different in
addition to the elements we already have that could be seen as
related to the acknowledgements use case -- Dedication, Preface,
possibly Appendix -- becausethere are in fact differences and
requirements that make those existing elements unsuitable for
marking up the contents of acknowledgements in the places
(front/back) in a book where acknowledgements can possibly occur.

  --Mike