DocBook assembly: inheritance of renderas

["Bob Stayton" <bobs@sagehill.net>]

As I implement a stylesheet to convert a DocBook assembly into a DocBook document, I'm
finding myself growing uncomfortable with this feature described in Norm's 5.1
Definitive Guide:

"By default, the renderas value is inherited from a module's preceding sibling."

First of all, the notion of inheriting something from a sibling is unprecedented in
XML, isn't it?  Are there other examples?

But more importantly, I think it creates confusion.  The renderas attribute on a
module is a means to override the element that is referenced by the module.  If there
is no renderas attribute, then then most people would think there is no override, and
the resource's element name would be used. If I create a resource that points to a
bibliography element, I would expect a module element without a renderas attribute to
become a bibliography.  I would be very surprised to see it become a chapter, simply
because a preceding sibling module had renderas="chapter".  I think that's why Norm
includes this statement about the last module in his first example:

"Even though the index is an index, because there is an explicit rendering [that
should be renderas] on a preceding module, it must be explicit on the index."

In other words, once you turn on such inheritance, there is no way to turn it off, so
you are forced to override your earlier renderas with another renderas to get back to
the original element in the resource.  That is two renderas attributes just to get
back to what should be the default: the element name in the resource.  That just seems
odd to me.

I'm pretty sure we established the inheritance from preceding sibling as a means of 
avoiding
having to repeat renderas on each module in a sequence of similar elements. I'm not
convinced that the convenience is worth the potential confusion.

If others feel the same way, I can suggest three other approaches to indicating how a 
resource is to be rendered:

1.  Establish default conventions for how elements are rendered.

  a.  Children of a module with renderas="book|part" would be rendered as chapters. 
Use renderas if you need preface or appendix.

  b.  Children of a module with renderas="chapter|appendix|preface" would be rendered 
as sections.

  c.  Children of sections would be rendered as sections.

However, this has the same problem as the preceding sibling scheme: how do you turn 
off the default rule when you just want to use the element name from the resource?

2.  On the parent module (or structure), allow an attribute that indicates what the 
rendering of children would be unless otherwise specified (attribute name to be 
decided):

 <structure renderas="book" renderchildrenas="chapter">
    <module renderchildrenas="section">

This also has the same problem as the preceding sibling scheme: how do you turn off 
the inheritance rule when you just want the element name from the resource?

3.  Allow DocBook hierarchical element names in place of module:

<structure renderas="book">
  <chapter resourceref="...">
    <section resourceref="...">

With RelaxNG, we can specify different content models for "chapter" within a 
structure.  In this model, these new elements would *not* permit renderas, because the 
element name serves that purpose. You could still use a module element with renderas, 
or a module element without renderas to get the resource's element name. In this 
scheme, there are no implied rules or inheritance, just that <chapter> is equivalent 
to <module renderas="chapter">.

Here is one example from Norm's book:

<structure xml:id="user-guide">
  <output renderas="book"/>
  <info>
    <title>Widget User Guide</title>
  </info>
  <module resourceref="full-toc"/>
  <module resourceref="tut1">
    <output renderas="chapter"/>
  </module>
  <module resourceref="tut2"/>
  <module resourceref="task1"/>
  <module>
    <output renderas="appendix">
    <info>
      <title>Troubleshooting</title>
    </info>
    <module resourceref="tut3">
      <output renderas="section"/>
    </module>
    <module resourceref="task4"/>
  </module>
  <module resourceref="index"/>
</structure>

And here it is rewritten with the new element names:

<structure xml:id="user-guide">
  <output renderas="book"/>
  <info>
    <title>Widget User Guide</title>
  </info>
  <module resourceref="full-toc"/>
  <chapter resourceref="tut1"/>
  <chapter resourceref="tut2"/>
  <chapter resourceref="task1"/>
  <appendix>
    <info>
      <title>Troubleshooting</title>
    </info>
    <section resourceref="tut3">
    <section resourceref="task4"/>
  </appendix>
  <module resourceref="index"/>
</structure>


I think I'm leaning toward option 3 for clarity and ease of authoring.  Comments?


Bob Stayton
Sagehill Enterprises
bobs@sagehill.net