Format of S-expression metadata for SRFI documents Lassi Kortela (11 Mar 2019 14:59 UTC)
Re: Format of S-expression metadata for SRFI documents Ciprian Dorin Craciun (11 Mar 2019 15:05 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (11 Mar 2019 16:05 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (11 Mar 2019 16:02 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (11 Mar 2019 16:02 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (11 Mar 2019 16:12 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (11 Mar 2019 17:30 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (11 Mar 2019 17:34 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (11 Mar 2019 17:49 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (11 Mar 2019 20:35 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (12 Mar 2019 09:43 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (11 Mar 2019 18:09 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (11 Mar 2019 20:37 UTC)
Re: Format of S-expression metadata for SRFI documents John Cowan (11 Mar 2019 22:20 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (12 Mar 2019 07:08 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (12 Mar 2019 07:45 UTC)
(missing)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (12 Mar 2019 15:12 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (12 Mar 2019 13:22 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (12 Mar 2019 17:02 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (12 Mar 2019 17:15 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (12 Mar 2019 17:35 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (12 Mar 2019 17:51 UTC)
Re: Format of S-expression metadata for SRFI documents Ciprian Dorin Craciun (13 Mar 2019 15:28 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (13 Mar 2019 17:01 UTC)
Re: Format of S-expression metadata for SRFI documents Ciprian Dorin Craciun (13 Mar 2019 15:41 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (13 Mar 2019 16:54 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (13 Mar 2019 17:17 UTC)
Re: Format of S-expression metadata for SRFI documents Ciprian Dorin Craciun (13 Mar 2019 19:00 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (14 Mar 2019 13:28 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (14 Mar 2019 17:33 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (23 Mar 2019 10:35 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (23 Mar 2019 16:37 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (24 Mar 2019 09:15 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (24 Mar 2019 09:26 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (24 Mar 2019 09:27 UTC)
Re: Format of S-expression metadata for SRFI documents Ciprian Dorin Craciun (13 Mar 2019 21:57 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (14 Mar 2019 10:49 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (13 Mar 2019 17:46 UTC)
Re: Format of S-expression metadata for SRFI documents Ciprian Dorin Craciun (13 Mar 2019 18:53 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (14 Mar 2019 11:03 UTC)
Re: Format of S-expression metadata for SRFI documents Ciprian Dorin Craciun (14 Mar 2019 11:07 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (14 Mar 2019 11:12 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (14 Mar 2019 11:34 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (14 Mar 2019 17:24 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (14 Mar 2019 20:40 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (25 Mar 2019 20:25 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (25 Mar 2019 22:04 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (25 Mar 2019 22:13 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (25 Mar 2019 22:42 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (25 Mar 2019 22:50 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (25 Mar 2019 22:54 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (25 Mar 2019 23:56 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (26 Mar 2019 00:16 UTC)
Re: Format of S-expression metadata for SRFI documents John Cowan (26 Mar 2019 01:27 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (26 Mar 2019 08:54 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (26 Mar 2019 04:17 UTC)
Re: Format of S-expression metadata for SRFI documents Göran Weinholt (26 Mar 2019 21:38 UTC)
Re: Format of S-expression metadata for SRFI documents Arthur A. Gleckler (26 Mar 2019 23:36 UTC)
Re: Format of S-expression metadata for SRFI documents Lassi Kortela (27 Mar 2019 21:42 UTC)

Re: Format of S-expression metadata for SRFI documents Lassi Kortela 25 Mar 2019 22:04 UTC

> I'd like to encourage any work that gets us better metadata extraction
> but doesn't change the visible content of existing SRFI documents
> (although it's fine to change the behind-the-scenes HTML, as you have
> been doing).  In other words, I don't want to change anything that
> people have already agreed upon, i.e. the designs, the APIs, and the
> wording of the documentation.  It looks like what you've been doing fits
> the bill.

That's my impression too. No changes to the text of the SRFIs are
suggested by me or Ciprian. The lightweight HTML classes for metadata
would keep even the visual styling of the SRFIs completely intact.
Ciprian's XHTML form might change the styling a little but still keep
all the text intact.

> I was hoping that you and Ciprian would come up with a Scheme format
> that would be good for encoding all that, but since the work you're
> doing can automatically generate whatever format we finally agree upon,
> there seems to be little risk in going ahead.

That's the plan, but we'd currently like to split his advanced type
signatures into different files. So we could have 4 metadata files for
each SRFI:

* srfi-123-info.scm -- general information (automatic + manual combined)
* srfi-123-info-add.scm -- manual additions to the general information
* srfi-123-args.scm -- traditional Lisp-style argument lists (auto)
* srfi-123-types.scm -- Ciprian's advanced type signatures (manual)

The advanced types could live in the SRFI repos or in Ciprian's own
repo, I don't think we made a final decision yet.

> This sounds good.  Just to be clear, though, would you mind laying out
> exactly what work you want to do in the official SRFI repos themselves?

Sure.

* The srfi-<n>.html file would be changed so that simple metadata
classes are added, *or* would have a complete makeover to Ciprian's
XHTML structure if he can discover a good one. These changes would be
done to finalized SRFIs by the editor and/or volunteers based on the
free-form HTML submitted by the author (so the SRFI submission
guidelines would not change). If the author later amends the submitted
HTML to fix errata, they can again use whatever kind of HTML they
prefer. The editor/volunteers can then fix it again to conform to the
expected structure for metadata extraction (by the assumption that
errata for finalized SRFIs are quite rare, so this woudn't be a big
burden). Of course, nothing forbids an author from submitting HTML in
the final form right away (e.g. Alex expressed interest in writing tools
to convert Scribble to it), but we don't require it.

* The S-expression metadata files (srfi-<n>-*.scm) can be generated by
the CI server for each SRFI whose HTML has been edited into the right
form. These metadata files should probably be committed into the SRFI
origin repos as well, so that each SRFI's Git history will track
metadata changes in addition to HTML changes.

* If the auto-generated metadata (srfn-<n>-info.scm) is missing some
stuff (e.g. "see also" links to other SRFIs) then the editor can
manually write a separate (srfi-<n>-info-add.scm) file into the SRFI's
repo. The generator will then patch its automatically derived metadata
with these manual additions. The combined file (auto w/ manual
additions) is what should be committed to the SRFI repo. It's possible
to keep changing the manual file (srfi-<n>-info-add.scm) and the CI
server will generate a new combined file every time.

* We might be able to use some GitHub API so the CI server can generate
pull requests to the origin repos for all metadata changes, so humans
don't need to do that (humans would still merge the PRs, the CI server
would never commit anything to the master branch without explicit human
permission). I would consider this an optional nice-to-have. The main
thing is that the server check the metadata in the repos for consistency
with the HTML.