User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9; rv:24.0)
            Gecko/20100101 Thunderbird/24.3.0
MIME-Version: 1.0
References: <53248902.4050200@morningstar2.co.uk>
            <532490E1.4060901@latex-project.org>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Message-ID:  <53249353.4050609@morningstar2.co.uk>
Date:         Sat, 15 Mar 2014 17:52:19 +0000
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: Joseph Wright <joseph.wright@MORNINGSTAR2.CO.UK>
Subject: Re: Documenting 'locally added' expl3 variants
To: LATEX-L@LISTSERV.UNI-HEIDELBERG.DE
In-Reply-To:  <532490E1.4060901@latex-project.org>
Precedence: list
Envelope-To: <rainer.schoepf@GMX.NET>
Status: R

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