Email list hosting service & mailing list manager

Re: Proposal to add HTML class attributes to SRFIs to aid machine-parsing Marc Nieper-Wißkirchen (06 Mar 2019 10:12 UTC)
Re: Proposal to add HTML class attributes to SRFIs to aid machine-parsing Lassi Kortela (11 Mar 2019 13:19 UTC)

Re: Proposal to add HTML class attributes to SRFIs to aid machine-parsing Lassi Kortela 11 Mar 2019 13:19 UTC

Things are beginning to look great :)

 > However at the same time I debate what is the usefulness of the
 > "partial" signatures you can automatically extract from the HTML, vs
 > the cost of adding the markup.

 > As hinted in the previous paragraph: what would be the actual
 > usefulness of such partial signatures? How would you use them?

I would have these immediate uses for them:

1) To show a quick overview of a particular definition (e.g. in Emacs,
put the cursor on a procedure name and it shows the expected arguments
at the bottom of the screen).

2) To show a cheat sheet or an index of procedures with arguments. I
generated an example: <>.
It could be formatted more nicely and have links, but shows what I
mean. Personally, Scheme is not my primary language and I tend to
switch languages constantly (as people are often forced to do
nowadays) so I forget details all the time. This kind of detailed
reference card is a huge help when learning a language or refreshing

3) Search for procedures by argument name. This would not be perfect
by any means, but it's one more tool to help find procedures and could
be implemented with almost no extra work from the index.

For these purposes, the main thing would be to have the names of the
arguments, and to see which ones are optional and which are required.
Types would be a nice bonus, but not strictly necessary. A link to the
the SRFI (especially if it's a direct link to the right definition)
would be plenty to get started with.

 > I don't know if the signatures should or shouldn't be part of the
 > actual SRFI repository.
 > I think a better place would be in a completely different "common"
 > repository.

After listening to all your points of view, I'm fine with either

 >> If we are going to developing the static type signatures in the
 >> same S-expression file where the straightforward transcribed stuff
 >> lives,
 > I see nothing wrong with multiple files. The "automatically
 > extracted" signatures could live in separate file than the "manually
 > formalized" signatures. Moreover there could be a simple tool that
 > would cross-check any discrepancies between the two.

The more I think about this, the more I'm beginning to agree.
Especially if the type signatures are stored in different repos.

The cross-checking tool would really be the main thing for me. As long
as we have a simple command that we can run to ask "is everything
synced?" then things will probably be fine. We might even be able set
up a Continuous Integration server to check automatically. The rest of
tooling and format design is just a question of having more vs less
manual work, and those details can be worked out one way or another.

If we use S-expressions for all the metadata files, the cross-checker
will also be easy to write in Scheme, eliminating one more discussion
about which language to use for tooling ;)

 > Please note that the above signature doesn't include argument
 > "names" because I haven't actually added them in the signature,
 > however the underlying format does support them.

OK, then an automatic converter could probably be made to generate
traditional Lispy signatures.

 >> We would have to find some notation that combines these quite
 >> opposing traditions. We could also write them separately, but any
 >> duplication is a chance for discrepancy.
 > The format I proposed supports both. (The variant of `make-vector`
 > above is just a "specialization" of the more "traditional" format.)

 > Also in case of `list-copy` I clearly want to markup that a circular
 > list would raise an error:

That sounds quite advanced :) Is there a circular list detector?