User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:24.0) Gecko/20100101
            Thunderbird/24.3.0
MIME-Version: 1.0
References: <53248902.4050200@morningstar2.co.uk>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Message-ID:  <532490E1.4060901@latex-project.org>
Date:         Sat, 15 Mar 2014 18:41:53 +0100
Reply-To: Mailing list for the LaTeX3 project
              <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
Sender: Mailing list for the LaTeX3 project <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
From: Frank Mittelbach <frank.mittelbach@LATEX-PROJECT.ORG>
Subject: Re: Documenting 'locally added' expl3 variants
To: LATEX-L@LISTSERV.UNI-HEIDELBERG.DE
In-Reply-To:  <53248902.4050200@morningstar2.co.uk>
Precedence: list
Envelope-To: <rainer.schoepf@GMX.NET>
Status: R

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