OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-tc message

[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]