MIME-Version: 1.0
References: <505141C9.60900@gmail.com> <50518513.30208@latex-project.org>
            <50518B69.7050005@morningstar2.co.uk>
Content-Type: text/plain; charset=ISO-8859-1
Message-ID:  <CANQYN6wq_cSHm3cV3u_SPmGSoHRxRKw2oW_i8f_zV5UozG2GmA@mail.gmail.com>
Date:         Thu, 13 Sep 2012 14:04:16 +0200
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: Bruno Le Floch <blflatex@GMAIL.COM>
Subject: Re: New auxiliary functions guidelines
To: LATEX-L@listserv.uni-heidelberg.de
In-Reply-To:  <50518B69.7050005@morningstar2.co.uk>
Precedence: list
Status: R

On 9/13/12, Joseph Wright <joseph.wright@morningstar2.co.uk> wrote:
> On 13/09/2012 08:02, Frank Mittelbach wrote:
>> Am 13.09.2012 04:15, schrieb Joel C. Salomon:
>>> The use of `\@@_function:nn` implies that the initial function is itself
>>> an internal one.  Sometime that will be the case, of course, but I think
>>> `\pkg_function:nn` would  make a better primary.
>>>
>>> (Thinking aloud:  Unless the intention is that `\pkg_function:nn` is the
>>> primary and `\@@_function:nn` ==> `\__pkg_function:nn` is the first
>>> auxiliary? but then you'd have said that.)
>>
>> I think you are right and the intention is not yet properly described.
>> My nomenclature would be something like this:
>>
>> \pkg_function:...
>>
>> is an interface function of the package to the outside world, eg what
>> other packages should use and should be able to rely on.
>>
>> \__pkg_function:... aka \@@_function:... for short
>>
>> is an "internal" package function that is used within the package but
>> shouldn't be used outside and its implementation and semantics are not
>> to be relied on by anybody
>>
>> Now sometimes one has a need for helper functions that are only be used
>> once to implement an internal function, typically when doing some
>> complicated token parsing. Those functions are the one we call
>> "auxiliary" functions and if they are needed they get the string "_aux"
>> in the name.
>>
>> So
>>
>> \@@_function:...       is the internal one
>> \@@_function_aux:...   is used to implement just the \@@_function:...
>>
>> if more than one "auxiliary is needed for implementing a single function
>> then either they are distinguished by the arg signature or by "_auxi"
>> "_auxii" etc.
>>
>>
>> point is that the "_aux" are intended to help just with a *single*
>> command implementation. If it turns out that one reuses an "_aux"
>> function several times, it would be better to give it a separate
>> descriptive name and make it an internal function and not an auxiliary.
>
> Do you want to revise this or shall I?
>
>> perhaps I should also mention that (though not that likely) you may also
>> have the situation that an interface function needs an auxiliary, eg
>>
>> \pkg_function:...
>> \@@_function_aux:...
>
>
> Unlikely, as this should be covered by
>
>   \pkg_function:...
>   \__pkg_function_aux:...

Joseph, you are saying the same as Frank.  Do you mean
\__pkg_function:...?  This is what we had done so far, avoiding _aux
unless it was really necessary.  I guess that including aux for all
auxiliaries used in a single function is best (so we'd need to change
the names of a bunch of auxiliaries in l3kernel).

Bruno