Is creating a unit a “user” function?

Working on siunitx version 2, I’m confronted with a slight problem. Currently, the macros used to manipulate units are called

  • \newunit
  • \renewunit
  • \provideunit

which follows the LaTeX 2ε \newcommand, etc.; the same is true for prefixes and so forth. These names were probably not the best choice: for example, biblatex also has a \newunit macro (although there is not a clash, luckily).

I’ve been thinking of better names, but I’m not sure whether these should be document level (all lower-case), or design level (mixed upper-case and lower-case). Some ideas:

  1. \DeclarePhysicalUnit (create without checks)
  2. \NewPhysicalUnit (create with checks: would require \RenewPhysicalUnit, etc.)
  3. \NewUnit (as 2 but shorter)
  4. \newphysicalunit (as 2 but document level)
  5. \createphysicalunit (is “create” better than “new”?)
  6. \createunit (avoids the confusion with biblatex)

You’ll see that I’ve not included “SI” in any of the above: it looks odd, and of course you can create non-SI units anyway. How do other people see this?

6 thoughts on “Is creating a unit a “user” function?

  1. How important do you judge it to be that users will really need the distinction between new/renew/provide ? For something this specialised, I’d be inclined to stick to only using Declare — similar to, e.g., amsmath’s DeclareMathOperator. I’d steer clear of create, just because it’s different.

    Another possible option: DeclareSIunit ?

  2. This was broadly my thinking, to be honest. I’m not so struck on DeclareSIunit because I think it doesn’t really follow the usual “rules” for desgin-type macro names (should be DeclareSIUnit, which I find hard to read).

  3. If the unit macros are undefined outside of SI or si, then name clashes are nearly impossible and one DeclareUnit macro would be sufficient. On the other hand, it would not be too difficult to provide the other combinations. My suggestion in this case is CreateUnit, OverwriteUnit, DeclareUnit and ProvideUnit. I don’t like names like newcommand—they are hard to read and don’t follow the usual verb–object pattern.

  4. The plan for v2 is that by default I’ll only define stuff inside SI and si (although there will be an option to control this). So I’m also in favour of Declare … I’m probably not going to go for DeclareUnit as I suspect it is still too general (there are other things which are “units”).

  5. Hello Stefan,

    From various things I’ve been doing (LaTeX3 work, name space questions, looking at other packages, answering questions, etc.) I’m pretty convinced that this type of “set up” macro should use design-like naming (upper- and lower-case mixed names). Hence thinking about DeclareUnit. The current working copy uses:

    – DeclareSIPrefix
    – DeclareSIPower
    – DeclareSIQualifier
    – DeclareSIUnit

    Most users will probably never need to use these macros, and I think that the names should now be both memorable and very unlikely to clash with anything.

    Joseph

Leave a Reply