29

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

Improve this question
20

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

Improve this answer
2
  • Ah! I didn't think about changing catcodes. – TH. Aug 19 '10 at 15:25
  • 2
    There is one active character which is \outer in LaTeX: \outer\def^^L{\par}. – Heiko Oberdiek Aug 17 '13 at 16:06
17

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.

Improve this answer
4
  • 4
    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 Floch Feb 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 Gerdes Jul 18 '15 at 6:29
  • 1
    @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 Floch Jul 23 '15 at 23:03
  • @BrunoLeFloch I see. I ended up here again for some other reason and when I read my comment again I thought, "Who the fuck is that idiot. Bruno is obviously right" but before I could tell him what a dumbfuck he was I realized it was me. Yah, the whole point is to give a name which you will only use on the top level so you should give another name to be used in other places. I'm an idiot. – Peter Gerdes Sep 4 '20 at 23:39
13

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.

Improve this answer
7

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

Improve this 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.

Improve this answer
0
5

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

Improve this answer
1
  • This must have changed in 2017: TeXLive2016 still had \outer, 2017 hasn't. Interestingly I have found no mention of this in ltnews. – campa Feb 6 '20 at 14:58
5

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
Improve this answer
3

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)

Improve this answer
2
  • I don’t know – I actually do use them in macros (\chapter, actually), and I don’t think that anything speaks against this. – Konrad Rudolph Aug 19 '10 at 12:57
  • No, no, I don't think anything speaks against this. I merely wanted to say that if you use \outer, it is most likely a command like \section that deserves it. – topskip Aug 19 '10 at 13:32
1

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.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.