On 9/13/12, Joseph Wright <[log in to unmask]> 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