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

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

Thank you, Mike! I think you have aptly described the need to add 
acknowledgements to the book model (and article for that matter) and 
perhaps remove the Ackno element in favor of this new element.

By "they", I was referring to chapter, appendix, glossary, index, toc, 
dedication, etc. The free-for-all structure, as you put it.

I do see your point about preface, and have used multiple preface 
elements in the past, so that approach does work.

I'll quote your justifications for acknowledgements in the RFE to allow 
ackno in book.

Thanks for a very interesting discussion!

Best regards,

--Scott

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

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