On 2019-03-05 15:00, Lassi Kortela wrote: > Hello, > Hello Lassi et al. > This is a proposal to gradually add a standardized set of HTML class > attributes to the SRFI source documents. The classes would encode > metadata that can be used to index all symbols defined in SRFIs. s/symbols/forms/? > General information about the SRFI (date, author, abstract, status, > license, etc.) could also be encoded. > > I made a simple SRFI symbol index (<https://schemedoc.herokuapp.com/>) > by screen-scraping the source HTML of all SRFI documents. I wasn't > aware that Ciprian Craciun had already done similar work earlier > (<https://github.com/cipriancraciun/scheme-srfi-index>). These indexes > are useful but contain errors and omissions because scrapers have to > guess where the definitions are in the SRFI. > > Scraping could be made perfectly reliable by adding HTML class > attributes to the SRFI source HTML. I emailed Arthur Gleckler about > this and his initial response was enthusiastic but he suggested that > we have a wider discussion on this mailing list. He also pointed me to > earlier threads started by Ciprian Craciun on this list in 2018: > > * "Is there an index of symbols defined by the various SRFI's?" > <https://srfi-email.schemers.org/srfi-discuss/msg/8163553> > > * "Describing Scheme libraries (and thus SRFI's and R7RS) in a > "machine readable" format (and rendering in various formats)" > <https://srfi-email.schemers.org/srfi-discuss/msg/8932119> > > The approach described here would be complementary. Ciprian has been > working on an S-expression-based layout for the metadata: the > S-expressions could be generated automatically from the HTML markup > proposed here. In fact, Arthur Gleckler and Per Bothner already hinted > at an HTML-based approach in the earlier thread. > > Why use HTML class attributes instead of another approach? This looks like html microformats (e.g. http://microformats.org/wiki/h-card) I am not sure why they overload the class attribute instead of using more sensible html attribute names given any attribute can be used in css. [...] I might have skipped something but what would be the goal of those classes? Is it to allow to generate indices? or more complicated things language servers or even reference doc for things like https://devdocs.io? I rely on skribe syntax to document my project [1][2] and the main pain point is that editors don't like it much even if looks like s-expressions. That can be fixed. I generate html, I can also generate indices. The intermediate representation is regular scheme data, I even rely on chez scheme expander to generate part of the html [3]. I also have a specific evaluator for things I could not make work (yet) with macros [4]. I find the skribe syntax more powerful than the equivalent racket language that is inspired from latex. [1] skribe source: https://git.sr.ht/~amz3/azul/tree/master/src/scheme/mapping.sfx [2] html rendering: https://vigorous-golick-e57443.netlify.com/scheme/mapping.html [3] https://git.sr.ht/~amz3/azul/tree/master/src/azul/sfx/doc.scm [4] https://git.sr.ht/~amz3/azul/tree/master/src/azul/sfx.scm At the end of the day, my take on this is that the SRFI process should keep a simple approach. Eventually implementations differ in their documentation habits so it is not worth perusing an advanced process that will not help anyway. HTH
