However, I would envisage something a little bit more:
* documents should be XHTML 1.0 strict (i.e.
https://www.w3.org/TR/xhtml1/) and validated with
https://validator.w3.org/; (this would ensure they are proper XML
files, and use only "standard" elements; thus allowing easier
parsing;)
In principle, this sounds good, but in practice, it may be too much to require of authors. First, XHTML doesn't allow some of the flexibility that HTML 5, for example, allows, e.g. omission of closing tags on certain elements. Going back through all our SRFIs and making them XHTML 1.0 strict would be even more work than just adding the classes. Also, it would require authors who generate HTML from other sources to make possibly dramatic changes to that software.
There seem to be plenty of HTML parsers out there, so it should be possible to stick with HTML rather than requiring XHTML.
One valuable test of these ideas would be to convert an entire existing SRFI, trying to make only the minimum number of changes required to support automatic extraction of metadata this way.
I may be wrong, of course. I'd be especially interested to hear feedback from SRFI authors, and from people who know more about XHTML and HTML parsing.
In the end I managed to do a little bit more. Based on the initial
proposed S-expressions format, I've introduced also Markdown-based
documentation support, and with a Rust-based generator, I've generated
the HTML's that can be viewed at:
https://vonuvoli.volution.ro/documentation/libraries-html/_libraries.html
I have spent quite some time finding the best structure and layout.
Very cool.
Once we come up with a good proposal that both of you and a representative set of authors agree upon, we can change
srfi-template.html so that it will be even easier for future authors to follow the new format. I've been planning to incorporate some combination of the CSS and markup from SRFIs
152 and
159 to improve the appearance of future SRFIs, too. It would be great to combine this into one great overhaul of the template.
Once that's done, we can ask for volunteers to go through existing SRFIs to update their markup. Many hands make light work, so if we can get enough people to contribute, we should be able to get it done in short order.
Thanks again to you both.