[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
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]