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

[Scott Hudson <scott.hudson@flatironssolutions.com>]

The issue with calling it frontmatter or endmatter, is that they are 
allowed anywhere in book (at the chapter level). 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!

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

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?

--Scott

Michael(tm) Smith wrote:
> 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
> 

begin:vcard
fn:Scott Hudson
n:Hudson;Scott
org:Flatirons Solutions
adr:Suite 200;;4747 Table Mesa Drive ;Boulder;CO;80305;USA
email;internet:scott.hudson@flatironssolutions.com
title:Consultant
tel;work:303-542-2146
tel;fax:303-544-0522
tel;cell:303-332-1883
url:http://www.flatironssolutions.com
version:2.1
end:vcard