On Mon, Mar 26, 2018 at 9:28 PM, Arthur A. Gleckler <xxxxxx@speechcode.com> wrote:
>
> 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.
>
> [...]
>
>> 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.

I think starting from Shiro's wiki "database" would be much more easy.
I've taken a look at a few SRFI's he has indexed, like for example
SRFI-1:

  https://practical-scheme.net/wiliki/schemexref.cgi?SRFI-1

And these wiki files might be trivial to parse.

> 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.

This could be a second source of information in addition to Shiro's wiki.

In fact I imagine we can build the final "database" from multiple
sources, each with varying degrees of "certainty", with definitions
imported via various automatic mechanisms being labeled something like
"discovered", and manually entered and verified being labeled as
"definitive" or similar.

>> 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.

I don't think we need that all authors "fill" the data for their
SRFI's.  I imagine that the willing authors will fill the data for
their own SRFI's, meanwhile as time permits they can contribute other
SRFI's in a collaborative manner.

> 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.

I agree.  This works best with the Git pull workflow.

>> 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.

I'll try to come up with an s-expression based format that will catch
the minimum information and see where we can go from there.

I will provide the example for SRFI-1 (as I've manually built that
list myself), and also for R7RS (which although not an SRFI I think
needs to be present in such an index, especially since many of the
R7RS definitions are borrowed from various SRFI's, and many SRFI's
re-export some R7RS definitions).

As a side-note, I am accustomed with Racket, and such I'll use that as
the environment.  Does anyone have any objections?  Moreover the
format I will propose will be as simple as possible so that one can
use standard functions (basically `assoc` and firends) to handle it,
and at the same time to be 1-to-1 convertible to JSON so that we can
build HTML views over this data.

> 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.

I imagine that having an HTML-based definition extraction would be
easier for the SRFI writers, however it wouldn't convey too much
information except the name and perhaps the type.  However, see the
following paragraph.

> 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.

Exactly.  One could use a standard HTML block element like `div` to
encapsulate all the "specification" of a particular definition.  Like
for example:

    <div id="srfi-1-cons*" class="srfi export function">
    ...
    </div>

    <div id="srfi-xx-receive" class="srfi export syntax">
    ...
    </div>

Thus we can easily insert these "markers" in existing HTML without
changing their formatting, or other "visible" aspects, and have a
minimal "interlinked" document.

Moreover some SRFI's already have "linkable" definitions.

> 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.

For now feedback and ideas are welcome.

In the end I hope that we'll get some "searchable" functions index
like many other languages have.  (And perhaps also one for R7RS for
which the only "official" documentation still is the original PDF...)
:)

Ciprian.