Opening discussion of the Assembly schema

["Rowland, Larry" <larry.rowland@hp.com>]

As requested at the last TC meeting, I am initiating a discussion of
how well the current schema at top of tree reflects the recent 
discussions of the assembly at TC meetings.

I applied the attached RNC version of the top of tree assembly schema,
provided by Norm, to three recent sample files generated during the
discussions of the assembly and relationship elements.  The following
comments are based on elements and attributes that were not allowed by
the current schema (or behaved differently than the discussions
assumed) but were included in the files and were necessary to
accomplish the outcomes described in the discussions of the files.
The assembly schema is a flattened schema and quite large, so doing a
thorough analysis of it will take some time, but this should be a good
starting point for the discussion.

The names of the attributes and elements are open for discussion.  The
semantics they represent are missing.  The values of the attributes
are representative, not necessarily exhaustive (this is, after all,
intended to stimulate discussion).

1) The element "manifesttext" is missing.  It is intended to provide
   descriptions of the resources for a manifest document generated by
   parsing an assembly that has a set of resources designed to be
   reused across assemblies, to support easy reuse of shared
   resources.  It replaces a proposed description attribute that was
   rejected due to localization concerns about putting editable text
   in an attribute.  It is intended for simple (typically a sentence
   or phrase) descriptions, so little, if any, markup should be
   allowed inside it.  I assumed CDATA.  
   A) The element "manifesttext" should be allowed as a child of
      "resources."
   B) The element "manifesttext" should be allowed as a child of
      "resource."

2) The attribute "format" on the "output" element originally allowed
   multiple tokens rather than a single one.  This was to allow a
   single output element to bind a characteristic to multiple output
   formats (such as webhelp and ohj, which frequently have similar
   delivery structures).  If it does not allow multiple tokens, the
   same result can be achieved by repeated binding of the
   characteristic to multiple output statements, but the intent may be
   less obvious.
   
   Allowing the tokens to include name spaces was also discussed,
   supporting something like "dita:webhelp" to indicate the output is
   in the form of a webhelp system described by DITA as opposed to
   "db:webhelp" which would specify a DocBook Webhelp system.

3) It may be desirable to allow the element output in more positions
   as a child of structure, it currently has to precede title, which
   was somewhat confusing, as I initially concluded it was not allowed
   as a direct child of structure.  I had title and titleabbrev
   preceding the output elements in one file, but following it in
   another or I would have concluded it was not allowed as a child of
   structure based on a single instance that had it in the wrong
   position.  Similar concerns apply to positioning it inside a
   module.

4) The attribute "chunk" should be allowed on the element "output," as
   well as on "module," to deal with situations where chunking needs
   to be specified for one output but not for others into which the
   same structure is being rendered.  If specified on a module as well
   as on an output element that is a child of the module, the value of
   the attribute on the module is the default for all outputs and the
   value on the output element overrides the default for the specified
   outputs.
   
5) The attribute "linking" needs to be added to the element "instance"
   to allow specifying the type of linking.  Example values include
   "targetonly" and "destinationonly," and "pathshome," and
   "listdestination."  This is the name of the attribute used for much
   the same purpose in DITA.

6) The attribute "type" should be allowed on the element
   "relationships" to allow defining groups of relations with specific
   characteristics based on the type specification.  Example values
   include "pathlist" and "lists."

7) The element "instance" needs to be added as a child of
   "relationships" to support the use of relationships to describe
   combinations of paths through documentation.


Larry
=======================================================================
[ Larry Rowland             | If you want to build a ship, don't drum ]  
[ MSL/QST+CSI               | up the men to gather the wood, divide   ]
[ Hewlett-Packard           | the work, and give orders. Instead,     ]
[ 3404 East Harmony Road    | teach them to yearn for the vast and    ]
[ Fort Collins, CO  80528   | endless sea. - Antoine de Saint Exupery ]
[ Phone: 970/898-2280       +-----------------------------------------]
[ E-Mail:larry.rowland@.hp.com                                        ]
=======================================================================

assembly.rnc

docbook.rnc