RE: [docbook-tc] Assembly questions

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

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

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

Ok. On the one hand, I don't like having multiple ways of doing the same
thing. On the other,

  <module resourceref="unpacking" renderas="chapter"/>
  <module resourceref="drivers" renderas="chapter"/>
  <module resourceref="cartridges" renderas="chapter"/>

is a lot simpler looking than

  <module resourceref="unpacking">
    <output renderas="chapter"/>
  </module>
  <module resourceref="drivers">
    <output renderas="chapter"/>
  </module>
  <module resourceref="cartridges">
    <output renderas="chapter"/>
  </module>

How about making it possible to specify renderas in either place, but
make it an error to specify it in both places?

LRR: This would lose the ability to specify a default renderas value
     for complex render requirements, but I am not sure how significant
     a loss that is.

>      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).

I think that may have been lost altogether, actually.

LRR: see above comment.

> 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.

Yes, I thought so too, until I realized that it really names a DocBook
element. And suppose I had a DocBook extension that mixed several
namespaces. I think I might need to be able to say
renderas="my:component".

LRR: That makes a lot of sense, seems like a good plan.

> 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.

Ok. I'll put it back.

> 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.

Ok. This is right at the heart of a fundamental dichotomy in how you
and I think about assemblies. I see them as instructions for how to
construct a new, single document to render. You, I think, see them as
instructions to the renderer directly, instructions about how to build
the final presentation artifact.

I don't know how to resolve that disconnect, so I'll just leave it
alone :-)

LRR: I just sent a description of what I think the type attribute is
     for.  Maybe it will help.


> 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. 

Ok. I'll investigate allowing it again.

LRR: Sounds good.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | I'm NOT in denial!
http://www.oasis-open.org/docbook/ | 
Chair, DocBook Technical Committee |