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 15:47 -0700:

> Technically, Preface, Chapter and Appendix have the same content model.
> 
> Dedication is definitely more restrictive, in that it cannot contain 
> bibliography, glossary, index or toc. Otherwise it's content is the same.
> 
> What about calling this generic structure "bookmatter" (since we can't 
> call it frontmatter or endmatter)?

If you really wanted to go that route, the maybe we'd actually be
a lot better off adding frontmatter and endmatter elements with
enumerated values.

The terms "front matter" and "end matter" at least are familiar to
users (well, at least to users who have some knowledge of book
publishing), whille "book matter" and "book unit" and "extra
matter" are not (because we would be coining them).

I really think we ought to be very wary of adding any markup that
would seem to carry with it a "clarification" sort of doc
requirement or a "see foo" cross-reference in the index.

What I mean is -- to trot out my hobbyhorse example of the
Systemitem element -- What we have in the docs now as a
description of Systemitem is, "A system-related item or term."
That description does nothing to clarify or signal what specific
things it's actually intended to be used --  for marking up
usernames, constants, IP addresses (and 19 other things).

It would help to at least have an entry in the index for username:

  username, see systemitem

But if we readlly wanted to provide point-of-use guidance to
readers of the docs on how to mark up usernames, we'd need to have
a page in the alphabetical elements listing docs for the term
"username", and that page would say something like,

  You may be expecting to find a specific element to mark up a
  username. DocBook doesn't have one. Instead, we consider a
  username (along with an assortment of 21 other things) to be a
  class of something we call a "system item", and we require you
  to use the systemitem element to mark it up.

And if we were to take a similar approach and go ahead with the
proposal for a generic element for acknowledgements and
dedication, something like:

  ...we consider acknowledgements to be a class of something we
  call "book matter" (or a "book unit" or "extra matter").
  Everybody except us considers that class of content to be "end
  matter" or "front matter", but we decided to call it something
  else because [we want to make things easier for you? we wanted
  to keep the number of elements in DocBook to a minimum?]

The problem with that kind of approach is that it is prescriptive
(rather than descriptive) one that shoehorns the markup into an
extra layer of artificial, invented terminology (systemitem,
bookunit), and that forces users to discover and adopt that
invented terminology instead of just being able to directly mark
up their content using the terms they'd naturally expect to find
and use (username, acknowledgements, dedication).

  --Mike