[latexrefman] \protect

[Lambda Coder]

I am responding to this advice from Contributing to the LaTeX
reference manual at https://latexref.xyz/dev/writing.html:

"The easiest way to start is to put your suggestion in plain text and
email the list. We will mark it up for insertion in the document
source."

Attached is the txt file of one section that I edited and re-wrote a
while back for local users. I submit this version as an update to the
\protect section of the current manual.

I have re-written many sections like this over the years, but have not
taken the time to submit them to your list. Before I send anymore, I
want to see if such contributions are welcome and if there are any
suggestions from the list. Thanks.

--S.J.
-------------- next part --------------
\protect

\protect solves some "missing curly brace" errors.

\protect refers to protecting macro expansions from unintentionally creating invalid LaTeX code. Some commands need protection when LaTeX moves the code to external files and back, such as when creating auxiliary (.aux) files for table of contents, list of figures, indexes, glossaries, and similar lists.

\protect ensures that code in the main text, such as a chapter title, remains  valid code when moved to another location, such as an entry in the table of contents.

Take for example this valid caption for a photograph:

\caption{Moonrise photo by \citeauthor{adams} \shortcite{adams}}

Yet when creating the necessary .aux file for the list of captions, LaTeX errors with a cryptic message about a missing curly brace. \protect can fix that:

\caption{Moonrise photo by \protect \citeauthor{adams} \protect \shortcite{adams}}

\protect holds off the expansion and execution of \citeauthor and \shortcite commands until the .aux file is read again to typeset the list of captions elsewhere in the document.

Not all commands need protection. Some are robust enough by design that they can survive the move to an auxiliary file and back again. Many commands though are fragile, especially those that take optional arguments, line breaks, raising or lowering format boxes, and other format altering macros. Unfortunately, there is no universal command to protect all fragile commands. Every fragile command needs its own protection switch. Hence the two \protect commands, one for each fragile command, in the Moonrise example above.

Using \protect for robust commands, such as \length, that do not need protection, turns out to be harmless. LaTeX does not error out, but continues with its normal processing. \protect, however, cannot be used for arguments to \addtocounter or \setcounter.

More examples of with and without \protect:

Without \protect:
\begin{figure}
  ...
  \caption{Picture of A\raisebox{1pt}{B}\raisebox{-1pt}{C}}
\end{figure}

With \protect:
\begin{figure}
  ...
  \caption{Picture of A\protect\raisebox{1pt}{B}\protect\raisebox{-1pt}{C}}
\end{figure}

In this example, without \protect, \(..\) expands to illegal TeX in the .toc file. Protecting the escaped parens solves the premature expansion.

Without \protect:
\begin{document}
\tableofcontents
...
\section{Einstein's \( e=mc^2 \)}

With \protect:
\begin{document}
\tableofcontents
...
\section{Einstein's \protect\( e=mc^2 \protect\)}