Skip to content

fix: Restyle references#10024

Open
martinthomson wants to merge 7 commits into
ietf-tools:mainfrom
martinthomson:restyle-references
Open

fix: Restyle references#10024
martinthomson wants to merge 7 commits into
ietf-tools:mainfrom
martinthomson:restyle-references

Conversation

@martinthomson

Copy link
Copy Markdown
Contributor

This is a little hacky in that it relies on xml2rfc inserting <dd class="break"></dd> after each reference, but that seems to be
something that we can rely on consistently across the series.

This is, as far as I can tell, character-for-character identical to the
placement used in xml2rfc's text generation output. I had to make a
small tweak to the layout for regular definition lists as well, but
that's fairly minor (it was missing an indent).

See martinthomson/rfc-txt-html#13 for a
discussion on the fix.

Stacked on #10016, but this could be retargeted at main if that makes more
sense.

This tries to make the HTML rendering look good, using the native
bootstrap styling as much as I can be bothered to do for now.
This is a little hacky in that it relies on xml2rfc inserting `<dd
class="break"></dd>` after each reference, but that seems to be
something that we can rely on consistently across the series.

This is, as far as I can tell, character-for-character identical to the
placement used in xml2rfc's text generation output.  I had to make a
small tweak to the layout for regular definition lists as well, but
that's fairly minor (it was missing an indent).

See martinthomson/rfc-txt-html#13 for a
discussion on the fix.

Based on ietf-tools#10016, but this could be retargeted at main if that makes more
sense.
@martinthomson

martinthomson commented Nov 28, 2025

Copy link
Copy Markdown
Contributor Author

Screenshot of RFC 9000, showing how the labels are placed:
image

The same in text form:

23.1.  Normative References

   [BCP38]    Ferguson, P. and D. Senie, "Network Ingress Filtering:
              Defeating Denial of Service Attacks which employ IP Source
              Address Spoofing", BCP 38, RFC 2827, May 2000.

              <https://www.rfc-editor.org/info/bcp38>

   [DPLPMTUD] Fairhurst, G., Jones, T., Tüxen, M., Rüngeler, I., and T.
              Völker, "Packetization Layer Path MTU Discovery for
              Datagram Transports", RFC 8899, DOI 10.17487/RFC8899,
              September 2020, <https://www.rfc-editor.org/info/rfc8899>.

   [EARLY-ASSIGN]
              Cotton, M., "Early IANA Allocation of Standards Track Code
              Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January
              2014, <https://www.rfc-editor.org/info/rfc7120>.

   [IPv4]     Postel, J., "Internet Protocol", STD 5, RFC 791,
              DOI 10.17487/RFC0791, September 1981,
              <https://www.rfc-editor.org/info/rfc791>.

   [QUIC-INVARIANTS]
              Thomson, M., "Version-Independent Properties of QUIC",
              RFC 8999, DOI 10.17487/RFC8999, May 2021,
              <https://www.rfc-editor.org/info/rfc8999>.

   [QUIC-RECOVERY]
              Iyengar, J., Ed. and I. Swett, Ed., "QUIC Loss Detection
              and Congestion Control", RFC 9002, DOI 10.17487/RFC9002,
              May 2021, <https://www.rfc-editor.org/info/rfc9002>.

   [QUIC-TLS] Thomson, M., Ed. and S. Turner, Ed., "Using TLS to Secure
              QUIC", RFC 9001, DOI 10.17487/RFC9001, May 2021,
              <https://www.rfc-editor.org/info/rfc9001>.

   [RFC1191]  Mogul, J. and S. Deering, "Path MTU discovery", RFC 1191,
              DOI 10.17487/RFC1191, November 1990,

You can see a few differences:

  • Browsers are more willing to wrap URLs than xml2rfc. That's hard to fix, because xml2rfc will wrap a longer URL and there is no good length-based wrapping controls in CSS.
  • The DPLPMTUD reference wraps differently, but that looks to be a quirk of how browsers choose to wrap. They wrap rather than fill to precisely the available space. I decided not to push that one.

@codecov

codecov Bot commented Nov 28, 2025

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 0% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.54%. Comparing base (ff75680) to head (171aa69).
⚠️ Report is 51 commits behind head on main.

Files with missing lines Patch % Lines
ietf/doc/views_doc.py 0.00% 4 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main   #10024      +/-   ##
==========================================
- Coverage   88.55%   88.54%   -0.02%     
==========================================
  Files         317      317              
  Lines       42343    42387      +44     
==========================================
+ Hits        37496    37530      +34     
- Misses       4847     4857      +10     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@jennifer-richards jennifer-richards left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks ok to me. I don't have a strong sense about whether relying on the <dd> from xml2rfc is a winning strategy for the long term, but as the existing styling options are preserved it seems mostly harmless.

That does hint at questions about proliferation of style options to support going forward but the count is still reasonable imo.

@martinthomson

Copy link
Copy Markdown
Contributor Author

The <dd class="break"> thing is (hopefully) temporary. Though no browser implements it, wrap-before: flex is the agreed solution to this. It's only been 10 years without any browser implementing it.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants