\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.

9 Answers
9

\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.

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

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):

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.

Since Ryan's answer is the most complete, I'll add one more thing as a comment. When defining an \outer command in a macro package, one should always provide an equivalent non-outer command. E.g. by defining \innermymacro and then \outer\def\mymacro{\innermymacro}. This allows other people to use the macro inside definitions, and in other places where it would be needed.
–
Bruno Le FlochFeb 9 '11 at 16:43

@Bruno, The whole reason you declare a macro outer is because you want to forbid it from being used indirectly by other macros. Either because it would be unreliable inside other macros or you want to force it to appear explicitly in the document structure. So if you are going to declare it outer presumably you shouldn't give an equivalent non-outer version. Am I missing something?
–
Peter GerdesJul 18 at 6:29

@PeterGerdes you are missing that making a macro \outer only makes it slightly more complicated to put it into a definition. It is often not possible to predict what programmers of packages relying on your package will need. For instance, look up the reason why LaTeX2e decided not to make \newcount etc \outer, contrarily to the earlier plain TeX format.
–
Bruno Le FlochJul 23 at 23:03

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.

If you simply want to provide additional optional arguments (or handle extra information supplied via some new commands) then the document should still contain \section. You would simply give \section a different definition. \outer would prohibit you from defining \myspecialsection which does some stuff and then calls section. This seems like good semantics. Augmenting the section command shouldn't stop TeX editors and users from recognizing that it's still a section being created.
–
Peter GerdesJul 18 at 6:37

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.