Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

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?

share|improve this question
2  
Possible duplicate of "Do all starred commands have anything in common?" (tex.stackexchange.com/questions/30456/…) 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
add comment

2 Answers

up vote 19 down vote accepted

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* mens that \newcommand* is preferable against \newcommand when defining macros, because its 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 (non-starred)%
   }{%
      Argument: #2 (starred)%
   }%
}


\begin{document}
\foo{Test}

\foo*{Test}
\end{document}
share|improve this answer
    
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. –  Marc van Dongen 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
add comment

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).

share|improve this answer
5  
\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
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.