Is there a LaTeX recommended standard for commands with optional arguments?

Question

According to LaTeX standards, the optional arguments of a command come before the mandatory ones. For example:

\command[optional]{mandatory}

Is it recommended to always follow this scheme? Is there any reason to avoid commands with inverted order of arguments? For example:

\command{mandatory}[optional]

A practical example: Supposing to create a class for articles, the author should be able to specify the title (TITLE); an optional short version of the title (SHORT) for page headings, and a note to the title (NOTE), similar a footnote. One could:

define \title[SHORT]{TITLE} and \titlenote{NOTE}, or
define \title{TITLE}[NOTE] and \shorttitle{SHORT},

The first one is according to usual LaTeX commands, and the asmart and beamer classes; the second is more coherent in relating the note to the title, but seems a little cumbersome. My question is: which one of them should be preferred?

Thanks in advance for your answers!

With LaTeX3 and xparse, the optional argument(s) can be essentially wherever you want (and you may have more than one), except in particular cases where arguments are parsed “expandably”, such as when using \NewExpandableDocumentCommand and friends. — frougon, Jul 05 '18 at 08:05
@frougon Since that will hopefully be the standard some day, would you mind adding an answer? — Raphael, Jul 05 '18 at 13:05

David Carlisle · Accepted Answer · 2019-03-14T09:08:42.800

Even standard latex commands have optional arguments before or after the mandatory arguments, for example

\usepackage{zzzz}[1884/01/01]

what is true is that the simple interface to defining optional arguments provided by \newcommand only lets you define one optional argument and it has to be first.

There are disadvantages to having a mandatory argument last if there is any possibility of the following text having a [

so for example

\title{TITLE}
 [the opening remarks are in square brackets]

would take the parenthetic remark as the optional argument so would requrire

\title{TITLE}\relax
 [the opening remarks are in square brackets]

or similar constructs to hide the [ from the argument scanner.

Note that that is not an issue for the trailing optional argument of \usepackage as you can not have free text in the preamble.

frougon · Answer 2 · 2018-07-05T19:27:39.507

With LaTeX3 and xparse, the optional argument(s) can be essentially wherever you want (and user-defined macros may have more than one), except in particular cases where arguments are parsed “expandably”, such as when using \NewExpandableDocumentCommand and friends.

Here is an example where we define a \printStuff macro whose syntax is: \printStuff[global style]{arg1}[style1][color1]{arg2}[style2][color2]. This macro prints the two arguments separated by a vertical bar. It applies global style to both arguments (default: \bfseries), then style1 plus color1 to the first argument, and style2 plus color2 to the second argument.

As customary in LaTeX3, we keep the implementation and user interface separate. The main logic is implemented in the internal function \my_print_stuff:nnnnnnn, while the user-level macro \printStuff merely defines the “public interface” (including default values) and calls \my_print_stuff:nnnnnnn with the appropriate parameters. Of course, it is technically possible to do everything inside the public macro \printStuff defined with \NewDocumentCommand, but this way, one loses the benefits of separation between interface and implementation.

\documentclass[a4paper,12pt]{article}
\usepackage{lmodern}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{expl3}
\usepackage{xparse}
\usepackage[svgnames]{xcolor}

\ExplSyntaxOn

% Implementation (internal)
\cs_new:Nn \my_print_stuff:nnnnnnn
  {
    \noindent
    {
      #1 #3                          % apply global and local “style”
      #4                             % optional color switch
      #2                             % first thing to print
    }
    \nobreakspace | \nobreakspace
    {
      #1 #6                          % apply global and local “style”
      #7                             % optional color switch
      #5                             % second thing to print
    }
    \par \bigskip
  }

% Public interface (user-accessible)
\NewDocumentCommand \printStuff { O{\bfseries} m O{} o m O{} o }
  {
    \my_print_stuff:nnnnnnn
      {#1}
      {#2} {#3}
      {
        \IfValueT {#4} { \color {#4} }
      }
      {#5} {#6}
      {
        \IfValueT {#7} { \color {#7} }
      }
  }

\ExplSyntaxOff

\begin{document}
\printStuff{first arg}{second arg}%
\printStuff[\itshape]{first arg}{second arg}%
\printStuff[\mdseries]{first arg}[\slshape]%
                      {second arg}[\scshape]%
\printStuff[\mdseries]{first arg}[\slshape][DarkRed]%
                      {second arg}[\scshape][DarkBlue]%
\end{document}

+1 although one might note that using key-value paramters (i.e. l3keys) may be beneficial and superior to using a bunch of optional arguments. — TeXnician, Jul 05 '18 at 19:03
@TeXnician I'd say it depends. In the example I gave, apart from the first one, the optional arguments are closely related to the preceding mandatory argument, therefore their positional nature makes sense in my opinion (as opposed to one argument using a key-value syntax). Of course, it's possible to have several arguments, mandatory or optional, using key-value syntax. :) — frougon, Jul 05 '18 at 19:23
@TeXnician That said, I agree that a syntax such as \printStuff[global style]{arg1}[font=...,color=...]{arg2}[font=...,color=...] would be a good synthesis of both approaches. — frougon, Jul 05 '18 at 20:25
Do you know pgfplots(table)? I think it would be very user-unfriendly using your approach, but that's personal preference, so I won't argue :) — TeXnician, Jul 06 '18 at 14:09

Mico · Answer 3 · 2018-07-05T12:39:00.630

With the fontspec and/or unicode-math packages (which, in turn, require the use of either LuaLaTeX or XeLaTeX), it's permissible to place the optional argument either before or after the mandatory argument in instructions such as \fontspec, \setmainfont, \setsansfont, \setmonofont, \setmathfont, \newfontfamily, \newfontface etc.

Otherwise, the general LaTeX standard is that if a macro is defined via \newcommand, any optional argument must come before the mandatory argument(s).

score 4 · Answer 4 · answered Jul 05 '18 at 19:44

4

Many newer packages move towards a key/value type interface such as

\title[%
  short=Short title,
  note=Title note,
]{Very long title}%

or

\articlesetup{%
  title=Very long title,
  short title=Short title,
  title note=Title note
}

This avoids confusion about the order of arguments (but requires key names to be memorized).

answered Jul 05 '18 at 19:44

Martin Heller

11,391

Sorry to ask you here, but which package has “\articlesetup”? – Philipp Aug 16 '21 at 09:02
@Philipp It was just meant as an example of the concept, not an example from an existing package. – Martin Heller Aug 16 '21 at 13:26

score 0 · Answer 5 · answered Jul 05 '18 at 18:59

The sectional commands (e.g., \chapter) in the memoir class can have two optional arguments before the required one, like

\section[toc-title][head-title]{body-title}

With no optional arguments body-title is used in the ToC, page headers, and the body of the text.

When one optional argument is given then it is used for the ToC and page headers.

If two optional arguments are given then toc-title is used for the ToC and head-title for page headers.

Peruse the memoir.cls code for how this is implemented.

Is there a LaTeX recommended standard for commands with optional arguments?

5 Answers5