The LaTeX3 project distinguishes between two levels of programming:

1. **Document-level commands**. These should be defined using commands present in the LaTeX kernel nowadays, formerly documented in [xparse.pdf](http://mirrors.ctan.org/macros/latex/contrib/l3packages/xparse.pdf) and now in [usrguide3.pdf](http://mirrors.ctan.org/macros/latex-dev/base/usrguide3.pdf) (only deprecated features still require `\usepackage{xparse}`, since the [October 2020 release of LaTeX](https://www.latex-project.org/news/latex2e-news/ltnews32.pdf)).

   These commands are those that users are supposed to use directly. `\NewDocumentCommand` is an excellent tool for defining such commands (`\NewExpandableDocumentCommand` if you really *know* that what you put “inside the definition” is *expandable*).
   
   There are also facilities for defining environments: `\NewDocumentEnvironment`, `\RenewDocumentEnvironment`, etc.

2. **Code-level commands**. These commands are normally intended to be used for programming, in particular not after `\begin{document}`. The LaTeX3 project offers a very convenient framework for this, called `expl3`. There are important syntactical differences beween `expl3` and “usual” TeX or LaTeX2e coding syntax. In particular, in `expl3`:

   - function names may (and should!) contain underscores (`_`); they should end with a colon (`:`) followed by the function signature;
   
   - there is a distinction between functions and variables (common in most programming languages but not really for TeX);
   
   - naming conventions for functions and variables are very useful to indicate global vs. local assignments, variable types, etc.;
   
   - spaces are mostly ignored in order to avoid the need to write `%` everywhere when programming (there are of course ways to input spaces).
   
   These special syntax rules become active after `\ExplSyntaxOn` (this usually changes the category codes of spaces, `_`, `:` and `~`). A good introduction is [expl3.pdf](http://mirrors.ctan.org/macros/latex/contrib/l3kernel/expl3.pdf). Then have a look at the [expl3 style guide](http://mirrors.ctan.org/macros/latex/contrib/l3kernel/l3styleguide.pdf) and finally, at the reference manual [interface3.pdf](http://mirrors.ctan.org/macros/latex/contrib/l3kernel/interface3.pdf).
   
   *These documents assume most of the time that you understand TeX concepts that are explained in the TeXbook.*
   
   Entry point for the official `expl3` documentation: [l3kernel](https://ctan.org/pkg/l3kernel).

# Ways of defining macros:
---

#### **Commands with no arguments:**
---

1. **TeX:** `\def\foo{the definition of foo}`
2. **LaTeX2e:** `\newcommand*{\foo}{the definition of foo}`
3. **xparse:** `\NewDocumentCommand{\foo}{ }{the definition of foo}`
3. **expl3:**

#### **Commands with mandatory arguments:**
---

1. **TeX:**

    - `\def\foo#1{\textbf{#1}}`
    - `\def\foo#1#2{\textbf{#1}\textsl{2}}`
2. **LaTeX2e:**
    - `\newcommand*{\foo}[1]{\textbf{#1}}`
    - `\newcommand*{\foo}[2]{\textbf{#1}\textsl{#2}}`
3. **xparse:**
    - `\NewDocumentCommand{\foo}{m}{\textbf{#1}}`
    - `\NewDocumentCommand{\foo}{m m}{\textbf{#1}\textsl{#2}}`
4. **expl3:**

#### **Commands with an optional argument defaulting to the given value when not given:**
---

1. **TeX:** Not available
2. **LaTeX2e:** `\newcommand*{\foo}[1][]{\textbf{#1}}`
3. **xparse:** `\NewDocumentCommand{\foo}{O{}}{\textbf{#1}}`
4. **expl3:**

#### **Commands with an optional argument defaulting to the `-NoValue-` marker when not given:**
---

1. **TeX:** Not available
2. **LaTeX2e:** 
3. **xparse:** `\NewDocumentCommand{\foo}{o}{\textbf{#1}}`
4. **expl3:**

#### **`\NewDocumentCommand{\foo}{r{<}{>}}{\textbf{#1}}`**
---

1. **TeX:** `\def\foo<#1>{\textbf{#1}}`
2. **LaTeX2e:**
3. **expl3:**