RE: [docbook-tc] A first stab at documenting assemblies

Norm,

I have been somewhat pressed for time of late, but did want to respond
to your excellent effort at documenting assemblies.  I have put some
comments inline in the attached HTML file, but find the write-up quite
helpful.  I am a little concerned with having to put an info block to
specify a title; I always get a little nervous about noisy markup but 
understand the desire to simplify the structure model.  I had 
anticipated it being more like the current model for title and similar
types of metadata being valid children of structure and module the
same way it works for book and part and component level structures.

For some reason I had to manually set the encoding to "Western 
(ISO-8859-1)" even though the encoding said UTF-8 in the original.  Not 
sure what happened, and can't tell if it was my systems (it happened on 
my Windows and Linux systems) or the transform misbehaving.

Perhaps adding something about a help system would be useful.  I will
likely have some time, since I am off for two weeks starting next
Monday if it would help.

Regards,
Larry



-----Original Message-----
From: Norman Walsh [mailto:] 
Sent: Monday, November 23, 2009 8:40 AM
To: 
Subject: [docbook-tc] A first stab at documenting assemblies

Hi folks,

I'm offline for a bit, distracting myself from other things by trying
to tie up some loose ends. Attached, find my first attempt to document
the assembly proposal.

I did this partly to see if I understood it. No doubt, there are
places where I *miss*understood it; there are certainly a few places
where I changed it to suite what I think are the requirements.
Consequently, I've documented what amounts to a slightly different
proposal.

I'd be interested, in particular, to know what capabilities of the
original proposal cannot be addressed with this one.

The description has two parts, an attempt at high-level exposition and
a few narrative examples. The examples are probably better than the
high-level exposition.