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