Describing Scheme libraries (and thus SRFI's and R7RS) in a "machine readable" format (and rendering in various formats) Ciprian Dorin Craciun (06 Jul 2018 20:54 UTC)

Describing Scheme libraries (and thus SRFI's and R7RS) in a "machine readable" format (and rendering in various formats) Ciprian Dorin Craciun 06 Jul 2018 20:54 UTC

Some time ago I've opened a thread on this mailing list called `Is
there an index of symbols defined by the various SRFI's?` (
https://srfi-email.schemers.org/srfi-discuss/msg/8166455 ).
After some discussions I've proposed a S-expression based format of
describing Scheme libraries (including SRFI).

For reference that proposed format was specified here:
* https://github.com/cipriancraciun/scheme-srfi-index/blob/master/syntax-specification.txt
* https://github.com/cipriancraciun/scheme-srfi-index/blob/master/syntax-examples.txt

Now, a few months later, I submit for your consideration (and
feedback) the following S-expression-based file that describes the
entire R7RS standard:
* https://data.volution.ro/ciprian/c7be0c0ba57fbe06fc342c1fdd27adc1/documentation/libraries.ss

Unfortunately this Scheme file uses an extension for "raw-strings" of
the form `#<<< ... >>>#`, which is custom for the Scheme interpreter I
am working on.  However one can replace that with a simple string
(provided one escapes quotes).  Moreover the syntax (i.e. how the
S-expressions are structured) does not exactly follow the original
proposal, but it expands upon that proposal by allowing more enhanced
syntax and procedure specifications, and a more complex "type-system".

However I hope that most of its contents (including syntax and
semantic) is pretty self-explanatory.  (Perhaps except for some type
related attributes...)

Based on that file I was able to generate the following files:

* https://data.volution.ro/ciprian/c7be0c0ba57fbe06fc342c1fdd27adc1/documentation/libraries.html
(An HTML rendering ready for "human consumption" in a browser.  For
the moment it is a single -- quite large -- page that is
self-contained.)

* https://data.volution.ro/ciprian/c7be0c0ba57fbe06fc342c1fdd27adc1/documentation/libraries.md
(An CommonMark rendering, which is in fact the basis for the HTML rendering.)

* https://data.volution.ro/ciprian/c7be0c0ba57fbe06fc342c1fdd27adc1/documentation/libraries.json
(A JSON file containing all the data from the S-expression-based file,
but structured as JSON for easy consumption especially by web-based
applications.)

As highlights of what is possible to specify I suggest looking at the
`do` syntax, which dissects the various patterns used:
* https://data.volution.ro/ciprian/c7be0c0ba57fbe06fc342c1fdd27adc1/documentation/libraries.html#definition__r7rs__do

For a procedure please see `=` or `make-rectangular` whose signature
should be from "top-to-bottom" with the first match winning:
* https://data.volution.ro/ciprian/c7be0c0ba57fbe06fc342c1fdd27adc1/documentation/libraries.html#definition__r7rs__3d
* https://data.volution.ro/ciprian/c7be0c0ba57fbe06fc342c1fdd27adc1/documentation/libraries.html#definition__r7rs__make-rectangular

As for the "type system" currently used one can look at the simple
`boolean` type, followed by `char` or `list` (with shows multiple
"super" relations), and last the `number` type:
* https://data.volution.ro/ciprian/c7be0c0ba57fbe06fc342c1fdd27adc1/documentation/libraries.html#type__r7rs__boolean
* https://data.volution.ro/ciprian/c7be0c0ba57fbe06fc342c1fdd27adc1/documentation/libraries.html#type__r7rs__character
* https://data.volution.ro/ciprian/c7be0c0ba57fbe06fc342c1fdd27adc1/documentation/libraries.html#type__r7rs__list
* https://data.volution.ro/ciprian/c7be0c0ba57fbe06fc342c1fdd27adc1/documentation/libraries.html#type__r7rs__number

Thus I would like to kindly ask the community to provide feedback.
(Any feedback is welcomed.)

I am especially interested in the following areas:
* what "features" I've missed, which would allow the user to "better"
describe his library;
* what can be improved in the HTML rendering to have it more "human-friendly";
* what other "outputs" might be generated based on this?

In order to better "guide" this feedback, please take into account the
following:
* the purpose of the proposed S-expression-based syntax is to be able
to "specify" (and also "document") the various entities exported by a
library (including procedures, syntaxes and constants);
* the type-system's main purpose is to provide a kind of pre-condition
/ post-condition to the procedure inputs / outputs, and thus provide
the user with more structured information about the values accepted;
(it is not meant to be an actual type system like the one used by
Racket;)
* I have tried to provide both support for "structured-data" (like
signatures or the type system), but also for "documentation" (like the
descriptions that support CommonMark, the links (currently not
implemented), and appendices;)
* one of the main outcomes should be human-friendly documents and
web-applications, that would allow the user to better "explore" and
"discover" libraries;
* documenting SRFI (and R7RS) are not the only "targets", but any user
library;  (and in fact my main driver in implementing this is to
provide a documentation for my Scheme interpreter;)

If one is curios about the implementation:
* it has **zero** Scheme/Lisp code (except the input document);
everything is implemented in Rust;  (the reasons are pretty straight
forward:  efficiency, self-contained tool, etc.;)
* it is open-source, available on GitHub, however at the moment (due
to its "immature" status) I wouldn't like to make it "public";  (but
see the last point;)
* the tool reads and parses the Scheme expressions, and generates an
internal "object model";
* that "object model" is then exported as JSON or alternatively it is
rendered as CommonMark;
* the same tool can internally take that CommonMark and re-render that as HTML;
* the tool is a self-contained "native executable" with **zero**
dependencies on any (native or not) libraries;  (currently it compiles
only on Linux, but I bet one can easily compile it on any OS supported
by Rust, especially since the documentation part doesn't use any
OS-related code;)
* the tool (especially the documentation part) is quite "pre-alpha"
and provides almost no useful feedback in case of errors;
* if anyone is interested in running it, please contact me privately
and I'll try to assist you;

I hope this provides something useful to the Scheme community,
Ciprian.