[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
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hmmm, the element name meaning is only relevant if: - - the author masters English language - - and he is aware of the sometimes very specific vocabulary used as element name. DocBook is already a new world in itself for most people. If some elements aren't labeled exactly the name they would have expected -a posteriori- (because they will learn semantics along the way) does it really matter? Talking about language, have there been research made on localized DTD/schemas ? Camille. Michael(tm) Smith a écrit : > 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 > > --------------------------------------------------------------------- > To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org > For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.5 (GNU/Linux) Comment: Using GnuPG with Mandriva - http://enigmail.mozdev.org iD8DBQFF3qDvjv9P65BfOUMRAovCAJ4x61c1YrnWerAaSYDlQydk3OWsdACgmZ1q 7FHK7IhsR/HDVqsIL8CrKM4= =RZkS -----END PGP SIGNATURE-----
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]