Re: [docbook-tc] assembly metadata

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

sorry for the delay. Been a bit pressed for time. My opinions inline... [sh]

--Scott

On 12-Feb-10 11:56 AM, Bob Stayton wrote:
> 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.
[sh] yes, thanks.
> 2.  Define the content of info like the DocBook 5 info element.
[sh] yes, consistency will be nice, and ability to reuse the same 
pattern or extend that pattern in customizations would be easier.
> 3.  An info element in <structure> can contribute to the output, just 
> like the info element on the root element of a document.
[sh] Probably implementation specific, but makes sense.
> 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.
[sh] Again, probably implementation specific but would not expect to be 
in rendered output by default.
> 5.  Permit <override> only on <module>.
[sh] Not sure I like the element name, but whatever mechanism we decide, 
it makes sense to override on module when needed.
> 6.  Define the content of <override> to be only those elements that 
> make sense to be overridden.  Not sure what that list is, though.
[sh] Probably title, numbering (override label from content). Can't 
think of others.
> 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.
[sh] might be easier to implement this way. kind of like a transclude?
> I don't much like the name <override>, so I'm open to suggestions.
[sh] no idea. I agree, I don't like the name override, but don't like 
the name transclude either...
> Bob Stayton
> Sagehill Enterprises
> bobs@sagehill.net <mailto:bobs@sagehill.net>