TeX is a macro expansion language, so everything we can create comes down to macros. However, that is not what is important here: what we are talking about is programming layers.
A LaTeX document is constructed using commands such as \emph
, \begin
, \section
and so on. These document commands may have take optional arguments where appropriate, and may have differing results depending on the document class. A classic example of the later is \emph
: it usually means 'make italic', but in a presentation might be bold, coloured or similar. At the same time, whilst LaTeX2e uses a particular 'standard' syntax, one could define alternative document formats with different conventions at this level.
The implementation of document commands needs a code level: details of the implementation. At this level, we want clearly defined APIs in which the number of arguments is fixed and which don't depend on variable syntax in the document. For example, if I decide to change how I implement \section
, I shouldn't need to worry about the optional star and optional square-bracket argument.
In LaTeX2e, there are some areas where such separation exists (\section
is one), but this is not entirely systematic. In LaTeX3 work, the situation is much more clearly defined. (LaTeX2e-like) Document commands should be created using xparse
(\NewDocumentCommand
, etc.), and pass their argument(s) to documented code-level APIs created using expl3
(\cs_new_protected:Npn
, etc.), i.e.
\NewDocumentCommand \foo { s O { } m }
{
\IfBooleanTF #1
{ \my_command_one:nn {#1} {#2} }
{ \my_command_two:nn {#1} {#2} }
}
...
\cs_new_protected:Npn \my_command_one:nn #1#2
{
% Implementation using private \__... functions
}
\NewDocumentCommand
is, well, for “document level” macros/functions/how-you-name-it, whereas\cs_new...
is for lower level functions inexpl3
code.\NewDocumentCommand
“is” obviously a function.\NewDocumentCommand
creates “functions” (not macros, although we know they are in the end macros).\cs_new:Npn
at this point, if\NewDocumentCommand
just creates functions too. Would be helpful to have a description on best-practices in this regard.\NewDocumentCommand
is to create commands that are going to be used inside a document (like\textbf
,\section
,\emph
,\int
,\frac
, etc.),\cs_new(_protected)(_nopar):Npn
are to be used for anything else that is not a “user interface”.