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

Re: Proposal to add HTML class attributes to SRFIs to aid machine-parsing Lassi Kortela 07 Mar 2019 22:18 UTC

I'm afraid I still don't quite understand what is meant by reliable and
comprehensive argument signatures.

What would be a reliable source of this information?

* You could copy from the text of the SRFI document and then verify by
hand. The auto-extractor already does basically this same thing -- it's
just as easy (if not easier) to hand-verify auto-extracted definitions
as it is to verify hand-copied ones. And if we're really unlucky, the
signature in the SRFI might have a misprint so the possibility of error
is still non-zero.

* You could run a Scheme implementation that implements the SRFI in
question, then use the introspection facilities in that Scheme to get
the information. I'm still not sure that the information would be
reliable and comprehensive for our purposes -- there are often small
implementation-specific variations in e.g. the exact data type used to
implement something. And if we're unlucky, the SRFI implementation might
be partial or divergent from the source document. You would still have
to verify by hand. Plus extracting things via Scheme introspection is
not as easily reproducible as extracting things from the HTML, because
you'd have to run particular Scheme interpreter(s), and particular
versions of them, possibly with the right options.

It seems to me that no matter which approach is chosen, there is an
approximately equal possibility of error. So I still don't see what can
go wrong with auto-extracting signatures from HTML that can't go wrong
with the other approaches.

The reason I'd really like to do that, apart from the simplicity of the
tooling (just feed the static HTML files to a simple script), is that
the tool would check that HTML and S-expression metadata stay in sync.
So if we discover some error or omission in the S-expressions, we are
"forced" to go back to the HTML and fix the situation at its source.
Unfortunately my experience is that human-updated things that are not
checked by computer simply do not stay in sync for any length of time :/

We could just as well have a tool in the other direction (i.e.
auto-update the HTML based on the S-expressions) but I expect that would
be too difficult to even attempt.

With more comprehensive signatures, do you mean things like this:

     (make-vector
      (type constructor)
      (export scheme:base)
      (signature
       ((range-length-zero) -> vector-empty)
       ((range-length-zero any) -> vector-empty)
       ((range-length-not-zero) -> vector-not-empty)
       ((range-length-not-zero any) -> vector-not-empty))
      ...)

Those seem like type constraints of some kind. Where do they come from?