Am 15.03.2014 18:08, schrieb Joseph Wright: > Hello all, > > I'm currently making a start on v3 of siunitx, and am trying to tighten > up the 'expl3 purity' of the code. One area I'm keen to sort out is a > proper set of documented commands at the code level so people can > exploit parts of siunitx without being tied to the interface layer I > provide. > > Working systematically, I notice that I use a few variants of core expl3 > commands that have to be created. Based on the 'document everything > public' principle, these should be mentioned (they have 'public' > function names). On the other hand, they are 'nothing to do with me' as > all I'm doing is something like > > \cs_generate_variant:Nn \some_team_function:n { V } > > (OK, as I'm on the team they are actually something to do with me, but > hopefully my point is clear!) > > How do other people see this? we are talking about variants of kernel functions correct? My view on this is a follows: ****** Ideally all kernel functions should be automatically available in all variants for all packages to use. ****** We have long time ago decided that this is not a realistic goal (even though in theory it could be achieved). therefore we settled on a slightly modified approach: ****** The kernel provides base functions (ie those with N n) plus a smaller set of variants that are a) generally useful b) and (fairly) consistent in what is provided and what not (so that a programmer can normally guess if a certain variant is already predefined) For all other (undefined) variants a package is supposed to provide the necessary variant using \cs_generate_variant:Nn ****** The \cs_generate_variant:Nn generator is is more or less a no-op if the variant already exists and so it costs nearly nothing if several packages generate the same kernel variant because they need it. In other words, the fact that "siunitx" defines a few kernel variants because it needs them doesn't mean that it "provides" these variants and no other package just because siunitx is loaded should assume that those variants are predeclared. So in that sense they do not make a public appearance in siunitx and should not documented as being provided. Only the kernel itself is providing variants that all packages can and should rely on. If certain variants are being needed (and therefore generated) in many packages we may over time add them to the kernel so that they become available by default and future packages have no need to define them (but if they keep the \cs_generate_variant:Nn lines it wouldn't hurt either). cheers frank