Order of autogenerated references

Question

Order of autogenerated references

dkg opened this issue 10 months ago · 6 comments

Currently, auto-generated references (those derived from inline data in the text, like RFCs or DOI identifiers) appear in the References section in the order in which they first appear in the document.

I've received requests to order references alphabetically for multiple documents lately (also for draft-ietf-dprive-unilateral-probing). Is there a way to ask kramdown-rfc to order the references in numerical order rather than document order, or do i need to make a manual listing in the references section?

Answer 1 · 2024-02-22T17:55:42.000Z

xml2rfc does that for you, as per "sortrefs".
RFCXML has an indefensible default for this: no.
Set it to yes in pi:, or let

v: 3

do this and a few other useful things for you.

Answer 2 · 2024-02-22T18:36:26.000Z

huh, interesting. i was passing --v3 to kramdown-rfc on the command line, and i didn't know that v: 3 in the metadata block would do this additional behavior. Should kramdown-rfc --v3 also explicitly set this to "yes"?

Answer 3 · 2024-02-22T18:57:10.000Z

Maybe calling it "v: 3" was confusing, as this ist mostly a package of settings that you want to do for v3 but that cannot be default for backwards compatibility reasons. (--v3 has been default since 2022-02-22T22:02:22.)

Answer 4 · 2024-02-22T19:07:48.000Z

🤷 ok by me! I can just include v: 3 as boilerplate in all my kramdown going forward, i guess, though it seems to violate the DRY principles that i generally am pleased with kramdown-rfc for following.

Regardless of indefensible choices by xml2rfc, it seems to me like kramdown-rfc could change its defaults to include sortrefs: yes directly unless the document author has explicitly included a sortrefs: no in their metadata block.

(ps why didn't you wait 20 minutes to change the default‽ so sad to miss the sexagesimal/decimal convergence by such a close shave… 😛)

Answer 5 · 2024-02-22T19:19:04.000Z

Well, DRY is fine, but supporting dusty decks is fine, too (and v: 3 is a declaration that you aren't a dusty deck).

v: 3 mostly does three things right now:

  ps.default!(:stand_alone, true)
  ps.default!(:ipr, "trust200902")
  ps.default!(:pi,  {"toc" => true, "sortrefs" => true, "symrefs" => true})

So you can get rid of all three pieces of boilerplate in exchange for putting in one, easy to remember one.

Answer 6 · 2024-02-22T20:05:13.000Z

good call. I've done that now, which reduced my boilerplate. thanks :)