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.