Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Automatically generate bibliography entries #293

Open
domenic opened this issue Apr 8, 2024 · 0 comments
Open

Automatically generate bibliography entries #293

domenic opened this issue Apr 8, 2024 · 0 comments

Comments

@domenic
Copy link
Member

domenic commented Apr 8, 2024

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

No branches or pull requests

1 participant