OASIS DocBook TC2

 View Only

RE: [docbook-tc] Re: allow resourceref on structure?

  • 1.  RE: [docbook-tc] Re: allow resourceref on structure?

    Posted 09-07-2011 21:21
    I think that this provides a duplicate of the functionality provided by using a module with the contentonly attribute set to true pointing at the same content that would be pointed to by the resourceref on the structure element. I believe the same result would be achieved by:

    <structure xml:id="mynewid">
    <output renderas="db:book">
    <module resourceref="master" contentonly="true">
    <override><title>My new title</title></override>
    <module resourceref="preface"/>
    ...

    I am hesitant to introduce another element for designating inclusion of content into a document structure, since it makes it more complex to explain the semantics bound to each element. I am not sure the renderas on the structure and the contentonly on the module are required. Structure is a container that could easily inherit the root element of the structure from a module if only one module is a child of it (not difficult to determine with XPATH). If multiple modules are direct children, the user would have to provide a renderas value. In that case, I would suggest adding renderas back as an attribute to the structure element, if it has not already been added back, to simplify providing the wrapper. I think making structure a container AND a mechanism for designating content will be harder to explain (sorry, too many years as a technical writer and tool developer trying to explain markup to writers). The fewer semantic bindings an element has, the easier it is to explain. I like that there is one way to specify content (the module element) -- easier to explain.

    As to whether override is necessary as a child of structure, the original model did not have explicit designation of override vs. other info content. I think in this case, the override could exist just as well as a child of the structure element, since only the content of the module is being included, it would be obvious that the title it would override would be that of the module it is a sibling of, since it is the only title that would be at the same level once the content inclusion is resolved. If the model of using the single-child-module root as root of the structure is adopted, the override would, of course, have to be a child of the module, since the book wrapper would be between it and the title it is overriding.

    LRR