(missing)
(missing)
(missing)
Re: Proposal to add HTML class attributes to SRFIs to aid machine-parsing Marc Nieper-Wißkirchen (06 Mar 2019 10:12 UTC)
Re: Proposal to add HTML class attributes to SRFIs to aid machine-parsing Lassi Kortela (06 Mar 2019 18:19 UTC)

Re: Proposal to add HTML class attributes to SRFIs to aid machine-parsing Lassi Kortela 06 Mar 2019 18:18 UTC

> I think -- as you've pointed before -- that there are multiple types
> of meta-data:
>
> (A)  "global" SRFI related meta-data like author, title, identifier
>
> (B)  "indexing" items, like `<span class="def-prog">make-array</span>`;
>
> (C)  textual "descriptive" elements related to various definitions
>
> (D)  procedure or syntax definition in a way that is machine readable
>
> Therefore I assume that our disagreement is only with (D).

Correct.

I would prefer to also have (D) in the HTML because:

1) It doesn't add all that much markup when we already have all the
other markup in the file. Yes, the argument lists become messy, but they
are only a fairly small part of the SRFI.

2) Any 'class=' attributes in the markup should be designed so that they
can be ignored when rendering the document. Especially if we use
semantic HTML tags in a uniform manner as suggested by you and Arthur,
e.g. <var> for arguments. We should design things so that it renders in
a reasonable manner even without the classes.

3) Most tools that process the procedure signatures (argument names,
etc.) probably would not read the source HTML. Instead, they would read
some S-expression or JSON database that is auto-generated from the HTML.
This wouldn't be a problem, because auto-generation makes it easy to
keep those databases in sync (if the SRFIs change, just re-run the
generator). Ideally a public API would serve up-to-databases to the
world in easy-to-digest formats, and the API server could simply poll
the source HTML at intervals. So most people who use SRFI metadata would
not be exposed to the messy markup. On the other hand, if the databases
are made manually instead of auto-generated, they may easily diverge and
people who change or verify the SRFI HTML do not simultaneously change
or verify the correctness of the database.