Automatically generate bibliography entries

[domenic]

Right now HTML hand-curates its bibliography entries by adding HTML directly in the following format towards the end of the document.

  <dl id="ref-list">
   <dt id="refsABNF">[ABNF]</dt>
   <dd><cite><a href="https://www.rfc-editor.org/rfc/rfc5234">Augmented BNF for Syntax Specifications: ABNF</a></cite>, D. Crocker, P. Overell. IETF.</dd>

   <dt id="refsABOUT">[ABOUT]</dt>
   <dd><cite><a href="https://www.rfc-editor.org/rfc/rfc6694">The 'about' URI scheme</a></cite>, S. Moonesamy. IETF.</dd>

   <dt id="refsAPNG">[APNG]</dt>
   <dd>(Non-normative) <cite><a href="https://wiki.mozilla.org/APNG_Specification">APNG Specification</a></cite>. S. Parmenter, V. Vukicevic, A. Smith. Mozilla.</dd>

This is annoying to maintain and the results are inconsistent with the rest of the spec ecosystem.

A north-star goal would be to move toward the same system as Bikeshed. We scan the document for [[FOO]] or [[!FOO]], and this combines to generate a full bibliography, based on https://www.specref.org/ data.

This would be a bit hard for a few reasons:

• String-scanning is not something we have precedent for in html-build or Wattsi
• Probably some of the bibliography entries in HTML are not in specref, so we'd need to support something like Bikeshed's custom bibliography entries.
• In general the algorithm to assemble the bibliography from a list of references is kind of complicated.

Here's my proposal for an incremental approach which significantly eases the maintenance burden:

• We continue to use <ref>, and continue to maintain the list of bibliography entries ourselves inside the <dl class="ref-list">
• We simplify the <dl id="ref-list"> in the source so that for auto-generated entries, we only write something like <dt>[ABNF]</dt> or <dt nonnormative>[APNG]</dt>. No <dd>, and no id="".
  • If we want a manually-curated entry, we can include both the <dt> and the <dd>.
  • The processor will look for a <dd> to know if it should try to auto-generate the entry.
• For entries we want to auto-generate, we implement the following logic:
  • Get them all into a list, and make a single call to the specref API.
  • Follow alias chains (e.g. https://api.specref.org/bibrefs?refs=ABNF) as necessary.
  • Generate the <dd> and insert it.
    • Optional enhancement: while doing so, generate the output in the same format as Bikeshed, instead of our current format.
• For all <dt>s, update them to add the appropriate id="".
• For all <dt>s, convert any nonnormative="" attributes into appropriate (Non-normative) prefixes in the corresponding <dd>.
• Optional enhancement: either check that the <dl id="ref-list"> is sorted, or sort it for us.
• Probably-not-optional enhancement: allow a fast no-internet mode where auto-generated entries just get empty <dd>s or something like <dd>(bibliography entry creation disabled in html-build)</dd>.

The result would require us to maintain a <dl id="ref-list"> which looks more like this:

  <dl id="ref-list">
   <dt>[ABNF]</dt>

   <dt>[RFC6694]</dt>

   <dt nonnormative>[APNG]</dt>

   <dt>[BEZIER]</dt>
   <dd><cite>Courbes &agrave; poles</cite>, P. de Casteljau. INPI, 1959.</dd>

This could all be done as part of the Rust pre-processor steps, so that Wattsi sees the same document that it's currently seeing.