[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook-tc] Re: allow resourceref on structure?
I just wanted to mention that I'll be starting a three-week vacation starting 20 September, so I won't be able to attend the next DocBook TC meeting. But I would like to get resolution on my proposal without waiting another month, so I would like to request that we settle it via email before 20 Sept. To reiterate, my proposal is to allow a resourceref attribute on structure, giving it the two roles of container and content provider in parallel with the same two roles on module. That would permit structure to optionally specify a resource that defines the top-level content, including the root element. The top-level resource would be similar to the current usage case of a master book file with XIncludes, but without the XIncludes (because they are provided by the modules in the structure element). Bob Stayton Sagehill Enterprises bobs@sagehill.net ----- Original Message ----- From: "Bob Stayton" <bobs@sagehill.net> To: "Rowland, Larry" <larry.rowland@hp.com>; "Hudson, Scott" <Scott.Hudson@schneider-electric.com>; <docbook-tc@lists.oasis-open.org> Sent: Monday, September 12, 2011 12:02 AM Subject: Re: [docbook-tc] Re: allow resourceref on structure? > Hi Larry, > I was almost convinced by your arguments. However, they may make us re-examine the > module element. You said: > >> I think making structure a container AND a mechanism for designating content will >> be harder to explain ... > > The module element is also a container and a mechanism for designating content. The > content model is: > > db.module = db.resource.module | db.container.module > > The container version does not take a resourceref attribute. It is replaced by an > element whose name is designated by its renderas value (either its @renderas or its > child output element's @renderas), but provides no other content. The resource > version of module requires a resourceref that pulls in content from a resource. > > Essentially my proposal is to make structure a specialized version of module, one > that can appear only at the top level. If we can explain the two roles for module, > then I think calling structure the "root module" will be straightforward to > explain. > > Bob Stayton > Sagehill Enterprises > bobs@sagehill.net > > > ----- Original Message ----- > From: "Rowland, Larry" <larry.rowland@hp.com> > To: "Hudson, Scott" <Scott.Hudson@schneider-electric.com>; <bobs@sagehill.net>; > <docbook-tc@lists.oasis-open.org> > Sent: Wednesday, September 07, 2011 2:15 PM > 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]