Re: DocBook 5.0: The Definitive Guide

[Norman Walsh <ndw@nwalsh.com>]

/ Dave Pawson <davep@dpawson.co.uk> was heard to say:
| On Tue, 2005-01-04 at 08:05 -0500, Norman Walsh wrote:
|> Over the winter break, I spent some time building a "V5.0"
|> version of DocBook: The Definitive Guide. You can find it at
|> http://docbook.org/tdg5/en/
|
| Another quiet Christmas Norm (and Debs :-)????
|
| Comment, tdg5.
|
| Why does the content  model appear twice please?
| The (in cases very long) list of items at the top,
| then again as a list of children?

Well, the idea is that the first occurrence is the content model. It
shows the structure that's allowed inside the element. The list of
children is just an alphabetic list of all the possible children.

In the DTD version, the names of elements in the content model tended
to be in an arbitrary order so it wasn't easy to tell, at a glance, if
"systemitem" was allowed in a particular content model. In the list
of children it was much easier.

Now, given that the greatly massaged content models in the V5 version
are already in alphabetical order, maybe the list of children is
redundant.

Is the list of parents useful?

| (And are you deriving the content models from the schema, you
| clever .... :-)

Egad, of course! Anything else would be insane :-)

| I like the phrase (db.phrase) style notation. 
|
| except, perhaps
| info (db.titleforbidden.info)
|
| Since its an info element, could it (should it)
| be db.info.notitle? 

Ahh, the names of the patterns might need some work. I've tried to
have some conventions, but I'm not sure I've followed them rigerously.

| Mmm. Found a few more
| info (db.info), info (db.titleforbidden.info), info (db.titleonly.info),
| info (db.titleonlyreq.info), info (db.titlereq.info).
|
| Is there logic there, (or should there be !)

Well, there are five kinds of info element that are used in different
places. Consider:

  <chapter>
    <title>Chapter Title</title>
    <info>...</info>

Title has to be forbidden in that info element because the chapter
already has a title. But in

  <chapter>
    <info>...</info>

title has to be required so that the chapter must have a title.

db.info -- the general case, anything allowed
db.titleforbidden.info -- no titles allowed
db.titleonly.info -- only title allowed, no subtitle
db.titleonlyreq.info -- only the title and required
db.titlereq.info -- required title

| informaltable (db.cals.informaltable)  could that be
| db.informaltable.cals (or .html)  with similar logic
| to that above? I.e. the element, then the descriptor?

But the info is the element not the descriptor above.

| Is the db. prefix essential?

Alas, yes. Pattern names aren't namespace qualified so if you might
want to use RELAX NG and TEI together, you better make sure that the
pattern names don't clash.

| indexterm is shown empty, yet is described as  a wrapper :-)

Right. The "endterm" form of indexterm shouldn't be described as a wrapper.

| Do we need the rev, date and time on every page?

While the book is in alpha, I think so. I'll try to make the
presentation a little more subtle :-)

| inlineequation shows 
|  One or more of
|   db._any.mml
|
| Wozzat please?

That's http://docbook.org/tdg5/en/html/_any.mml.html

Basically, any element from the MathML namespace. Those "any" cases
aren't handled very well yet.

| I'm less happy with that notation Norm.
| If we assume lots of namespaces may creep in over the next n years,
| then its worth getting this good now?
|
| will there be _any.xhtml, _any.svgml  etc?
|   Brain dump.
|    mml:*   
|    xhtml:*
|    svg:*
|    *:* 
| (sort of reads more like 'stuff from *this* namespace' to me?)
| or perhaps mml:any etc?

Some improvement is defnitely needed here.

| I think I basically don't like the underscore starter?
| any would be near the top, as would * in the index.
|   (I'll stop rambling now)

Please don't, it's all good stuff.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Everything should be made as
http://www.oasis-open.org/docbook/ | simple as possible, but no simpler.
Chair, DocBook Technical Committee |

PGP signature