[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook-apps] Please respond: adding generic sibling to high-levelbook components
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]