> 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.
