On Tue, Mar 27, 2018 at 1:33 AM, Arthur A. Gleckler <xxxxxx@speechcode.com> wrote:
> On Mon, Mar 26, 2018 at 2:37 PM, Ciprian Dorin Craciun
> <xxxxxx@gmail.com> wrote:
> | So I gave it a quick try...
> | The **initial** proposed syntax:
> |
> | https://github.com/cipriancraciun/scheme-srfi-index/blob/master/syntax.txt
>
> This looks good to me.  It's more elaborate than I expected, but that seems
> okay as long as it's possible to add information gradually. That appears to
> be the case because much of it is optional.

Yes, this is the case:  I think most of it should be optional, or else
the bar of entry would be too high and people would skip on it.
However for the willing we should capture enough information to be
able to build "browseable" index (and documentation) for the SRFI's.

> Perhaps the argument type information, which you've put in a section labeled
> `contract', should be moved to a section specifically labeled something like
> `signature' since such contracts are, so far, mostly specific to Racket in
> the Scheme world.

Initially I thought to name it exactly as you've said `signature`, but
went with the Racket terminology.  But perhaps you are right,
contracts imply more than the actual signature.

However I don't think having a separate section for signatures would
serve best, as one would have to look in two sections for the same
function.  I think it is best to keep all information pertaining to a
particular definition in the same section (i.e. under the same
S-expression).

> Also, does your `types' section support the kinds of types that Scheme
> procedures often support?  For example, `assq' returns either #f or a pair,
> and the types used in the pair are unspecified.  It looks like it does,
> through the textual description, but I'm wondering whether you want to
> specify a machine-readable convention.  Scheme is dynamically typed, so that
> may not be important, but I'll raise the issue just in case you want to
> consider it.

This is a very good question, and one I don't know how to best tackle
at this moment, except to acknowledge that functions are in fact
typed, and provide a human description for each type.

I have programmed in Erlang, which like Scheme is a dynamic-typed
language, but it does have what they call "type specifications", that
allows them to express, and reason about, such cases where a function
can return different types based.  (In fact they go even further with
the type specifications, to the point where they can express that
certain types are returned only for certain inputs, and moreover if
certain conditions are met.)

  http://erlang.org/doc/reference_manual/typespec.html

This is how they specify `keyfind` function (
http://erlang.org/doc/man/lists.html#keyfind-3 ):

    keyfind(Key, N, TupleList) -> Tuple | false
        Key = term()
        N = integer() >= 1
        1..tuple_size(Tuple)
        TupleList = [Tuple]
        Tuple = tuple()

However as said for the moment I think it is best to define a set of
"builtin" types, (perhaps identified by the R7RS predicate names), and
leave this section open for debate at the moment.

> My only other comment is that hope that you and Shiro can agree on a format
> for foreign keys between your databases so that one can link from entries in
> one of these databases to entries in the other.

I don't think Shiro's index is automatically created.  I believe he
manually filled in all those wiki pages.  Or?

> That might help eliminate
> the need to do manual filtering and re-work as changes are made to one or
> the other.

In any case I think the best "key" for a particular definition should
be as simple as `srfi-x--<identifier>` (note the double `-` separating
the SRFI identifier and the definition identifier.

Or any other key that can be automatically derived given the library
and definition identifiers.  (This process also has to be reversible,
i.e. having the key, deriving the library and definition identifier
without any additional lookup.)

Ciprian.