Re: [docbook-tc] assembly metadata

[Scott Hudson <scott.hudson@flatironssolutions.com>]

I think assuming override is undesirable, as there are times when we 
need to provide metadata at the module level, not only at the assembly 
level.

I'm not sure about a dedicated override element, but perhaps an 
attribute on module and assembly to specify whether the metadata should 
be an override of the metadata inside the actual resource?

Best regards,

--Scott

Scott Hudson
Senior XML Architect
+1 (303) 542-2146  |  Office
+1 (720) 663-SCOT [7268]  |  Gvoice
Scott.Hudson@flatironssolutions.com
http://www.flatironssolutions.com





On 17-Feb-10 10:50 AM, Rowland, Larry wrote:
> I would think that an info element that sometimes contributes to the 
> output and sometimes does not would be confusing and possibly 
> difficult to explain.  I am also not sure we need an override 
> element.  Why not assume any content containing element that is a 
> child of a module is intended to override the referenced content.  
> Then add an assemblyinfo element that is explicitly identified as 
> providing information about the assembly rather than the output (or 
> add a role attribute or some other customization mechanism) for 
> information about the assembly.  I think that would be a simpler 
> markup model and easier to explain.
> Regards,
> Larry Rowland
>
> ------------------------------------------------------------------------
> *From:* Bob Stayton [mailto:bobs@sagehill.net]
> *Sent:* Friday, February 12, 2010 11:57 AM
> *To:* DocBook Technical Committee
> *Subject:* [docbook-tc] assembly metadata
>
> I'm following up on my action item to initiate a discussion of 
> metadata in assembly. Here are the minutes from the last meeting:
> --------------------------------------------------------------
> Scott raised the issue of adding info to module and other
> assembly elements to support metadata.  Norm had
> added info in order to hold a title that would override
> the title in the resource it pointed to. Bob objected
> to using info for override content as well as
> metadata for assembly elements.  It was agreed that
> they need to be differentiated.
> ----------------------------------------------------------------
> I'll start the discussion by suggesting that we add an info element, 
> but document it as holding information to describe the current 
> assembly-level element, not the element pointed to.  I would also 
> suggest adding another element, perhaps named <override>, whose 
> purpose is to contain content that is to override the content of the 
> element pointed to.   So if you want a new title to replace the title 
> in a topic, you would put that title into a module's override element.
> <assembly>
> <info>may contain author, revhistory, etc. to this assembly element</info>
> <resources>
> <info>may contain information on who maintains the resource list, 
> etc.</info>
> <resource ...>
> <info>although resource is normally an empty element, it could contain 
> an optional info element</info>
> </resource>
>     ...
> </resources>
> <structure>
> <info>contains metadata about this structure element</info>
> <module>
> <info>contains metadata about this module element</info>
> <override>
> <title>This title overrides the title in the resource that this module 
> points to</title>
> <pubdate>This pubdate overrides that in the topic's info element, if 
> it has one.</pubdate>
>         ...
> </override>
> </module>
> </structure>
> </assembly>
> Here some suggestions for discussion:
> 1. Permit <info> on any element in an assembly.
> 2.  Define the content of info like the DocBook 5 info element.
> 3.  An info element in <structure> can contribute to the output, just 
> like the info element on the root element of a document.
> 4. An info element in any other assembly element generally does not 
> contribute to the output, although I'm sure there are cases where it 
> could.
> 5.  Permit <override> only on <module>.
> 6.  Define the content of <override> to be only those elements that 
> make sense to be overridden.  Not sure what that list is, though.
> 7. Any element in <override> is merged with the content that the 
> module points to, and overrides it if the corresponding element exists 
> in the resource.
> I don't much like the name <override>, so I'm open to suggestions.
> Bob Stayton
> Sagehill Enterprises
> bobs@sagehill.net <mailto:bobs@sagehill.net>