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.
