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>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Message-ID:  <50518513.30208@latex-project.org>
Date:         Thu, 13 Sep 2012 09:02:43 +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: Frank Mittelbach <frank.mittelbach@LATEX-PROJECT.ORG>
Subject: Re: New auxiliary functions guidelines
To: LATEX-L@listserv.uni-heidelberg.de
In-Reply-To:  <505141C9.60900@gmail.com>
Precedence: list
Status: R

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.


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

frank