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.
I would like to see two things:
1. Concrete examples of markup, external files, etc. applied to a few existing SRFIs.
2. More importantly, concrete explanations of exactly what we hope to achieve by doing this work. This might be staged into levels of ambition and work, e.g. perhaps starting with simply indexing all the names defined by each SRFI and ending with full documentation of all procedures and syntax along with their arguments, argument types, return types, and descriptions.
I'm working on some experiments on the five SRFIs I listed before, making minimal changes to HTML markup with the unambitious goal of automatically indexing macros and procedures and collecting their arguments' names and whether they're required or optional. This markup may not prove to be sufficient or even desirable, but I'm going to try the experiment and see what happens.
I find concrete examples super helpful for understanding this kind of problem. I encourage everyone to try their own experiments so we can compare results.