User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:15.0) Gecko/20120907
            Thunderbird/15.0.1
MIME-Version: 1.0
References: <505141C9.60900@gmail.com> <50518513.30208@latex-project.org>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Message-ID:  <50518B69.7050005@morningstar2.co.uk>
Date:         Thu, 13 Sep 2012 08:29:45 +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: Joseph Wright <joseph.wright@MORNINGSTAR2.CO.UK>
Subject: Re: New auxiliary functions guidelines
To: LATEX-L@listserv.uni-heidelberg.de
In-Reply-To:  <50518513.30208@latex-project.org>
Precedence: list
Status: R

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 Wright