On Sat, Jul 7, 2018 at 7:41 AM Arthur A. Gleckler <xxxxxx@speechcode.com> wrote: > On Fri, Jul 6, 2018 at 1:54 PM Ciprian Dorin Craciun <xxxxxx@gmail.com> wrote: >> 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 > > > I have a few suggestions, mostly to do with HTML rendering: > > It takes a long time to load. > Perhaps hosting with a CDN or on a site like Github or Gitlab would help, too. But I suspect that hosting is not the problem since ping times to your domain are fine. According to Google Pagespeed Insights, compressing the libraries.html page with Gzip would yield a 91% reduction in page size. Indeed that single file is about 2 MiB and even my browser struggles to handle it... (I tried it from an iPhone but the browser "broke"...) (The reduction that Google PageSpeed suggested was from an embedded CSS to include the Fira Sans and Fira Mono fonts.) > It would be nice to break the site into smaller pages or otherwise optimize load and display time. After a few days of tinkering with the code here it is: https://data.volution.ro/ciprian/c7be0c0ba57fbe06fc342c1fdd27adc1/documentation/libraries-html/r7rs/_index.html If one is curious it even "renders" nicely on GitHub (thus it would allow one to embed the documentation right into the source code of his library): https://github.com/volution/vonuvoli-scheme/blob/development/documentation/libraries/r7rs/_index.md#library__r7rs The entire "tree" is also available as a CPIO archive (one for the HTML files and one for the CommonMark files): https://data.volution.ro/ciprian/c7be0c0ba57fbe06fc342c1fdd27adc1/documentation/libraries-html.cpio https://data.volution.ro/ciprian/c7be0c0ba57fbe06fc342c1fdd27adc1/documentation/libraries-md.cpio > It would be nice to have responsive CSS so that it displayed well on mobile devices. Right now, the fonts in particular are too small. At first, it doesn't seem like mobile use of information like this would be important, but I find myself looking things up with my mobile phone in spare moments all the time. Indeed the the mobile experience is lacking at the moment. (The CSS is "responsive" in the sense that it scales with the width of the viewport, but for some reason indeed the font is not readable...) I'll have to look into it... > Providing output in other formats, perhaps through Pandoc, would be great. For example, I would love to have this in Emacs Info format for quick, searchable, offline reference. I've tried to use Pandoc to produce PDF and TexInfo files, but the outcomes are not that "nice" (as compared to the HTML version). However I think it is trivial to take another approach: adding support for the desired formats "natively" (i.e. by modifying the Rust code) based on the generated CommonMark. This should be quite straight forward especially since the same approach was used to generate the HTML formats. On the other hand, based on the provided JSON file -- which contains all the information from the source S-expression based file, plus the additional information that is derived by the Rust code (like links to-and-from definitions and types, recursive type membership, etc.) -- one can create custom renderers for additional formats. > I've never used it, but Language Server Protocol (Wikipedia, Langserver.org) appears promising. I wonder whether your file format has the information necessary to support such a server for Scheme. I've taken a quick look, and from what I gather, I think this could be implemented as a separate project that would consume the JSON file mentioned previously, and interact with the IDE. (However one has to take into account how many "users" would be for such a tool...) > Thanks again for embarking on this project. This is great. I'm glad I was able to help. I just hope we can make the Scheme ecosystem move more closely to a more "integrated" and "interconnected" world. I still have some "features" on the "TODO-list": * adding support for `import` specifiers; (i.e. given a definition, say `infinite?`, the user is made aware that it has to "import" it as `(import (scheme inexact))`;) * adding support for inter-library references; (like for example another library documentation file should be able to reference `code-point-ascii` from the `r7rs` one;) * adding explicit support for examples (which right now can only be included in the description), which with the help of `(assert <some-expression>)` could be transformed into tests; Ciprian.
