Re: Ruminations on the future of DocBook

[Norman Walsh <ndw@nwalsh.com>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

/ "A.R. (Tom) Peters" <tpeters@xs4all.nl> was heard to say:
| On Fri, 30 May 2003, Pierre Machard wrote:
|> The syntax itself (the DTD) is very comprehensive, the most difficult
|> aspect, is the rendering. Don't you agree with that ?
|
| Hear, hear.  The main problem I have with DocBook is not the element set,
| it is the tool chain.  It is very hard to get an even moderately decent
| print-out.  Vanilla LaTex and even MS-Word do a better job.  Like I saw
| Norman mention earlier this year, there is no-one taking care of the tool
| chain so that everything from editing to printing gets in place and just
| works.  I believe this has been the major obstacle to a more widespread
| use of DocBook.

Perhaps. But I'm not sure what we can do about that.

| My second problem is that so much mark-up is needed.  Marking up a text
| to DocBook easily doubles its size.  It is too much hard work, and
| distracts from writing content more than it does help you organize it.

One man's distraction is another man's organization, I guess. Writing
structured documentation is a different than writing non-structured
documentation. I think it's worth the effort, but others might disagree.

| Finally, the hierarchical way the elements and attributes are specified in
| the definition makes adding features an N-squared problem.  Suppose I want
| an extension to identify a piece of text as a "chemical formula".  Never
| mind the rendering: there are many elements under which a "chemical
| formula" could properly appear.  As far as I understand DocBook, you have
| to explicitly specify them all in the definition.  And if you forget one

Most of the definitions are composed from parameter entity classes. If you add
the new element to the right parameter entity (or sometimes a few entities),
it shows up in all the right places.

| On a related note: in the documentation the allowed sub-tags are listed in
| an - as far as I can tell - random order.  It is sometimes very tedious to
| verify if a specific tag is valid in a certain context.  I suggest
| extensive re-ordering of the documentation.

They're listed in content-model order at the top (because that's a
content model fragment). They are then listed in alphabetical order
below.


                                        Be seeing you,
                                          norm

- -- 
Norman Walsh <ndw@nwalsh.com>      | Until death, it is all
http://www.oasis-open.org/docbook/ | life.--Cervantes
Chair, DocBook Technical Committee |
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>

iD8DBQE/Fv9kOyltUcwYWjsRAn43AKCmqVaQJfvzbYD+NKzUYT5gbIvxngCfWYLJ
kE/Wvp/5xf63vF+hL4/zsC0=
=nm9S
-----END PGP SIGNATURE-----