RE: [docbook-tc] Assembly questions

["Rowland, Larry" <larry.rowland@hp.com>]

Norm,

Here is what I think (being freshly returned from a week in the Rockies):

-----Original Message-----
From: Norman Walsh [mailto:ndw@nwalsh.com] 
Sent: Sunday, July 11, 2010 10:36 PM
To: docbook-tc@lists.oasis-open.org
Subject: [docbook-tc] Assembly questions

Looking at 5.1b1,...

1. Why does the module have @renderas when it can contain an output that
   also has @renderas?

LRR: The idea was that for very simple document structures it would not
     be necessary to use an output statement when there is no need to
     differentiate the render based on the output being used.  At one
     point it also provided a default renderas value when there are 
     multiple output formats that mostly use the same renderas but 
     there are a small set of exceptions -- we may have moved that
     to a defaultrenderas attribute (it has been a while).

2. Renderas is an NMTOKEN. Shouldn't it be an xs:QName (maybe with a
   special default rule that says that a name in no colon is by default
   in the DocBook namespace)?

LRR: It was NMTOKEN because I was thinking of element names and other
     token-like .  If QNAME makes more sense, then by all means make it 
     that.  I was thinking that it served the same function a token did,
     and that's why I chose the NMTOKEN.

3. If module *should* have @renderas, then shouldn't structure as well?

LRR: At one time it did, and I would probably add it back.  It likely
     was dropped off when output was added to the markup and not added
     back when it was added back to module.

4. What is @type on structure for?

LRR: Type identifies a class of document that has significance to the
     rendering system: a helpsystem would have different rendering
     expectations than a book and both would have different rendering
     expectations than a tutorial.  This is not as simple as the output
     format -- I might want to render a helpsystem as CHM or as Webhelp
     or as a printable version in PDF, but the fact that it is a 
     helpsystem provides information to the rendering systems for each
     of the output formats that it might be rendering.

5. It seems inconsistent to me that you can say

     <resource xml:id="someid"> <chapter> ... </chapter> </resource>
     ...
     <module resourceref="someid"/>

   But you can't say

     <module> <chapter> ... </chapter> <module>

   Forcing me to insert a level of indirection just because I want to have
   a bit of content in the assembly file seems entirely arbitrary.

   (And it would seem equally arbitrary to say that resource can contain
   some DocBook elements and not any DocBook element.)

LRR: The original model was that resources provided content, whether it was
     local to the assembly file or referenced from an external source of
     some kind.  That was a long time ago, and at one time we didn't allow
     DocBook markup in the assembly, at all.  I think that was a mistake,
     but one of the problems with markup that has evolved as much as this 
     one has is that there is a tendency for a lot of historical accidents 
     to be preserved that don't really make sense when you look at the
     grammar as a whole (which you appear to be doing now).  I think it 
     probably does make sense to allow the markup inside a module, it just 
     was not the model that was being implemented when the decision was made 
     to restrict all content to the resources.  I am not sure about the impact
     it might have on localization, although it certainly doesn't make it
     any more difficult than the addition of override elements like a title.
     I agree about the arbitrary nature of restricting DocBook elements --
     it is probably more reasonable to allow them unrestricted, although
     that probably introduces some issues with nesting of arbitrary elements.
     I think having the content of the module inside the structure makes
     sense in this context. 

Sorry if I'm repeating myself.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | It is seldom that any liberty is
http://www.oasis-open.org/docbook/ | lost all at once.--David Hume
Chair, DocBook Technical Committee |