[texhax] Creating stared versions of macros

[Morten Høgholm]

On Thu, 30 Dec 2004 15:08:38 +0100, Stefan Björk <stefan at raggmunk.nu>  
wrote:

>> This small example should perhaps make it a little clearer:
>
> I'm beginning to understand a thing or two now, thank you. My little  
> macro here works as expected, but I still have a question:
>
> What's the difference between \newcommand and \newcommand*?

It's in usrguide (texmf/doc/latex/base) but I'll give it here as well (a  
copy of what I wrote on another list).

%%%%%%%%%%%%%%%%% copy begins
  The command in question:
  \newcommand*\vNameref[1]{`\nameref{#1}"\ \vpageref{#1}}

  > Sounds very good, thank you! Some questions remain:
  >
  > - I only knew the "\newcommand{\command}[1]{....}" syntax. What
  >   is "\newcommand*"?

  Using the starred version of \newcommand means that the arguments of the
  defined command cannot contain a blank line or \par. This makes it a lot
  easier to spot runaway arguments.

  Let's consider the input

  Some text in English. See \vNameref{sec:2. Some text in English.
  Some text in English. Some text in English. Some text in English.
  Some text in English. Some text in English. Some text in English.
  Some text in English. Some text in English. Some text in English.
  Some text in English. Some text in English. Some text in English.
  Some text in English. Some text in English. Some text in English.
  Some text in English. Some text in English. Some text in English.

  With the non-starred version of \newcommand we get an error like this:
  %%%%%%%%%
  Runaway argument?
  {sec:2. Some text in English. Some text in English. Some text in Engl\ETC.
  ! File ended while scanning use of \vNameref.
  <inserted text>
                   \par
  <*> varioref.tex

  ? H
  I suspect you have forgotten a `}", causing me
  to read past where you wanted me to stop.
  I"ll try to recover; but if the error is serious,
  you"d better type `E" or `X" now and fix your file.
  %%%%%%%%%%

  With the starred version we instead get this (useful) message:
  %%%%%%%%%
  Runaway argument?
  {sec:2. Some text in English. Some text in English. Some text in Engl\ETC.
  ! Paragraph ended before \vNameref was complete.
  <to be read again>
                      \par
  l.25

  ? H
  I suspect you"ve forgotten a `}", causing me to apply this
  control sequence to too much text. How can we recover?
  My plan is to forget the whole thing and hope for the best.
  %%%%%%%%%%

  So we can actually pinpoint the place where it goes wrong. The drawback is
  of course that you can't have arguments that span multiple paragraphs, bow
  how often does one have that kind of arguments, where they couldn't be
  more sensibly put inside an environment?
%%%%%%%%%%%%%%%%% copy ends
-- 
Morten Høgholm