54

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?

Community
  • 1
StrongBad
  • 20,495
  • 2
    Possible duplicate of "Do all starred commands have anything in common?" (http://tex.stackexchange.com/questions/30456/do-all-starred-commands-have-anything-in-common) and the associated answers? – Mico Feb 22 '12 at 12:51
  • 1
    @mico thanks, I wasn't aware of that question. I am not sure it is a duplicate, but it is definitely close. I read that question as asking about why/when to use a * and my question is about given you have decided to use a * ... – StrongBad Feb 22 '12 at 13:05

2 Answers2

32

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}
Ben
  • 197
Tobi
  • 56,353
  • I agree with this. I was in the process of drafting a similar kind of reply. The only reason why it took me so long is that I am not sure if \newcommand should be the default. I think it depends on the implementor. –  Feb 22 '12 at 12:10
  • @MarcvanDongen: I’m not sure if \newcommand or \newcommand* is prefarable. I simply rephrased the quote from usrguide.pdf – Tobi Feb 22 '12 at 13:23
15

The general rule is that \command stands for default action and \command* stands for alternative action. Determine which behaviour is what and define your command accordingly. If you cannot categorize either behaviour as alternative, then it might be better to have two different commands altogether.

The \newcommand case is somewhat special. It is true that the starred version is better programming practice. I think the reasoning to define \newcommand in such a way was as follows: making the starred version the default could frustrate an inexperienced user, who does not know about \long:

I defined a simple command, and it won't work for an argument such as

{a

 b}

, and I don't understand why!

Or it could have been for historical reasons as well (a particular decision made in the beginning, can't be changed afterwards).

Andrey Vihrov
  • 22,325
  • 6
    \newcommand was in LaTeX since the beginning, the * form was added in LaTeX2e and we couldn't change the default behaviour. – David Carlisle Feb 22 '12 at 13:00
  • @DavidCarlisle if \newcommand hadn't been in LaTeX since the beginning, or the need for the short version had been realized, do you think the * behavior would have been reversed? – StrongBad Feb 22 '12 at 15:06
  • 2
    @DanielE.Shub "if" questions are not really answerable:-) For document level definitions the long form is probably the correct default, as it makes the macro work the same way as its replacement text. However for internal coding where often you are passing around small fragments and working at a level where such coding judgement is needed anyway, defaulting to non-long is probably right. So this works well in 2e where document authors use \newcommand in documents but package writers (mostly) use \def in lower level code, but it was never really discussed as there was no choice at the time – David Carlisle Feb 22 '12 at 15:33