6

In a comment of this question,David Carlisle wrote:

[l3keys2e] should be considerd legacy now, the new built in option code is based on the same core expl3 code but extended and improved so hopefully all packages using l3keys2e will switch

I learnt the l3keys2e approach last year from a few questions on this site. Now that there is a new approach, is there some guides or examples demonstrating how to make the transition from the legacy l3keys2e approach to the new expl3 approach?

Jinwen
  • 8,518
  • there is some documentation in source2e. Basically you only have to use the new processing command, and you should classify the usage of your keys into load, preamble and general keys: load keys should only be executed the first time the package is loaded. – Ulrike Fischer Jun 22 '22 at 09:59
  • I've also heard the recommendation not to use load-time package options at all (https://chat.stackexchange.com/transcript/message/60360822#60360822). Presumably, to use l3keys and a dedicated command instead. Never seen this "officially", or even if the comment was meant to be somewhat "tongue-in-cheek". Still something to think about, it makes sense. (I'd love to see an update on clsguide with this kind of thing, it would have spared me some tough learning. ;-) – gusbrs Jun 22 '22 at 10:08
  • @UlrikeFischer In the source2e doc, it seems to suggest that keys be defined with \DeclareKeys[mypkg], and then use the \ProcessKeyOptions you mentioned. Is it the same to use \keys_define:nn { mypkg } and then \ProcessKeyOptions or \ProcessKeyOptions [ mypkg ]? – Jinwen Jun 22 '22 at 10:09
  • yes, you can declare keys with both. Underlying it is the same. – Ulrike Fischer Jun 22 '22 at 10:13
  • 1
    @gusbrs indeed this would still be the better interface. The new mechanism avoids/fixes many problems of the options-related code, but it is still not perfect (and due to backwards compatibility most likely never will be), since your options have to survive full expansion (even though they are parsed without being expanded). – Skillmon Jun 22 '22 at 15:37
  • 1
    @Skillmon Thanks for your comment. And indeed, I can understand that the restrained aspect of the point in that chat discussion was mostly due, well, to "tradition". Either way, it is a good argument. I was personally convinced, to the point I've adopted it in my packages since then (they are new enough for me to dare the breaking change). ;-) Still, it would have been easier and less "bumpy" if such a good recommendation were to be found in a more official document, such as the clsguide. – gusbrs Jun 22 '22 at 16:49

1 Answers1

5

In the update 2022-06-22 of l3keys2e (as a part of l3packages), the following instruction is placed at the beginning of the documentation:

enter image description here

This answer of David Carlisle provides an example of using \ProcessKeyOptions. And the newly updated siunitx gives a perfect example for package/class authors looking for the way to switch to the new approach:

\IfFormatAtLeastTF { 2022-06-01 }
  { \ProcessKeyOptions [ siunitx ] }
  {
    \RequirePackage { l3keys2e }
    \ProcessKeysOptions { siunitx }
  }
Jinwen
  • 8,518