Hi y’all, hi Duncan,

I realize that my comments are tangential to the actual SRFI text, but
so are style changes which I consider to be both unnecessary and
undeserving of a new draft. Comments inline:

>  I have also styled <pre> blocks with shading so that the
>  examples are much more clearly distinguished, and I've adjusted the
>  spacing below them.

Shading <pre>-s is a good change, and I personally think this should be
the default. Arthur, would you be open to such a change in srfi-common?

> I have also adjusted the spacing of the procedure
>  definitions so that it is more consistent, and so that their descriptions below are more clearly linked to the definition immediately above.

I find such layout complications unnecessary, because they break the
flow of reading and make older / simpler / weaker browsers to do
unnecessary work. In my SRFIs, I stick to this structure:

<h3>(srfi XXX) procedure (procedure prototype ...)</h3>

While it is slightly more verbose, it’s dead simple to parse and read,
regardless of a user agent.

>  I have also overridden the default font presentation with a combination of URW Classic Sans (clone of Univers included with Ghostscript) for
>  headings, table structure and test cases, Charter (sans-serif font used in the Racket documentation) for body text, and Roboto Mono for
>  monospace. The R7RS.org website uses URW Classic Sans and it works quite well.
>
>  Roboto Mono is a good match for the section headings as the original Roboto is close to Univers for many characters (e.g. 'G'), and it has
>  good character coverage which helps in the IRIs.

I personally think that fonts should be left out of SRFI documents,
unless these fonts come for global srfi.schemers.org stylesheet. SRFIs
should be simple to parse and read, which means basic HTML and abiding
to user agent fonts.

In particular, someone with OpenDyslexic or Atkinson Hyperlegible fonts
might actually _need_ them to read things comfortably. Unconditionally
overriding fonts hurts accessibility (huge turn-off) and performance
(which is mostly okay, but is a cherry on top of inaccessibility.)
Forcing fonts on readers is not cool, especially for such vital
documents as SRFIs.

> I think it's worth overriding the web browser's own monospace font as it means we can
> match the monospace font to the body text in terms of size.

This is easily fixable with

pre, code {
   font-size: 1em;
}

Including a font solely to “fix” code sizing is an unnecessary burden on
everyone.

Yes, the default browser stylesheets setting code / pre font size to 95%
make a despicable choice, but this is left for discussion elsewhere and
is unlikely to be fixed due to its backwards-compatibility motivation.

>  The procedure index is formatted so that there are no line breaks on hyphens and the procedures do not overflow the notional text width.
>  This also the case in the paragraphs describing procedures (when they link to other procedures).

Note that this might hurt readers on narrow viewports, like smaller
phones. If you force-disable word breaks, the people get unnecessary
horizontal scrollbar in the document. This complicates reading and
scrolling tremendously. See https://aartaka.me/easy-fixes.html#wbr for
context and a fix:

p {
    word-break: break-word;
    overflow-wrap: anywhere;
}

I urge you to roll back fonts and questionable CSS. For those cases
where the changes are actually useful (like with shading of code / pre,)
consider contributing them to srfi-common instead, so that _all_ SRFIs
benefit from more readability.

Again, sorry for this tangential comment, but, again, these CSS changes
are equally tangential and unnecessary in an SRFI.

Best of luck,
--
Artyom Bologov
https://aartaka.me