search

cabo / kramdown-rfc

An XML2RFC (RFC799x) backend for Thomas Leitner's kramdown markdown parser
MIT License
195 stars 83 forks source link

Order of autogenerated references #225

Closed dkg closed 9 months ago

dkg commented 9 months ago

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?

cabo commented 9 months ago

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.

dkg commented 9 months ago

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"?

cabo commented 9 months ago

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.)

dkg commented 9 months ago

:shrug: 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… 😛)

cabo commented 9 months ago

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.

dkg commented 9 months ago

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