Am 24.08.2012 04:37, schrieb Joel C. Salomon:
>
> What's the difference between the `:x` signature and the `_x:n`
> suffix+signature?

Bruno gave a very nice and elaborate explanation. I just want to
highlight one point here as it is central to the idea of the "argument
spec/argument manipulation" syntax.

The main idea of that syntax (and I'm not sure we have explained that 
well enough) is

  - that it describes how arguments are manipulated/modified *before* 
they are passed to a "base" function.

  - they do not describe what happens inside the function with the 
values passed as arguments.

The key point here is really that the manipulation happens *before*.


Base functions those that have only :n or :N arguments. All other 
arg-specifiers manipulate arguments first and than pass the result to 
the base function.

Conceptually this means

  - there should always be a base function defined not just a variant

  - variants (ie, those with :x or :o or ...) are defined via 
\cs_generate_variant:Nn

  - or if not, they behave *exactly* as if defined this way (ie, 
sometimes for very heavily  used functions it might be better to code 
them differently for speed reasons (but we expect that to be not 
necessary often or outside the kernel)

A corollary of this is that if the kernel, say, provide \foo:nnn but not 
\foo:nxo and some package needs it, it will be safe for the package to go

\cs_generate_variant:Nn \foo:nnn {nxo}

and that will be true regardless of some other package doing the same or 
the kernel (or some other package) defining an optimized variant 
\foo:nxo at some point in the future.


Now when we ran the  last consolidation round on function names, we 
noticed that we violated this principle sometimes and in cases where we 
felt it was important to indicate to something gets e"x"panded inside as 
part of the function behavior we introduced _x as part of the function name.

frank