[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [docbook-tc] Re: allow resourceref on structure?
Doesn't seem to be a whole lot of discussion on this, except among the three of us. I think of the module as having a single role, providing content, whether by reference or by explicit inclusion, rather than having two functions. However, that is my own mental model. I still think that making the structure element more complex is the wrong direction, but it is not something I am religious about. To me, root elements are frequently different from elements that are children of them. Perhaps we don't need structure at all, and could just put a class attribute on module if we are going the make the structure a specialization of module (which is, I believe, essentially what you are suggesting). Then a module with a class attribute of "root" could be a valid child of assembly, while the children of a module with class of root have to have no class attribute. Not sure I can represent that in a DTD, but more modern schema representations can probably handle it. I guess the last was somewhat facetious, but I find not find the idea of structure being a specialization of module to be compelling. If it makes things easier to implement, I would prefer a more complex structure element to not having a working system. I am pragmatic about most things, dogmatic about very few. Regards, Larry -----Original Message----- From: Hudson, Scott [mailto:Scott.Hudson@schneider-electric.com] Sent: Tuesday, September 13, 2011 10:50 AM To: Bob Stayton Cc: Rowland, Larry; docbook-tc@lists.oasis-open.org Subject: Re: [docbook-tc] Re: allow resourceref on structure? I am in favor of allowing it. --Scott On Sep 13, 2011, at 10:36 AM, Bob Stayton wrote: > 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 >>> >>> > > > ______________________________________________________________________ > This email has been scanned by the MessageLabs Email Security System. > ______________________________________________________________________
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]