On Mon, Mar 26, 2018 at 9:01 AM, Ciprian Dorin Craciun
Current SRFI editor here, chiming in.
I've wanted an index of SRFI definitions, exactly as you proposed, for
a while, but as you all have been discussing, it's a lot of work.
>
> > Yes, they are in the git repos under
> > working from the source is problematic because
> > you will get purely internal names as well.
> Unfortunately by looking at the first 4 or 5
> repositories on GitHub (the latest updated
> ones), there doesn't seem to be a common pattern
> for conveying the reference implementation. For
> example:
>
> * SRFI 153 has only HTML files;
SRFI 153 is in draft status. The implementation
will be included in the Git repository as soon as
it is ready. (Generally, I discourage publishing
SRFIs before their implementations are ready for
review, but I have wanted to encourage people to
contribute, so I haven't been rigid about that.)
> * SRFI 150 has an `./srfi` folder with various
> sources, some which seem to include other SRFI's
> (perhaps dependencies);
Yes, exactly. Those are dependencies. Many
authors like to include them.
> * SRFI 48 seems to have only tests;
Actually, the implementation of SRFI 48 is in the
HTML itself. Especially in older SRFIs, this was
the way things were often done. I generally
discourage that except for the smallest
implementations, but I haven't extracted the
implementations from older, finalized SRFIs. I
would welcome the effort if someone was willing to
do it.
I should note that some SRFIs implement features
that are necessarily so tied to the Scheme
implementation that they can't be extracted into a
separate SRFI implementation. In those cases, the
SRFI text points to the source code repository of
the implementation. For example, see SRFI 159.
Authors of other Scheme implementations are
encouraged to look at that code and how it is
integrated as an example.
> That is why I wondered about an "official" place
> where all the reference implementation sources
> were available.
The Github repositories (and any mirrors people
would like to set up) are the closest things we
have.
> Parsing the HTML specifications I think would
> yield too many false-positives (i.e. symbols
> which are in fact not defined by that SRFI).
I agree. It might be a good way to start a draft,
though. Putting something on the internet that is
wrong is a great way to motivate people to produce
the right thing, even if only incrementally.
Starting from scratch is much harder.
While many recent SRFIs include library or module
definitions, which makes at least enumerating the
defined identifiers easy, many do not. Still, one
could use what library definitions there are to
filter out internal definitions and symbols
referenced but not defined in an SRFI.
> Would the SRFI community and authors be willing
> to fill in such a "database"? (I'm not asking
> about implementing the forms, just about the
> willingness to fill them.)
That sounds like a nice idea.
One thing to remember, though, is that the SRFI
process has been going on for twenty years now, so
some of the authors are no longer involved, or are
hard to reach for one reason or another.
The best way to make progress on this would be to
set up some system that makes it easy to
contribute incrementally, so that SRFIs that are
being actively developed or used would get the
most attention, and so others can be filled out
later, if at all. If we try to absorb the whole
corpus at once, we're likely to get stuck.
> Better yet, instead of a "form-based system" we
> could create a Git repository (on GitHub), and
> specify an s-expression format that would
> "collect" all the data. Thus by using pull
> requests we can start filling this in.
> (Afterwards I could cobble something to generate
> the HTML and other useful export formats based
> on that data.)
I like this idea best, and would welcome and
encourage any work on it. May I suggest that you
propose such a metadata format and collect the
definitions in one or two widely used SRFIs as
examples? I'd be happy to put such a definitions
file in the Git repository for each SRFI and, once
a few people have said they like it, to advertise
it and declare it official.
Another idea I have been toying with is a standard
way to declare definitions in HTML files, e.g. a
set of HTML classes to use when writing a
definition in HTML. If that's lightweight but
machine- readable, we could encourage authors of
new SRFIs to use that format, making extracting
definitions easier. On the other hand, if your
s-expression-based definitions format is
lightweight enough, producing it manually may be
more expedient, flexible, and practical.
For a while, I thought it would be nice to include
a description of each definition in such a
metadata format. However, extracted those
descriptions would be a lot of work, and would
lead to us having to deal with HTML markup,
textual context, etc. Perhaps the best way to
deal with the issue of mapping definitions to
their descriptions would be to include HTML
anchors in the SRFI documents next to each
definition. Then one could refer to each anchor
from outside the file, e.g. in the metadata file.
But I would recommend going with something dead
simple, but extensible, to start with, because
adding features, and therefore work, is a surefire
way to stall this project.
Thank you very much for bringing up the idea, and
thank you in advance to you or to anyone else who
helps to bring it to life. Please let me know if
there's anything I can do to help turn this idea
into a reality.