Have seen

\cs_new_protected:Nn \feuds_newteorema_define:nn

Is this just a definition of a function named \feuds_newteorema_define (taking two arguments as far as I can tell), Or is it something else ?

What does it mean exactly by Protected Restriction ?

  • \cs_new_protected:Nn defines a \protected macro, take a look at the e-TeX manual what that means (it basically means that the macro doesn't expand in an \edef context, stops the scanning for \noalign or \omit in an alignment, doesn't expand inside a \write)
    – Skillmon
    Sep 29 at 9:19
  • 2
    are you user Veak?, you can ask stackexchange to merge the accounts if they are separated by accident. Sep 29 at 9:49
  • @Skillmon I guess that's an answer (I couldn't see any obvious duplicate, surprisingly) Sep 29 at 10:24

1 Answer 1


Short theory

\cs_new_protected:Nn is documented in the interface3.pdf and states that a function defined with it doesn't expand any further inside of an x or e type expansion.

What this means at the lower level is, that it uses the e-TeX primitive \protected. You can see what that means in the e-TeX manual (texdoc etex). But to summarise:

A macro defined \protected

  • doesn't expand in an \edef or \expanded context
  • doesn't expand in a \write or \message context
  • stops TeX's scanning for \omit or \noalign inside of an alignment context (like a \relax would)

Simple examples

An example showcasing the different behaviour (in plain TeX):

\protected\def\foo{protected }

Results in the following output to stdout:

This is pdfTeX, Version 3.141592653-2.6-1.40.25 (TeX Live 2023) (preloaded format=pdflatex 2023.8.16)  29 SEP 2023 12:21
entering extended mode
 restricted \write18 enabled.
 %&-line parsing enabled.
LaTeX2e <2023-06-01> patch level 1
L3 programming layer <2023-08-11>
> \baz=macro:
->\foo unprotected.
l.4 \show\baz

As you can see \bar was expanded (to the word "unprotected"), but \foo wasn't and remains as \foo inside of \baz's replacement text.

Another example using the L3 syntax and printing into the PDF:


\cs_new_protected:Nn \test_foo: { foo }
\cs_new:Nn \test_bar: { bar }

\cs_new:Nx \test_baz: { \test_foo: \test_bar: }
\test_baz: \par

\cs_set_protected:Nn \test_foo: { FOO }
\cs_set:Nn \test_bar: { BAR }


enter image description here

As you can see, on the first usage of \test_baz: it printed "foobar" since both \test_foo: and \test_bar: were lowercase. If we alter that afterwards to both being uppercase this only results in "FOO" but "bar" remains lowercase. That's the case because when we defined \test_baz: we expanded \test_bar: to "bar", but \test_foo: wasn't expanded due to it being protected, so its redefinition also alters the result of \test_baz:.

Why or when is this behaviour important?

In TeX we have the notion of things that are expandable, and things that aren't. Some primitives are expandable, but most aren't. Macros on the other hand are expandable (unless defined \protected, in which case they are only expandable by certain operations like \expandafter, but not in \edef or \expanded).

If a macro now uses one of the unexpandable primitives, but somehow ends up in an \edef or \expanded context and would expand itself you'd get undefined/unpredictable behaviour (because anything after your unexpandable primitives still gets expanded). Because of this, it is necessary to define such macros \protected, so that the behaviour (almost -- let's ignore the ways to still expand a \protected macro) always stays well defined.

Here is a small, hopefully easy to understand example of this (again in plain TeX syntax):


\edef\test{\mymacroB}% this is still fine
\edef\test{\mymacroA}% this throws an error

This prints to stdout:

! Undefined control sequence.
\mymacroA ->\def \mythingA 
l.5 \edef\test{\mymacroA
                        }% this throws an error

even though both \mythingA and \mythingB would be fine if used outside of \edef. The reason is quite simple: \def isn't expandable, so stays the same, but TeX continues to expand the rest of the replacement text of \mymacroA which hits \mythingA. That macro isn't expandable, so we get above error message.

  • Could you provide an example of how protected works out. I find the answer too theoretical.
    – Veak
    Sep 29 at 10:57
  • For the L3 syntax, do the x or e type expansion have meaning ? If the definition of protected is expressed in terms of x or e type commands only, \cs_new_protected:Nn might skip the discussion for the L3 Syntax routines.
    – Veak
    Sep 29 at 13:47
  • In general terms the protected marker means that the defined function is protected from expansion in certain contexts. Expansion is the process of replacing macros and control sequences with their actual values or definitions. However, there are situations where this expansion is not desired, especially in places where LaTeX processes content in a different way, such as section headings. Do the manuals give such discussion regarding the need for expansion protection for section headings ?
    – Veak
    Sep 29 at 13:59
  • @Fluffy x is \edef expansion, e is \expanded expansion. It means that the macro will as argument not get literally what was given, but the result of either \edef or \expanded on that argument. I don't understand what you mean with "... might skip the discussion for the L3 Syntax routines".
    – Skillmon
    Sep 29 at 14:19
  • 1
    @Fluffy yes, in LaTeX2e you got the \protect macro to use in headings and stuff (moving arguments is the term) to prevent things from expanding, a mechanism that predates e-TeX and the \protected primitive. See the LaTeX companion.
    – Skillmon
    Sep 29 at 14:21

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .