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>           
            <532490E1.4060901@latex-project.org>
            <53249353.4050609@morningstar2.co.uk>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Message-ID:  <53256A57.2060207@latex-project.org>
Date:         Sun, 16 Mar 2014 10:09:43 +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:  <53249353.4050609@morningstar2.co.uk>
Precedence: list
Envelope-To: <rainer.schoepf@GMX.NET>
Status: R

Am 15.03.2014 18:52, schrieb Joseph Wright:
> 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.

I think the answer is the same (more or less). The only difference that 
I would see is that while in the kernel we tried a fairly uniform set of 
predefined variants I would thank that a package author has more freedom 
deciding what he predefines.

Basically, if you as a package author define a certain base function as 
being a public interface, say \siunitx_units_format:nN, then it is upto 
you which variants you predefine (and also which of them you document).

However, the important point is that

  - by defining the base function as an interface you have essentially 
declared all variants as public (whether predefined or not)

  - by documenting all the predefined ones all you do is that you  save 
any user of your package the burden to add a \cs_generate_variant:Nn 
line to make them accessible

  - and as a follow up you agree on supporting as being predefined 
(i.e., that no \cs_generate_variant:Nn line is necessary for others to 
use them).

If you if you use the variants yourself and you believe that this is not 
going to change and the variants are generally useful, then I would 
probably document them. However,  documenting only a uniform set would 
be equally defensible - neither really changes the usability of the 
interface as *all* variants come implicitly into existence either way.

-------------------------------

>> 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.

not for variants defined for interfaces of other packages or interfaces 
of the kernel. This only generates dependencies that are unnecessary and 
produce extra complications (then variants are available or not 
depending on what other packages have been loaded and over time you get 
surprises when you restructure code  and take packages out).

frank
> --
> Joseph Wright
>