# Best practices on when to create a new function vs. a command in LaTeX3

Experienced TeX programmers will probably be worried that I’m talking about ‘functions’ and not about ‘macros’. ... The LaTeX3 programming approach allows us to treat many macros as if they were functions, but there are places where we’ll need to think about macros being expanded. Throughout the LaTeX3 documentation, programming is described in terms of functions, and so I’ll stick to that approach. Bear in mind that underlying everything is a set of macros, and that this will show up from time to time.

If "macros" are now being called "functions", but under the hood everything is still a macro, I'm wondering how we should think about when to create a macro with \NewDocumentCommand vs. creating a function such as with \cs_new:Npn.

• \NewDocumentCommand is, well, for “document level” macros/functions/how-you-name-it, whereas \cs_new... is for lower level functions in expl3 code. Mar 24, 2018 at 18:00
• That text you quoted doesn't say at all what you are saying. It says that everything is a function (altough we know deep down they are macros, we refer to them as functions). So \NewDocumentCommand “is” obviously a function. Mar 24, 2018 at 18:00
• I mean \NewDocumentCommand creates “functions” (not macros, although we know they are in the end macros). Mar 24, 2018 at 18:10
• As a newcomer it's confusing on when each should be used. I don't see when I should ever use \cs_new:Npnat this point, if \NewDocumentCommand just creates functions too. Would be helpful to have a description on best-practices in this regard. Mar 24, 2018 at 18:12
• \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”. Mar 24, 2018 at 18:18

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
}

• "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" I am uncertain by the meaning in this part. So when using a document command like \emph or \foo, it can have dynamic arguments like \foo{1} or \foo{1}{a=10}. So that seems to mean the doc command impl is not fixed, since there's dynamic arguments, even though it does have a clearly defined api. Mar 24, 2018 at 19:21
• Also uncertain as to this part: "I shouldn't need to worry about the optional star and optional square-bracket argument." Mar 24, 2018 at 19:22
• @LancePollard E.g. \section*[short]{long} has three arguments but only one is mandatory: parsing those is about the document level, implementing the ideas 'goes in the TOC', 'short title' and 'long title' is code-level. Mar 24, 2018 at 19:36