Re: [docbook-tc] DocBook assembly: inheritance of renderas

[Scott Hudson <scott.hudson@schneider-electric.com>]

I'm worried about this getting too complicated. Perhaps we should just
forget the inheritance and require the use of renderas when you specifically
need to override the base element name.

I really don't like the renderchildrenas attribute, and am not a fan of
adding the hierarchical element names (at that rate, we might as well just
go back to Xincludes).

If we want to establish default conventions as presented in option 1, that
would be OK, but agree that the override would get confusing.

My vote is no inheritance, explicitly call renderas for override and no to
adding the hier elements...

Thanks and best regards,

--Scott

Scott Hudson |  Pelco by Schneider Electric | United States | API and
Integration - Strategy
Ph: +1-970-282-1952  | M: +1-720-663-7268 |
scott.hudson@schneider-electric.com





On 7/25/11 12:45 PM, "Bob Stayton" <bobs@sagehill.net> wrote:

> 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
> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
> 
> 
> ______________________________________________________________________
> This email has been scanned by the MessageLabs Email Security System.
> ______________________________________________________________________