OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[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]