I would like to formally propose that we allow a resourceref attribute on structure.
My arguments are described below. Since the next meeting is not until 28 Sept, I
thought we could resolve this through email discussion before the meeting. Is it
clear what I'm asking for here? Any agreement or disagreement?
Bob Stayton
Sagehill Enterprises
----- Original Message -----
From: "Bob Stayton" <>
To: "DocBook Technical Committee" <>
Sent: Friday, August 19, 2011 9:20 AM
Subject: allow resourceref on structure?
>
> I'm wondering if the structure element should also permit a resourceref attribute?
> That would allow one to treat the root element as a module also. In that module's
> resource you could define the root element name of the output, its title, and any
> other top-level
> info content, and possibly other top level frontmatter content as well. As with
> other
> modules, any child modules are appended after this content and before its end tag.
>
> This small change would allow an author to keep all textual content out of the
> assembly file and in resource files.
>
> It seems we already allow an override element on structure (5.1b4), yet without a
> resourceref there is nothing to override, no?
>
> Here is a short example:
>
> <resources>
> <resource xml:id="master" fileref="master.xml"/>
> <resource xml:id="preface" fileref="preface.xml"/>
> ...
> </resources>
>
> <structure xml:id="mynewid" resourceref="master">
> <override><title>My new title</title></override>
> <module resourceref="preface"/>
> ...
>
> where the master.xml file looks like this:
>
> <book xml:id="bookid" xmlns="http://docbook.org/ns/docbook" version="5.0">
> <info>
> <title>Book Title</title>
> <author>
> <orgname>Organization Name</orgname>
> <address>
> <city>City</city>
> <street>Street</street>
> <postcode>000000</postcode>
> <country>Country</country>
> </address>
> <email></email>
> </author>
> </info>
> </book>
>
> When processed to a book, this would yield:
>
>
> <book xml:id="mynewid" xmlns="http://docbook.org/ns/docbook" version="5.0">
> <info>
> <title>My new title</title>
> <author>
> <orgname>Organization Name</orgname>
> <address>
> <city>City</city>
> <street>Street</street>
> <postcode>000000</postcode>
> <country>Country</country>
> </address>
> <email></email>
> </author>
> </info>
> <preface>
> ...
> </book>
>
> The top-level xml:id comes from the structure element, and the title comes from the
> override, but everything else in the info comes from the resource.
>
> This resource element could also use the alternate syntax, which is to omit a
> fileref
> attribute and populate the resource element with this book element, so it is visible
> inside the assembly, if that is your choice:
>
> <resource xml:id="master">
> <book xml:id="bookid" xmlns="http://docbook.org/ns/docbook" version="5.0">
> <info>
> <title>Book Title</title>
> <author>
> <orgname>Organization Name</orgname>
> <address>
> <city>City</city>
> <street>Street</street>
> <postcode>000000</postcode>
> <country>Country</country>
> </address>
> <email></email>
> </author>
> </info>
> </book>
> </resource>
>
> Without this change, you could still do a structure with a renderas to specify the
> root element, and the top-level info could still be supplied as a module under
> structure.
> Currently the resource file for that info module could not contain just an info
> element, because DB5
> does not permit info as a root element. But the info could be put inside a book
> element
> in the resource file and accessed either using contentonly="yes" on the module or
> with a fragment identifier
> such as fileref="master.xml#info" on the resource, for example.
>
> Allowing resourceref and override provides symmetry between structure and module in
> how its metadata is handled. Without resourceref, I'm not clear why we would want
> an override element on structure.
>
> Comments?
>
> Bob Stayton
> Sagehill Enterprises
>
>
>
> Bob Stayton
> Sagehill Enterprises
>
>
>
