On 15/03/2014 17:41, Frank Mittelbach wrote: >> How do other people see this? > > we are talking about variants of kernel functions correct? Yes and no. While my question applies to functions defined by the kernel, the same could apply to using a function provided by any package author writing expl3 code. For example, in my siunitx v3 code I'm hoping to provide \siunitx_units_format:nN { <input> } <token list> which might be taken up by another code author requiring \siunitx_units_format:VN So they would then have the question 'Do I document that I've created this publicly-usable function?' as well. Clearly, the two questions may have different answers as the generality of the kernel code doesn't necessarily apply to individual package authors. > 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 > ****** I've no problem with this position :-) > 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). OK, so no documentation for using \cs_generate_variant:Nn alone: seems perfectly reasonable. -- Joseph Wright