[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [docbook-tc] Re: allow resourceref on structure?
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
-----Original Message-----
From: Hudson, Scott [mailto:Scott.Hudson@schneider-electric.com]
Sent: Tuesday, August 30, 2011 11:17 PM
To: bobs@sagehill.net; docbook-tc@lists.oasis-open.org
Subject: Re: [docbook-tc] Re: allow resourceref on structure?
I agree...
Sent from myTouch 4G
----- Reply message -----
From: "Bob Stayton" <bobs@sagehill.net>
To: "Bob Stayton" <bobs@sagehill.net>, "DocBook Technical Committee" <docbook-tc@lists.oasis-open.org>
Subject: [docbook-tc] Re: allow resourceref on structure?
Date: Tue, Aug 30, 2011 9:56 pm
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
bobs@sagehill.net
----- Original Message -----
From: "Bob Stayton" <bobs@sagehill.net>
To: "DocBook Technical Committee" <docbook-tc@lists.oasis-open.org>
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>user@example.com</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>user@example.com</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>user@example.com</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
> bobs@sagehill.net
>
>
> 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.
______________________________________________________________________
---------------------------------------------------------------------
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]