structure vs. module

["Bob Stayton" <bobs@sagehill.net>]

I'm following up on my action item to delineate the differences between the structure
and module elements in an assembly.

Description of elements
-----------------------------
module comes in two flavors: resource module (has resourceref attribute) and container 
module (no resourceref).

A container module is intended to contain literal content.  It can contain optional 
filterin, filterout, and output elements to help define structure, followed by a 
single DocBook element as its content. A container module currently cannot contain a 
sequence of DocBook elements.

Container module attributes are chunk, contentonly, omittitles, and renderas (although 
omittitles makes little sense here because no content is pulled in from another 
resource). It does support a contentonly="yes" attribute, so one could get a sequence 
of literal elements in the output by omitting the single literal element wrapper.


A resource module is intended to point to a resource for its content.  It can contain 
filterin, filterout, and output elements to help define structure, followed by title, 
info, and override elements, followed by optional navigational elements (bibliography, 
glossary, index, toc), followed by zero or more of modules, followed by optional 
navigational elements.


Resource module attributes are chunk, contentonly, omittitles, renderas, and 
resourceref.


The structure element's content is nearly identical to the resource version of module, 
with the addition of revhistory and the omission of resourceref attribute. Structure 
currently allows override, but not clear what it is overriding if it has no 
resourceref.

Structure attributes are defaultformat, renderas, and type.


Discussion
------------------
Structure defines the root element of the output. It names the element with renderas, 
which currently is not required (should it be?).  Structure currently supplies no 
content itself, so all of its content comes from its children.

The structure content model is nearly identical to resource module (minus resourceref 
attribute).

Question: is it the expectation that any common DocBook attributes on structure are 
copied to the rendered output element?  If so, that makes structure a standin for the 
output element.  If not, where would such attributes come from?

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net