[latexrefman-commits] [SCM] latexrefman updated: r1170 - trunk

[Karl Berry]

Author: karl
Date: 2024-05-09 17:39:42 +0000 (Thu, 09 May 2024)
New Revision: 1170

Modified:
   trunk/ChangeLog
   trunk/NEWS
   trunk/latex2e.texi
Log:
update fragile/robust discussion; mention cprotect

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog	2024-05-06 22:02:20 UTC (rev 1169)
+++ trunk/ChangeLog	2024-05-09 17:39:42 UTC (rev 1170)
@@ -1,3 +1,8 @@
+2024-05-09  Karl Berry  <karl at freefriends.org>
+
+	* latex2e.texi (\protect): update for current LaTeX; most commands
+	have been robust since October 2019. Mention the cprotect package.
+
 2024-05-06  Karl Berry  <karl at freefriends.org>
 
 	* latex2e.texi (Input encodings): brief introduction to character

Modified: trunk/NEWS
===================================================================
--- trunk/NEWS	2024-05-06 22:02:20 UTC (rev 1169)
+++ trunk/NEWS	2024-05-09 17:39:42 UTC (rev 1170)
@@ -20,6 +20,8 @@
 * Briefly describe input encodings and how to handle them.
 
 Changes:
+* Update the discussion of fragile commands at \protect; since October 2019,
+most commands have been robust. Mention the cprotect package.
 * The lengthy list of commands for class and package writers, from
 clsguide, now split into sections instead of being one long table.
 

Modified: trunk/latex2e.texi
===================================================================
--- trunk/latex2e.texi	2024-05-06 22:02:20 UTC (rev 1169)
+++ trunk/latex2e.texi	2024-05-09 17:39:42 UTC (rev 1170)
@@ -10451,20 +10451,16 @@
 
 All @LaTeX{} commands are either @dfn{fragile} or @dfn{robust}.  A
 fragile command can break when it is used in the argument to certain
-other commands.  Commands that contain data that @LaTeX{} writes to an
-auxiliary file and re-reads later are fragile.  This includes material
-that goes into a table of contents, list of figures, list of tables,
-etc.  Fragile commands also include line breaks, any command that has an
-optional argument, and many more. To prevent such commands from
-breaking, one solution is to preceded them with the command
- at code{\protect}.
+other commands, typically those that write material to the table of
+contents, the cross-reference file, etc.  To prevent fragile
+commands from causing errors, one solution is to precede them with the
+command @code{\protect}.
 
 For example, when @LaTeX{} runs the @code{\section@{@var{section
 name}@}} command it writes the @var{section name} text to the
 @file{.aux} auxiliary file, moving it there for use elsewhere in the
-document such as in the table of contents.  Any argument that is
-internally expanded by @LaTeX{} without typesetting it directly is
-referred to as a 
+document such as in the table of contents.  Such an argument that is
+used in multiple places is referred to as a
 @cindex moving arguments
 @dfn{moving argument}.  A command is fragile if it can
 expand during this process into invalid @TeX{} code.  Some examples of
@@ -10474,39 +10470,55 @@
 @code{array} environments (@pxref{tabular}).
 
 If you get strange errors from commands used in moving arguments, try
-preceding it with @code{\protect}.  Every fragile commands must be
+preceding it with @code{\protect}.  Each fragile command must be
 protected with their own @code{\protect}.  
 
 Although usually a @code{\protect} command doesn't hurt, length
-commands are robust and should not be preceded by a @code{\protect}
-command. Nor can a @code{\protect} command be used in the argument to
- at code{\addtocounter} or @code{\setcounter} command.
+commands such as @code{\parindent} should not be preceded by a
+ at code{\protect} command (@pxref{Lengths}. Nor can a @code{\protect}
+command be used in the argument to @code{\addtocounter} or
+ at code{\setcounter} command (@pxref{\setcounter} and
+ at ref{\addtocounter}. These commands are already robust.
 
-In this example the @code{\caption} command gives a mysterious error
-about an extra curly brace.  Fix the problem by preceding each
- at code{\raisebox} command with @code{\protect}.
+As of the October 2019 release of @LaTeX{}
+(@url{https://www.latex-project.org/news/latex2e-news/ltnews30.pdf}),
+most commands that had been previously fragile were fixed to be
+robust. For example, any command taking an optional argument, such as
+ at code{\root} or @code{\raisebox}, was fragile, but is now
+robust. Similarly, @code{\(...\)} math was fragile and is now robust
+(@code{$...$} has always been robust).
 
+ at findex \verb at r{, as fragile command}
+Perhaps the most commonly used remaining fragile command is
+ at code{\verb}; for example,
+
 @example
 \begin@{figure@}
   ...
-  \caption@{Company headquarters of A\raisebox@{1pt@}@{B@}\raisebox@{-1pt@}@{C@}@}
+  \caption@{This \verb|\command| causes an error.@}
 \end@{figure@}
 @end example
 
-In the next example the @code{\tableofcontents} command gives an error
-because the @code{\(..\)} in the section title expands to illegal @TeX{}
-in the @file{.toc} file.  You can solve this by changing @code{\(..\)}
-to @code{\protect\(..\protect\)}.
+Adding @code{\protect} does not help here. It's usually feasible to
+rewrite the caption (or section heading or whatever) to use
+ at code{\texttt}, often the simplest solution.
 
+ at PkgIndex{cprotect}
+ at findex \cprotect
+Alternatively, to use @code{\verb}, you can apply the
+ at code{\cprotect} command from @code{cprotect} package
+(@url{https://ctan.org/pkg/cprotect}) to the @code{\caption}:
+
 @example
-\begin@{document@}
-\tableofcontents
-...
-\section@{Einstein's \( e=mc^2 \)@}
-...
+\cprotect\caption@{This \verb|\command| is ok with \verb|\cprotect|.@}
 @end example
 
+ at findex \cprotEnv
+ at code{\cprotect} also allows use of @code{\begin...\end} environments
+in moving arguments, where they are normally not allowed, via a
+similar prefix command @code{\cprotEnv}.
 
+
 @node \ignorespaces & \ignorespacesafterend
 @section @code{\ignorespaces & \ignorespacesafterend}
 
@@ -11451,7 +11463,6 @@
 
 New counters are created with @code{\newcounter}.  @xref{\newcounter}.
 
-
 @menu
 * \alph \Alph \arabic \roman \Roman \fnsymbol:: Print value of a counter.
 * \usecounter::           Use a specified counter in a list environment.