[Tex/LaTex] Meaning of an asterisk (*) in a macro name

macrosstarred-version

What does the * in the starred version of a macro "mean"? I know for \section and \section* the * controls numbering and for \newcommand and \newcommand* the * determines if the macro is long. What I don't understand is if I create a macro with starred and unstarred versions, which should version be the starred version.

I am creating an environment that can have a numbered or unnumbered list and I would like to control the presence/absence of numbers with a *. Part of me says that unnumbered should be the starred case to be consistent with things like \section. The issue is that the unnumbered case is likely to be used more commonly and therefore maybe it should be the unstarred case. Then again, What's the difference between \newcommand and \newcommand*? suggests that the starred version should be for the typical use case.

Are there any guidelines about how to chose which version of a macro should be the starred condition?

Best Answer

As far as I know there are no such guidelines. As the author (and user) of a macro, you can decide how to use the starred version. But for a little consistency I’d use the star as mark for not numbered if the macro does something with numbering (as in your example).

Otherwise I’d prefer to use the non starred version as default (often used) and the starred version as special.

The linked answer about \newcommand* means that \newcommand* is preferable against \newcommand when defining macros, because it's likely that the arguments are not long. In my eyes it doesn’t tell anything about how to use the star in own macros.

To define a starred macro one can use the LaTeX way with \@ifstar or the xparse package, which I prefer since you need no helper macros:

\documentclass{article}

\usepackage{xparse}

\NewDocumentCommand\foo{ s m }{% s = star, m = mandatory arg
   \IfBooleanTF{#1}{%
      Argument: #2 (starred)%
   }{%
      Argument: #2 (non-starred)%
   }%
}


\begin{document}
\foo{Test}

\foo*{Test}
\end{document}