Duncan,

>> 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.
>
> This is a change made in a previous draft - this adjusts the spacing
> underneath these sections so that it's more consistent when there are
> only one procedure in a block. (You're probably aware of this but the
> CSS is based on SRFI 276.)
>
> Originally, I took an approach like headings but it didn't work very
> well. Specifically, the SRFI exports several libraries, and the document
> is not linearly structured in terms of those libraries (as there is
> effective duplication for URIs and IRIs).
>
> The libraries were their own headings at level h4, and although the
> exported procedures weren't a heading, they were in body-like bold text,
> so that's another level of nesting.
>
> I agree that it is more readable in certain proposals, but they don't
> export many libraries and are generally terser. In writing this out it
> was a constant fight to write more tersely in a way which is clearly
> structured and implementable.

I value simplicity and semantics, thus my recommendation of
headings. Headings can be parsed and a TOC can be made out of
them. Screen readers do that to ease person’s navigation, for
example. So using an ad-hoc heading here is not really semantic and not
really parseable. But I see your argument on noise here, and I realize
the appeal.

In r7rs.aartaka.me and scheme-index.aartaka.me I went for groups of
headings, each following the other. Coupled with proper padding and font
customization, these are really readable. And need no extra support to
work everywhere.

But SRFI styling is ultimately your choice, so I cannot force semantic
elements and simple markup on you here 😜

>> 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 hear you, but I don't understand how this differs from the default
> template, which forces Noto Sans (loaded from Google fonts).

This is a bad choice too. I’d stick to browser fonts by default here.

> If we're
> going to make the site more accessible then I presume there'd be more
> involved than refraining from setting a font.

Yes and no. Font is part of it, and changing it means an increase in
accessibility. And any increase is welcome!

>>> 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.
>
> There are a lot of monospace fonts out there and typically the actual
> character size is not well-matched to the body text font even when
> they're set to a uniform size. I experimented with a bunch of system
> fonts and the default, and it was very difficult to get a good match
> without reducing the size of the monospace font. It felt that it
> mattered for readability in a dense document like this where there is
> a lot of monospace inline with body text.

Fair point. It’s a value difference again here, ahah. My argument is:
browsers and users tend to set fonts to uniformly-sized ones, so there’s
no need to rigorously match them manually. Except for the 95% problem,
at least. So yeah, I feel like this readability problem is
self-inflicted—if you rely on browser / user fonts, this problem kinda
disappears.

>> 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.
>
> I am happy to roll back the fonts but a number of the CSS changes
> aren't really about the font at all. SRFI 275 gives gives a number of
> test cases and I partly selected the fonts in order to make that portion
> of the document more readable without excessive bold text.

Hmmmm. I mean, does a slight variation in font size hurt readability
that much? I don’t see much problem in that. Disabling the 275-specific
fonts and falling back to default SRFI stylesheet makes reading as easy
as your example, in particular. Disabling _all_ fonts did work well too,
at least on my machine.

> There are a number of SRFIs which do not follow the current template,
> for various reasons, and at least one which overrides the default
> font, so it wasn't clear what the consensus is. I would appreciate
> some clarification on this.

Existing SRFIs might be a precedent, but a weak one—they might have been
wron… uninformed too.

I don’t know of a consensus here, but Arthur might chime in, as the
maintainer of the template.

> I also want to emphasise that the font selection was not arbitrary
> and was made with the structure of the proposal in mind. I selected
> fonts which are widespread in the Scheme community already (namely
> the same body text as the Racket documentation site).

This is a good argument, but I find readthedocs-style sites quite
different from (essentially) standards. If you want a nice interactive
reference, better rely on https://index.scheme.org which focuses on
richer UI and interaction. It’s all built from
https://github.com/schemeorg-community/scheme-index which you can contribute
too. While leaving the SRFI text simple enough to be read by anyone with
ease.

Thanks,
--
Artyom Bologov
https://aartaka.me