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