1 % \iffalse meta-comment
4 % The LaTeX3 Project and any individual authors listed elsewhere
7 % This file is part of the LaTeX base system.
8 % -------------------------------------------
10 % It may be distributed and/or modified under the
11 % conditions of the LaTeX Project Public License, either version 1.3c
12 % of this license or (at your option) any later version.
13 % The latest version of this license is in
14 % http://www.latex-project.org/lppl.txt
15 % and version 1.3c or later is part of all distributions of LaTeX
16 % version 2005/12/01 or later.
18 % This file has the LPPL maintenance status "maintained".
20 % The list of all files belonging to the LaTeX base distribution is
21 % given in the file `manifest.txt'. See also `legal.txt' for additional
24 % The list of derived (unpacked) files belonging to the distribution
25 % and covered by LPPL is defined by the unpacking scripts (with
26 % extension .ins) which are part of the distribution.
30 %%% From File: ltmiscen.dtx
34 \ProvidesFile{ltmiscen.dtx}
35 [2014/09/29 v1.1l LaTeX Kernel (Misc. Environments)]
37 \documentclass{ltxdoc}
38 \GetFileInfo{ltmiscen.dtx}
51 \MaintainedByLaTeXTeam{latex}
60 % \changes{v1.0c}{1994/03/28}{Improve Documentation}
61 % \changes{v1.0d}{1994/03/29}{Remove counter macros to ltcntlen}
62 % \changes{v1.0g}{1994/05/02}{Changed 91 to 1991 and moved some bits}
63 % \changes{v1.0i}{1994/05/05}{Removed braces from ifnextchar and
65 % \changes{v1.0m}{1994/05/20}{Use new warning commands}
66 % \changes{v1.0n}{1994/05/21}{Use new error commands}
67 % \changes{v1.0s}{1994/10/14}{Move math to other file}
68 % \changes{v1.0v}{1994/11/17}
69 % {\cs{@tempa} to \cs{reserved@a}}
70 % \changes{v1.0x}{1995/04/22}{Removed extra def of \cs{@gobble}}
71 % \changes{v1.0z}{1995/07/13}{Improve Documentation}
72 % \changes{v1.1c}{1996/04/22}{Improve Documentation}
73 % \changes{v1.1d}{1996/06/03}{Move setting of verbatim font and
75 % \changes{v1.1g}{1998/08/17}{(RmS) Minor documentation fixes.}
77 % \section{Miscellaneous Environments}
78 % This section implements the basic environment mechanism, and also
79 % a few specific environments including |document|, The math
80 % environments and related commands, the `flushing' environments,
81 % (|center|, |flushleft|, |flushright|), and |verbatim|.
87 \message{environments,}
90 % \subsection{Environments}
92 % |\begin{foo}| and |\end{foo}| are used to delimit environment |foo|.
94 % |\begin{foo}| starts a group and calls |\foo| if it is defined,
95 % otherwise it does nothing.
97 % |\end{foo}| checks to see that it matches the
98 % corresponding |\begin| and if so, it calls |\endfoo| and does an
99 % |\endgroup|. Otherwise, |\end{foo}| does nothing.
101 % If |\end{foo}| needs to ignore blanks after it, then |\endfoo| should
102 % globally set the |@ignore| switch true with |\@ignoretrue|
103 % (this will automatically be global).
106 % NOTE: |\@@end| is defined to be the |\end| command of \TeX82.
108 % |\enddocument| is the user's command for ending the manuscript file.
110 % |\stop| is a panic button --- to end \TeX\ in the middle.
112 % \begin{oldcomments}
115 % \@checkend{document} %% checks for unmatched \begin
119 % then close file @mainaux
120 % if G@refundefined = true
121 % then LaTeX Warning: 'There are undefined references.' fi
122 % if @multiplelabels = true
123 % then LaTeX Warning:
124 % 'One or more label(s) multiply defined.'
126 % \@setckpt {ARG1}{ARG2} == null
127 % \newlabel{LABEL}{VAL} ==
130 % if def(\reserved@a) = def(\r@LABEL)
131 % else @tempswa := true fi
133 % \bibcite{LABEL}{VAL} == null
136 % if def(\reserved@a) = def(\g@LABEL)
137 % else @tempswa := true fi
141 % \input \jobname.AUX
143 % then LaTeX Warning: 'Label may have changed.
144 % Rerun to get cross-references right.'
150 % \@writefile{EXT}{ENTRY} ==
151 % if tf@EXT undefined
152 % else \write\tf@EXT{ENTRY}
156 % \begin{macro}{\@currenvir}
157 % The name of the current environment. Initialized to
158 % \texttt{document} to so that |\end{document}| works correctly.
160 \def\@currenvir{document}
164 % \begin{macro}{\if@ignore}
165 % \begin{macro}{\@ignoretrue}
166 % \begin{macro}{\@ignorefalse}
167 % \changes{v1.1e}{1996/07/26}{put \cs{global} into definition}
169 \def\@ignorefalse{\global\let\if@ignore\iffalse}
170 \def\@ignoretrue {\global\let\if@ignore\iftrue}
178 % \begin{macro}{\ignorespacesafterend}
179 % \changes{v1.1e}{1996/07/26}{user level macro added}
181 \let\ignorespacesafterend\@ignoretrue
185 % \begin{macro}{\enddocument}
186 % \changes{LaTeX2.09}{1993/08/03}
187 % {Changed redefinition of \cs{global} to redefinition
189 % \changes{LaTeX2.09}{1993/09/08}
190 % {Added warning in case of undefined references.}%
191 % \changes{v0.9e}{1993/12/09}{Hook added}
195 % The |\end{document}| hook is executed first. If necessary it can
196 % contain a |\clearpage| to output dangling floats first. In this
197 % position it can also contain something like |\end{foo}| so that
198 % the whole document effectively starts and ends with some special
199 % environment. However, this must be used with care, eg if two
200 % applications would use this without knowledge of each other the
201 % order of the environments will be wrong after all.
202 % |\AtEndDocument| is redefined
203 % at this point so that and such commands that get into the hook do
204 % not chase their tail\ldots
205 % \changes{v1.0y}{1995/04/27}{\cs{@checkend} moved after hook}
206 % \changes{v1.0z}{1995/07/13}{Set \cs{@setckpt} to \cs{@gobbletwo}
207 % instead of defining it by hand}
208 % \changes{v1.1i}{2000/05/19}
209 % {Reset \cs{AtEndDocument} for latex/3060}
211 \let\AtEndDocument\@firstofone
213 \@checkend{document}%
217 \immediate\closeout\@mainaux
218 \let\@setckpt\@gobbletwo
219 \let\@newl@bel\@testdef
221 % \changes{v1.0z}{1995/07/13}{Shorten redefinition of \cs{bibcite} and
223 % The previous line is equiv to setting
225 % \def\newlabel{\@testdef r}%
226 % \def\bibcite{\@testdef b}%
228 % \changes{v1.1k}{2010/08/17}{Use braces around \cs{input} arg (pr/4124)}
229 % \changes{v1.1l}{2010/08/17}{Change of plan: use \cs{@@input} instead
231 % We use |\@@input| to load the \texttt{.aux} file, so that it doesn't
232 % show up in the list of files produced by |\listfiles|.
235 \makeatletter \@@input\jobname.aux
238 % \changes{v1.0w}{1994/11/30}
239 % {(DPC) Use \cs{@dofilelist}}
243 % First we check for font size substitution bigger than
244 % |\fontsubfuzz|. The |\relax| is necessary because this is a macro
246 % \changes{v1.0w}{1994/11/30}
247 % {(DPC) Do warnings even for \cs{nofiles}}
249 \ifdim \font@submax >\fontsubfuzz\relax
251 % In case you wonder about the |\@gobbletwo| inside the message
252 % below, this is a horrible hack to remove the tokens |\on@line.|
253 % that are added by |\@font@warning| at the end.
254 % \changes{v1.1j}{2000/07/11}{Fix typo in warning}
256 \@font@warning{Size substitutions with differences\MessageBreak
257 up to \font@submax\space have occurred.\@gobbletwo}%
260 % The macro |\@defaultsubs| is initially |\relax| but gets redefined
262 % a warning if there have been some default font substitutions.
263 % \changes{v1.0z}{1995/07/13}{Use \cs{@defaultsubs} instead of switch}
267 % The macro |\@refundefined| is initially |\relax| but gets redefined
268 % to produce a warning if there are undefined refs.
269 % \changes{v1.1b}{1995/10/24}{Use \cs{@refundefined} instead of switch}
273 % If a label is defined more than once, |\@tempswa| will always be
274 % true and thus produce a ``Label(s) may \ldots'' warning. But
275 % since a rerun will not solve that problem (unless one uses a
276 % package like \texttt{varioref} that generates labels on the fly),
277 % we suppress this message.
278 % \changes{v1.0e}{1994/04/20}{Changed logic for producing
280 % \changes{v1.1b}{1995/10/24}{Changed logic for producing
281 % warning messages and removed switch}
284 \ifx \@multiplelabels \relax
286 \@latex@warning@no@line{Label(s) may have changed.
287 Rerun to get cross-references right}%
294 \deadcycles\z@\@@end}
298 % \begin{macro}{\@testdef}
300 \def\@testdef #1#2#3{%
301 \def\reserved@a{#3}\expandafter \ifx \csname #1@#2\endcsname
302 \reserved@a \else \@tempswatrue \fi}
307 % \begin{macro}{\@writefile}
308 % \changes{v1.0l}{1994/05/20}{Added correct setting of \cs{protect}.}
309 % \changes{v1.0t}{1994/11/04}{Removed setting of \cs{protect}. ASAJ.}
310 % \changes{v1.0z}{1995/07/13}{Added missing percent and use \cs{relax}
313 \long\def\@writefile#1#2{%
314 \@ifundefined{tf@#1}\relax
316 \immediate\write\csname tf@#1\endcsname{\the\@temptokena}%
322 % \begin{macro}{\stop}
324 \def\stop{\clearpage\deadcycles\z@\let\par\@@par\@@end}
329 % \begin{oldcomments}
332 \everypar{\@nodocument} %% To get an error if text appears before the
333 \nullfont %% \begin{document}
336 % \begin, \end, and \@checkend changed so \end{document} will catch
337 % an unmatched \begin. Changed 24 May 89 as suggested by
338 % Frank Mittelbach and Rainer Sch\"opf.
342 % IF \NAME undefined THEN \reserved@a == BEGIN report error END
343 % ELSE \reserved@a ==
344 % (\@currenvir :=L NAME) \NAME
346 % @ignore :=G F %% Added 30 Nov 88
349 % \@currenvir :=L NAME
358 % IF @endpe = T %% @endpe set True by \@endparenv
359 % THEN \@doendpe %% \@doendpe redefines \par and \everypar
360 % %% to suppress paragraph indentation in
361 % FI %% immediately following text
368 % \@checkend{NAME} ==
370 % IF \@currenvir = NAME
371 % ELSE \@badend{NAME}
378 % \begin{macro}{\begin}
379 % \changes{LaTeX2.09}{1992/03/18}{Changed \cs{@ignoretrue} to
380 % \cs{@ignorefalse} (as documented)}
381 % \changes{LaTeX2.09}{1992/08/24}{Added code to \cs{begin} to
382 % remember line number. Used by \cs{@badend} to display
383 % position of non-matching \cs{begin}.}
384 % \changes{v1.1e}{1996/07/26}{remove \cs{global} before \cs{@ignore...}}
388 {\def\reserved@a{\@latex@error{Environment #1 undefined}\@eha}}%
389 {\def\reserved@a{\def\@currenvir{#1}%
390 \edef\@currenvline{\on@line}%
391 \csname #1\endcsname}}%
393 \begingroup\@endpefalse\reserved@a}
397 % \begin{macro}{\end}
398 % \changes{v1.1e}{1996/07/26}{remove \cs{global} before \cs{@ignore...}}
401 \csname end#1\endcsname\@checkend{#1}%
402 \expandafter\endgroup\if@endpe\@doendpe\fi
403 \if@ignore\@ignorefalse\ignorespaces\fi}
407 % \begin{macro}{\@checkend}
409 \def\@checkend#1{\def\reserved@a{#1}\ifx
410 \reserved@a\@currenvir \else\@badend{#1}\fi}
414 % \begin{macro}{\@currenvline}
415 % We do need a default value for |\@currenvline| on top-level since
416 % the document environment cancels the brace group. This means that
417 % a mismatch with |\begin|\allowbreak|{document}| will not produce
418 % a line number. Thus the outer default must be |\@empty| or we
419 % will end up with two spaces.
420 % \changes{v1.0q}{1994/05/24}{Use \cs{@empty} as outer default}
422 \let\@currenvline\@empty
427 % \subsection{Center, Flushright, Flushleft}
433 % \begin{oldcomments}
435 % \center, \flushright and \flushleft set
436 % \rightskip = 0pt or \@flushglue (as appropriate)
437 % \leftskip = 0pt or \@flushglue (as appropriate)
439 % \parfillskip = 0pt. (except \flushleft)
440 % \\ == \par \vskip -\parskip
441 % \\[LENGTH] == \\ \vskip LENGTH
442 % \\* == \par \penalty 10000 \vskip -\parskip
443 % \\*[LEN] == \\* \vskip LENGTH
445 % They invoke the trivlist environment to handle vertical spacing before
448 % \centering, \raggedright and \raggedleft are the declaration analogs
451 % \raggedright has a more universal effect, however. It sets
452 % \@rightskip := flushglue. Every environment, like the list
454 % that set \rightskip to its 'normal' value set it to \@rightskip
458 % \begin{macro}{\@centercr}
459 % \changes{v1.0h}{1994/05/03}{\cs{@badcrerr} replaced by \cs{@nolnerr}}
460 % \changes{v1.0z}{1995/07/13}{Use \cs{nobreak}}
462 \def\@centercr{\ifhmode \unskip\else \@nolnerr\fi
463 \par\@ifstar{\nobreak\@xcentercr}\@xcentercr}
467 % \begin{macro}{\@xcentercr}
469 \def\@xcentercr{\addvspace{-\parskip}\@ifnextchar
470 [\@icentercr\ignorespaces}
474 % \begin{macro}{\@icentercr}
476 \def\@icentercr[#1]{\vskip #1\ignorespaces}
481 % \begin{environment}{center}
482 % \changes{v0.9h}{1993/12/13}{Removed optional argument of \cs{item}}
483 % \changes{v1.0u}{1994/11/12}{Changed end macro to \cs{def}: safer and
485 % We use |\relax| to prevent |\item| scanning too far.
487 \def\center{\trivlist \centering\item\relax}
491 \def\endcenter{\endtrivlist}
495 % \begin{macro}{\centering}
499 \rightskip\@flushglue\leftskip\@flushglue
500 \parindent\z@\parfillskip\z@skip}
504 % \begin{macro}{\@rightskip}
506 \newskip\@rightskip \@rightskip \z@skip
510 % \begin{environment}{flushleft}
511 % \changes{v0.9h}{1993/12/13}{Removed optional argument of \cs{item}}
512 % \changes{v1.0u}{1994/11/12}{Changed end macro to \cs{def}: safer and
514 % We use |\relax| to prevent |\item| scanning too far.
516 \def\flushleft{\trivlist \raggedright\item\relax}
520 \def\endflushleft{\endtrivlist}
524 % \begin{macro}{\raggedright}
527 \let\\\@centercr\@rightskip\@flushglue \rightskip\@rightskip
533 % \begin{environment}{flushright}
534 % \changes{v0.9h}{1993/12/13}{Removed optional argument of \cs{item}}
535 % \changes{v1.0u}{1994/11/12}{Changed end macro to \cs{def}: safer and
537 % We use |\relax| to prevent |\item| scanning too far.
539 \def\flushright{\trivlist \raggedleft\item\relax}
543 \def\endflushright{\endtrivlist}
547 % \begin{macro}{\raggedleft}
551 \rightskip\z@skip\leftskip\@flushglue
552 \parindent\z@\parfillskip\z@skip}
560 % \subsection{Verbatim}
563 % The verbatim environment uses the fixed-width |\ttfamily| font, turns
564 % blanks into spaces, starts a new line for each carriage return (or
565 % sequence of consecutive carriage returns), and interprets
566 % \emph{every} character literally.
567 % I.e., all special characters |\, {, $|, etc.
568 % are |\catcode|'d to 'other'.
570 % The command |\verb| produces in-line verbatim text, where the argument
571 % is delimited by any pair of characters. E.g., |\verb #...#| takes
572 % `|...|' as its argument, and sets it verbatim in |\ttfamily| font.
574 % The *-variants of these commands are the same, except that spaces
575 % print as the \TeX{}book's space character instead of as blank spaces.
577 % \begin{macro}{\@vobeyspaces}
579 {\catcode`\ =\active%
580 \gdef\@vobeyspaces{\catcode`\ \active\let \@xobeysp}}
584 % \begin{macro}{\@xobeysp}
585 % \changes{v1.0z}{1995/07/13}{Use \cs{nobreak}}
586 % \changes{v1.1f}{1996/09/28}{Moved to ltspace.dtx}
590 % \begin{macro}{\@xverbatim}
591 % \begin{macro}{\@sxverbatim}
593 \begingroup \catcode `|=0 \catcode `[= 1
594 \catcode`]=2 \catcode `\{=12 \catcode `\}=12
595 \catcode`\\=12 |gdef|@xverbatim#1\end{verbatim}[#1|end[verbatim]]
596 |gdef|@sxverbatim#1\end{verbatim*}[#1|end[verbatim*]]
602 % \begin{macro}{\@verbatim}
603 % \changes{LaTeX2.09}{1991/07/24}{Added \cs{penalty}\cs{interlinepenalty}
604 % to definition of \cs{par} so that \cs{samepage} works}
605 % \changes{v0.9h}{1993/12/13}{Removed optional argument of \cs{item}}
606 % Real start of verbatim environment
607 % We use |\relax| to prevent |\item| scanning too far.
608 % \changes{v0.9p}{1994/01/18}
609 % {Add \cs{global}\cs{@inlabelfalse}}
610 % \changes{v1.0b}{1994/03/16}
611 % {Remove \cs{global}\cs{@inlabelfalse} again.}
613 \def\@verbatim{\trivlist \item\relax
614 \if@minipage\else\vskip\parskip\fi
615 \leftskip\@totalleftmargin\rightskip\z@skip
616 \parindent\z@\parfillskip\@flushglue\parskip\z@skip
618 % \changes{LaTeX2.09}{1991/08/26}{\cs{@@par} added}
619 % Added |\@@par| to clear possible |\parshape| definition
620 % from a surrounding list (the verbatim guru says).
621 % \changes{v0.9p}{1994/01/18}
622 % {Only add \cs{penalty} if in hmode}
629 % A |\leavevmode| added: needed if, for example, a blank verbatim
630 % line is the first thing in a list item (wow!).
631 % \changes{v1.0f}{1994/04/29}{\cs{leavevmode} added}
633 \leavevmode \null \@@par\penalty\interlinepenalty
636 \ifhmode\@@par\penalty\interlinepenalty\fi
639 % To allow customization we hide the font used in a separate macro.
640 % \changes{v0.9a}{1993/11/21}{use \cs{verbatim@font} instead of \cs{tt}}
641 % \changes{v0.9h}{1993/12/13}{Readded \cs{@noligs}}
642 % \changes{v1.1d}{1996/06/03}{Exchanged the following two code lines
643 % so that \cs{dospecials} cannot reset the category code
644 % of characters handled by \cs{@noligs}.}
645 % \changes{v1.1h}{2000/01/07}{Disable hyphenation even if the font allows it.}
647 \let\do\@makeother \dospecials
648 \obeylines \verbatim@font \@noligs
649 \hyphenchar\font\m@ne
651 % To avoid a breakpoint after the labels box, we remove the penalty
652 % put there by the list macros: another use of |\unpenalty|!
653 % \changes{v1.0f}{1994/04/29}{Change to \cs{everypar} added}
655 \everypar \expandafter{\the\everypar \unpenalty}%
660 % \begin{macro}{\verbatim}
661 % \begin{macro}{\endverbatim}
662 % (RmS 93/09/19) Protected against `missing item' error message
663 % triggered by empty verbatim environment.
665 \def\verbatim{\@verbatim \frenchspacing\@vobeyspaces \@xverbatim}
666 \def\endverbatim{\if@newlist \leavevmode\fi\endtrivlist}
671 % \begin{macro}{\verbatim@font}
672 % \changes{v0.9a}{1993/11/21}{Macro added}
673 % Macro to select the font used for verbatim typesetting.
674 % It also does other work if necessary for the font used.
675 % \changes{v0.9s}{1994/01/21}{Removed unnecessary category code
678 \def\verbatim@font{\normalfont\ttfamily}
683 % \begin{environment}{verbatim*}
685 \@namedef{verbatim*}{\@verbatim\@sxverbatim}
686 \expandafter\let\csname endverbatim*\endcsname =\endverbatim
690 % \begin{macro}{\@makeother}
692 \def\@makeother#1{\catcode`#112\relax}
696 % \begin{macro}{\verb@balance@group}
697 % \changes{LaTeX2.09}{1993/09/07}
698 % {(RmS) Changed definition of \cs{verb} so that it detects a
699 % missing second delimiter.}
701 \let\verb@balance@group\@empty
705 % \begin{macro}{\verb@egroup}
707 \def\verb@egroup{\global\let\verb@balance@group\@empty\egroup}
711 % \begin{macro}{\verb@eol@error}
715 \gdef\verb@eol@error{\obeylines%
716 \def^^M{\verb@egroup\@latex@error{%
717 \noexpand\verb ended by end of line}\@ehc}}%
722 % \begin{macro}{\verb}
723 % \changes{LaTeX2.09}{1992/08/24}
724 % {Changed \cs{verb} and \cs{@sverb} to work correctly
726 % \changes{v0.9a}{1993/11/21}{Use \cs{verbatim@font} instead of
728 % \changes{v1.1a}{1995/09/19}{Put \cs{@noligs} after
729 % \cs{verbatim@font} where it belongs.}
730 % Typesetting a small piece verbatim.
731 % \changes{v1.1d}{1996/06/03}{Put setting of verbatim font after
733 % so that \cs{dospecials} cannot reset the category code
734 % of characters handled by \cs{@noligs}.}
736 \def\verb{\relax\ifmmode\hbox\else\leavevmode\null\fi
738 \verb@eol@error \let\do\@makeother \dospecials
739 \verbatim@font\@noligs
740 \@ifstar\@sverb\@verb}
745 % \begin{macro}{\@sverb}
746 % \changes{v1.0j}{1994/05/10}{Slight change in error message text.}
747 % Definitions of |\@sverb| and |\@verb| changed so |\verb+ foo+|
748 % does not lose leading blanks when it comes at the beginning of a line.
749 % Change made 24 May 89. Suggested by Frank Mittelbach and Rainer
756 \gdef\verb@balance@group{\verb@egroup
757 \@latex@error{\noexpand\verb illegal in command argument}\@ehc}%
758 \aftergroup\verb@balance@group
759 \lowercase{\let~\verb@egroup}}%
763 % \begin{macro}{\@verb}
765 \def\@verb{\@vobeyspaces \frenchspacing \@sverb}
769 % \begin{macro}{\verbatim@nolig@list}
770 % \changes{LaTeX2.09}{1993/09/03}
771 % {Replaced \cs{@noligs} by extensible list}
773 \def\verbatim@nolig@list{\do\`\do\<\do\>\do\,\do\'\do\-}
777 % \begin{macro}{\do@noligs}
783 \lowercase{\endgroup\def~{\leavevmode\kern\z@\char`#1}}}
787 % \begin{macro}{\@noligs}
788 % To stay compatible with packages that use |\@noligs| we keep it.
789 % \changes{v0.9h}{1993/12/13}{Readded \cs{@noligs}}
791 \def\@noligs{\let\do\do@noligs \verbatim@nolig@list}
795 % \changes{v0.9i}{1993/12/16}{\cs{literal} added}
796 % \changes{v1.0r}{1994/05/26/16}{\cs{literal} removed}