When is it appropriate to use \outer?

Question

\outer is a strange beast. Any control sequence declared \outer cannot be used as either the parameter text or replacement text of a macro, at least if the control sequence is declared \outer at the time the parameters are tokenized or the definition is scanned, respectively. That is, both the definition of \bar and the use of \baz are errors:

\outer\def\foo{asdf}
\def\bar{\foo}
\def\baz#1{#1}
\baz\foo

However, changing this slightly to

\def\bar{\foo}
\def\baz#1{\outer\def\foo{asdf}#1}
\baz\foo
\bar

so that \foo is only declared \outer after the definition of \bar and after the parameters to \baz have been parsed, compiles correctly.

I could see requiring a macro to appear only in vertical mode, but \outer doesn't do that. In fact, \outer control sequences can appear in any of vertical, internal vertical, horizontal, restricted horizontal, math, and display math modes.

\outer\def\foo{asdf}
\foo% vertical mode

foo \foo% horizontal mode

\hbox{\foo}% restricted horizontal mode

\vbox{\foo}% internal vertical mode

$\foo$% math mode

$$\foo$$% display math mode
\bye

So given all of that, what is the utility of \outer?

Answer 1

\outer isn't used in LaTeX2e and I'm not aware of any packages that do, either (there are probably some, though). However, I've come across occasion to think it might sometimes be a good idea.

\outer prevents a macro from being used inside any other macro. But when is this even desirable? Well, consider the use of \verb: because it changes catcodes, and catcodes are frozen when tokenization occurs, \verb can never be (reliably) used inside any other macro. For examples, this will not work:

\section{The \verb|\outer| primitive}

Now, \verb contains its own processing to give a suitable error message in this case anyway, but there are other packages that define commands that use catcode-mucking to do their work. For examples, some indexing commands and, say, \url, can give bad output if they're used inside macros. In theory, you could use \outer to enforce their use in running text only, but this isn't done very often.

Note also that eTeX gives \scantokens which relieves many of the restrictions of only being able to change catcodes before tokenization occurs. So \outer is less useful these days from that point of view.

Answer 2

According to the TeXbook, the sole and intended purpose of \outer is to detect runaway arguments to \long macros and other situations where forbidding \par won't help you (p. 206). Knuth explicitly notes that he hopes that format authors make discriminating choices as to their \outer macros so that the document structure can inform TeX as to the presence of missing close-braces. To see what kind of choices he considered discriminating, here are the things he declared \outer in the plain style (Appendix B) and the TeXbook format (Appendix E):

In plain:

• \newanything (count, dimen, etc.)
• ^^L, as noted by Lev Bishop
• \+ (the tab skip command)
• \proclaim (which functions as a theorem environment), \beginsection
• \bye (ends the document)

In the TeXbook:

• \beginchapter, \endchapter, \begindisplay, \enddisplay, \begintt, \exercise, \dangerexercise, \ddangerexercise, \answer (all of them basically sectioning commands)
• \danger, \ddanger (for putting in the Bourbaki "dangerous bend" signs)

Will Robertson says that LaTeX2e doesn't use \outer, so no lessons are forthcoming there, but based on this example, I would say that if it had been written by Knuth, then macros such as \section and \chapter, and likely environments in general, would all be \outer.

To generalize, then, I would say that \outer is supposed to be used to communicate the intent of the document structure from the author to TeX: to indicate which regions of the document are self-contained. Of course, as designed it functions entirely to save the author from themselves (it is only for error checking, not for layout), so given that its intended place is in high-level structural macros, it seems unlikely that the general TeX user will ever use any macros that they themselves define to be \outer: how many people write formats for their own use, or at all for that matter?

Another problem with \outer shows up in a few of TeX's design decisions and is related to the passage of time. Namely, this macro seems designed to minimize wasteful duplication of effort in that it helps provide useful diagnostics. My experience with LaTeX is that it does not provide useful diagnostics: whenever I get an error, I usually get a few dozen and only the first means anything. I correct that one, then recompile; often that eliminates all subsequent errors.

The careful use of \outer would confine meaningless errors to small regions of the document, so that once a sectioning boundary is crossed no further errors should arise from unbalanced braces in any one macro. Thus, hopefully, the debugging process can proceed in sublinear time in the number of errors (or, at least, linear with a small coefficient). I think few young computer users (like me) have the habit of performing batch processing on their work, which was presumably more necessary back in the days of shared computing, paid computer time, and slower processors. For better or worse, we can have (sometimes hostile) dialogues with our machines these days.

Answer 3

I see no real use for \outer either, because it semantics are such that it does not do anything helpful except in trivial cases. Even macros that do change category codes can make perfect sense in an argument, in actual cases (for example in the setup macros of more complex environments).

Older versions of LuaTeX silently ignored \outer. This was later changed by request to be more compatible with older engines, so now \outer can produce an error again, but this backward compatibility feature can still be disabled by specifying

\suppressoutererror=1

in the source code.

Answer 4

The bm package uses \outer to prevent a malformed \bm eating the entire document.

Answer 5

A Beginner's book of TeX says it is for error detection.

I think it is a good idea with a bad semantics. It's perfectly reasonable to define wrappers around macros like \section, to allow, say, optional indexing information to be added. Throwing an error if the macro is expanded within a box would fit this intended use much better.

I can think of one use for the semantics as it stands: to ensure that macros that change catcodes occur at the definitional top level, making it harder to hide catcode changes, and so make the Tex source that bit easier to understand.

Answer 6

Latex defines ASCII formfeed ^^L as an \outer. This is the only good use of outer that I can think of. So, the answer to your question is "almost none".

Answer 7

Packages with \outer macros (grep -r '\\outer\\' texmf-dist/tex/latex/TeX Live 2013):

• etex.sty: \reserveinserts
• verbatimcopy: \VerbatimCopy, \setOutputDir
• cprotect: \cprotect
• gmdoc: \DefIndex, \CodeUsgIndex, \CodeCommonIndex, \CodeMarginize, \Define, \CodeUsage, \changes, \chgs, \chschange, \DescribeMacro, \Describe
• plain: \+, \beginsection
• bm: \bm@end
• fontdoc: \endencoding, \endmetrics
• localloc \newinsert
• slides.def: \newifG
• latex209.def: \proclaim
• dvipaste: \sendout
• docidx2e, docindex: \indexnewletter

Answer 8

I'd assume that commands like \section should be \outer, so that they don't appear in a macro.

(Depending on the use case, of course)

Answer 9

It's a useful concept in that it potentially provides the ability to force a macro to be used explicitly (or clever tricks applied) in the TeX code for any document it appears in. Thus if \fooouter is used in the document bar.tex one is assured that the string \fooouter will appear in bar.tex or one of it's dependencies absent trickery.

Note that another recent question on this site about automatically replacing macros with their definitions had answering users specifically suggesting a \newsanemacro command that would only allow relatively simply macros to be defined that might be automatically eliminated. \outer seems like it offers just such a tool for the common case of the simple user textual substitution.