Clone the repo:

 git clone https://codeberg.org/aartaka/r7rs-html5

and build the index.html file (requires ed(1), the standard text editor—and nothing else:)

 make clean index.html

The resulting file (yes, it’s all of the standard in a single file) is ready for styling and hosting,

The source file (/aartaka/r7rs-html5/src/branch/main/source.html) has some custom tags for references and easier writing. Build script (/aartaka/r7rs-html5/src/branch/main/htmlize.ed) processes these into valid HTML5 tags. If you want to customize the conversion (add classes, change the format of the resulting tags,) then edit the script file and re-generate

Special tags:

<xref>symbol</xref>

to reference standard procedures/syntax.

<secref X.X.X>

to reference sections of the document

<libref name>

to reference one of the standard libraries

<bibref>integer</bibref>

to reference one of the bibliography references

<syntax [library]>(name ...)</syntax>, procedure, auxiliary-syntax, lexical-syntax (same format as <syntax>)

tags for semantic definitions of entities, possibly with library names

<h2 id>

Also note the special syntax <h2 ID>, <h3 ID> etc. for headers, because it allows generating sensible section IDs and self-references.

<sem-d>

Domain in formal semantics.

<sem-fn>

Function in formal semantics.

<sem-const>

Constant in formal semantics.

<sem-stx>

A syntax fragment or a set of syntax in formal semantics.

<sem-str>

A string rendered in a formal semantics function.

Classes to style:

note

class for side notes, like Note or Rationale sections

example

for possibly runnable small code blocks exemplifying some procedure or feature

• Other code blocks are plain <pre>-s, so style accordingly

  • Example blocks are <pre> too, just in case

author

for author display customization in the report preamble

authors

container for author groups

xref, secref, bibref, libref

for results of tags above, <a> links by default

syntax, procedure, auxiliary-syntax, lexical-syntax

results of generation from <syntax> and the kind, <h5> by default

semantics-notation-table

A class for the <table> that contains the definitions of the special notation for the formal semantics.

semantics-notation

The LHS of the above table, which has the notation (as opposed to the description).

semantics-function

Style for semantics function (new, cwcc, etc.) In the report it is in italic serif.

semantics-domain

Style for domain sets. In the report it is upright typewriter.

semantics-constant

Style for semantics constants (false, true). In the report it is italic serif.

semantics-block

Self-standing block of semantics. The default font in this is upright monospace.

semantics-syntax

Style for objects in the semantics that correspond to Scheme syntax. In the report this is upright serif.

semantics-definition

Definition of formal semantics function. The default font is upright serif.

semantics-string

String in the formal semantics. The font in the report is upright serif.

Many of these changes are encoded in the /aartaka/r7rs-html5/src/branch/main/htmlize.ed script, but some were hand-edited into the document. The version hosted on standards.scheme.org was taken as a departure point and improved over.

• Of course, many non-semantic tags were replaced with semantic (or at least less evil) counterparts from HTML5:

  • <i> to <em> (<dfn> might be preferable for some cases, but it’s not added yet)
  • <span style="font-family:monospace"> (what? yes, that’s what it used!) to <code>
  • Arbitrary <br>-s to semantic structures like <table>, <pre>, and <dl>.
  • Tables are wrapped into <div> -s for easier overflow styling.
• Section links were expanded to include "section" and "chapter" for easier clicking/tapping. I.e., "see section [XXX]" became "see [section XXX]".
• Evaluation results (these ⟹ expressions) are comments now, for ease of parsing and highlighting

• Standard libraries and symbols were heavily hyperlinked to point to the most sensible document section describing them. Including links in <pre> blocks that some might deem un-aesthetic. The usefulness of these in allowing a quick lookup greatly exceeds their "ugliness."

  • If you wish to, you can remove them by adding this (untested) line to htmlize.ed and rebuild:

    g;<pre>;.,/<\/pre>/s;</*xref>;;g

• Most procedure arguments have associated type information in their tooltips now. I allowed myself a liberty of expanding these type descriptions, as in

  port => port, an input and output device (see section 6.13.1)

• HTML document is heavy with newlines, for readability.

  • Some source code blocks had newlines inserted for consistency and ease of read on mobile.

Contributions are welcome, because I couldn’t possibly iron out all the translation mistakes myself. And I might not know about some features of HTML (and MathML in particular) I’m missing. So please fix things and open a pull request with them! Nice to have for contributions:

• Group edits into semantic batches and split into commits
• Format commits in "Action—rationale" style

• Some editing conventions:

  • If you see overly long lines (> 120 chars), split them at sentence or clause boundaries. This way, even the source code is readable.

  • Do not introduce styles or scripts—this is left for downstream users to customize.

    • Exceptions can be made for accessibility fixes needing JavaScript to work
• Use of historic HTML shortcuts (unclosed <p>, using closing tags to close stack of unclosed ones) is okay, but better do stricter HTML than lax