The issue of any "subset of HTML" we use is that there are things that
people might want to include that get excluded because they are difficult.

1. MathML (I use this. The alternative is JS.)
2. SVG (I don't know of an SRFI that uses this, but I don't see any
reason to get rid of it)
3. Images (if we're translating to terminal or LaTeX, then images pose
an issue. Should the "small" subset of HTML forbid these?)

Another issue that is not solved with "small" HTML is that the selection
of elements is small (by definition), so when we mark up things that
aren't covered by those elements we have to get presentational. In
R7RS-Large DocBook, procedure prototypes are marked up like:

     <s:synopsis>
      <s:procprototype>
       <function>car</function>
       <parameter>pair</parameter>
      </s:procprototype>
     </s:synopsis>

so we know exactly what is the function name, what is the parameter
(and, if we follow the R7RS function parameter conventions, what the
type restriction is on the arguments). With HTML you might get around it
with data-* attributes or class names, but it is much less structured
and harder to validate.

It is harder to mark up when you have more complicated prototypes:
     <s:synopsis>
      <s:procprototype>
       <function>string-copy</function>
       <parameter>string</parameter>
       <s:argopt><parameter>start</parameter>
                 <s:argopt><parameter>end</parameter></s:argopt></s:argopt>
     </s:procprototype></s:synopsis>

This is getting pretty verbose, I usually write it in SXML, where it is
less complicated:

     (s:synopsis
      (s:procprototype
       (function "string-copy")
       (parameter "string")
       (s:argopt (parameter "start")
                 (s:argopt (parameter "end")))))

Here the groups of optional arguments are grouped using the tree
structure of XML. In HTML you would have to do some messing around with
<spans> and you would likely have to insert "[" and "]" manually. You
could try text-before and text-after in CSS, but I find that to be a hack.

For something even more structured, there is productionset:

     (productionset
      (production
       (lhs "datum")
       (rhs (nonterminal "symbol"))
       (rhs "(" (rhsmany (nonterminal "datum")) ")")
       (rhs "(" (rhsplus (nonterminal "datum")) "." (nonterminal
"datum") ")")))

This is a representation of EBNF and is structured enough to be
mechanically translated into a YACC grammar. An HTML representation of
this would have a lot of superfluous ::=, ⟨, ⟩, +, and * floating around
that you'd have to remove somehow.

The R7RS DocBook toolchain compiles to XHTML1.1 so you can distribute a
compiled HTML file for web viewing, and use the DocBook version for
format translation / extracting information.

This more-or-less brings us back to custom elements, which would be fine
if we didn't have to use JS to transform them. Having a compiler (a
simple script) that translates HTML+SRFI-custom-elements to HTML5 (or
XHTML1.1 or SmallWeb whatever dialect of HTML) would be useful.

-- Peter McGoron