>> Could we get everyone's opinion on this issue, as it may be the
>> biggest detriment to forming a consensus? Who would rather have
>> somewhat clumsier markup but require only a single HTML file, and who
>> would rather have separate HTML and metadata files if it means the
>> HTML markup can be somewhat cleaner?
>
> My vote is clear:  Simpler (X)HTML format just indexing and back-referencing.
> (This could include the name, description and perhaps examples.)
>
> Another proposal should cover the heavier syntax meta-data.

OK, we are in pretty fundamental disagreement about what to do here :)

I think we should make a decision about this before starting work on
anything concrete since it will have a drastic impact on most
near-future tasks.

My vote is still to have all metadata in the HTML file, but if a
different decision is made I will co-operate with it.