Definitions made with \newcommand die after one use

Question

I'm using Overleaf.

I created a simple command to combine \textbf and \texttt.

\newcommand{\textbftt}[1]{\textbf{\texttt{#1}}}

The definition is in the document prelude file.

I use the \textbftt command elsewhere in the document, e.g., textbftt{return}. It seems to work fine.

However, when I edit the file where \textbftt is used (and the edit has nothing to do with the use of \textbftt) the command no longer works. The text is rendered with neither bf nor tt.

I also see an error marking in the margin (a small red box with an 'x'). The attached error message says that the command is used in a way that is inconsistent with its definition. (How can that be if it worked properly at first?)

More confusing is that if I then make an extraneous edit to the file containing the definition, e.g., add an extra space someplace in the file, the command now works properly--until I again edit the file where it is used. (The same thing happens if I use \def instead of \newcommand.)

I find myself making repeated meaningless changes to the prelude file, e.g., adding and removing an extraneous space) to see what my document looks like.

Any thoughts about what might be going on?

Are the changes to the prelude file forcing Overleaf to re-read that file--and hence the definition? Doesn't it always do that when it recompiles?

Thanks.

Answer 1

In your document you have/had:

\def\textbftt[#1]{\textbf{\texttt{#1}}}

and in the question you said you had:

\newcommand{\textbftt}[1]{\textbf{\texttt{#1}}}

First things first: unless you really, absolutely know what you're doing, you should use \newcommand instead of \def in a document. If you look carefully, the LaTeX manual doesn't even explain the usage of \def, so it (sort of) doesn't belong to the system (of course it works because LaTeX runs on top of TeX, but it really shouldn't be used in an everyday document). \def is for "experts"!

Now, both of the definitions above are correct and both will work if used properly (what doesn't :-). However both define two very different commands!

\newcommand

Let's first tackle the second one, which is "easier". The syntax for \newcommand is:

\newcommand{<command>}[<num args>][<default>]{<replacement text>}

where both [<num args>] and [<default>] are optional, but the former is mandatory if the latter is to be used. <command> is the command name, in your case \textbftt, which you defined to take <num args>=1 argument, with no optional arguments (because <default> is not given) and the <replacement text> of this command is \textbf{\texttt{#1}}, where #1 is the first (and only) argument to the command, enclosed in braces ({...}). This all means that when you use that definition:

\textbftt{<some text>}

TeX will expand \textbftt, replacing the #1 in the <replacement text> by the stuff between (balanced!) braces:

\textbf{\texttt{<some text>}}

which is what you want.

\def

Now the \def version is trickier. The syntax of \def is (simplifying a little):

\def<command><parameter text>{<replacement text>}

where <command> and <replacement text> are the same as the ones in the \newcommand version. The <parameter text> is what tricked you because, well, it's the tricky part :-)

The <parameter text> can be arbitrary text, with the exception of { and }, which can contain up to 9 # symbols followed by consecutive numbers from 1 to 9 (i.e., #1, #2, ... #9---these are the "parameters"). Whatever you use in the <parameter text> except for the parameters must match exactly when you use the <command>. In your definition \def\textbftt[#1]{\textbf{\texttt{#1}}}, the <parameter text> is [#1], so whenever you use \textbftt TeX expects to find exactly a [, followed by arbitrary (balanced---balanced pairs of {...}), possibly empty, text, until the next ]. If TeX doesn't find any of these it will say that the Use of \textbftt doesn't match its definition.

Now, knowing that you need to enclose the text in [...] instead of {...} you now can use the command like in the previous version:

\textbftt[<some text>]

then TeX will expand \textbftt:

\textbf{\texttt{<some text>}}

and you have the same result, but with a different definition and usage.

The catch

But now you say: "Hey, I can use \textbftt[<some text>] instead of \textbftt{<some text>}!"

Well, yes, you can. But you should not. The LaTeX manual defines that optional arguments should be enclosed in [...], not mandatory arguments. Going against this convention makes the usage of the command counter intuitive and potentially problematic.

The other problem is that TeX knows that {...} are "delimiters", while [ and ] are just two characters just like ! and , and @ and... This means that if you need to use other [ or ] you need special protection to ensure that TeX does the right thing. For example:

\textbftt[some [text] with square brackets]

will not do what you want.
It will expand to:

\textbf{\texttt{some [text}} with square brackets]

And, finally, of course, \newcommand checks whether the command you are trying to create already exists and throws an error if you are about to redefine something important. \def just does it and you will only notice when chaos ensues.

If you search this site you'll see tons of examples of "you should've used \newcommand instead", so I suggest you stick to it unless you are sure of what you're doing.