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.
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 à 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.
Right now HTML hand-curates its bibliography entries by adding HTML directly in the following format towards the end of the document.
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:
Here's my proposal for an incremental approach which significantly eases the maintenance burden:
<ref>, and continue to maintain the list of bibliography entries ourselves inside the<dl class="ref-list"><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 noid="".<dt>and the<dd>.<dd>to know if it should try to auto-generate the entry.<dd>and insert it.<dt>s, update them to add the appropriateid="".<dt>s, convert anynonnormative=""attributes into appropriate(Non-normative)prefixes in the corresponding<dd>.<dl id="ref-list">is sorted, or sort it for us.<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: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.