path: root/macros/latex-dev/base/ltsect.dtx

% \iffalse meta-comment
%
% Copyright (C) 1993-2024
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
% This file is part of the LaTeX base system.
% -------------------------------------------
%
% It may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%    https://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008 or later.
%
% This file has the LPPL maintenance status "maintained".
%
% The list of all files belonging to the LaTeX base distribution is
% given in the file `manifest.txt'. See also `legal.txt' for additional
% information.
%
% The list of derived (unpacked) files belonging to the distribution
% and covered by LPPL is defined by the unpacking scripts (with
% extension .ins) which are part of the distribution.
%
% \fi
%
% \iffalse
%%% From File: ltsect.dtx
%<*driver>
% \fi
\ProvidesFile{ltsect.dtx}[2024/03/25 v1.1f LaTeX Kernel (Sectioning)]
% \iffalse
\documentclass{ltxdoc}
\GetFileInfo{ltsect.dtx}
\title{\filename}
\date{\filedate}
 \author{%
  Johannes Braams\and
  David Carlisle\and
  Alan Jeffrey\and
  Leslie Lamport\and
  Frank Mittelbach\and
  Chris Rowley\and
  Tobias Oetiker\thanks{Tobi updated
              the comments to `doc' conventions}\and
  Rainer Sch\"opf}

\begin{document}
 \MaintainedByLaTeXTeam{latex}
 \maketitle
 \DocInput{\filename}
\end{document}
%</driver>
% \fi
%
%
% \changes{v1.0o}{1995/05/07}{Use \cs{hb@xt@}}
% \changes{v1.0y}{1996/10/31}{Corrected and tidied documentation;
%                             removed long lines}
%
%
% \section{Sectioning Commands}
%
% This file defines the declarations such as |\author| which are used
% by |\maketitle|. |\maketitle| itself is defined by each class, not
% in the \LaTeX{} kernel.
%
% The second part of the file defines the generic commands used for
% defining sectioning commands such as |\chapter|. Again the actual
% document level commands are defined in the class files, in terms of
% these commands.
%
% \MaybeStop{}
%
%
% \changes{v1.0a}{1994/03/04}{Initial version, split from latex.dtx}
% \changes{v1.0b}{1994/03/28}{Split further from ltherest.dtx}
% \changes{v1.0d}{1994/05/21}{Use new error commands}
% \changes{v1.0f}{1994/10/12}{Doc. typos}
% \changes{v1.0g}{1994/10/18}{Added \cs{normalcolor}}
% \changes{v1.0i}{1994/11/17}
%         {\cs{@tempa} to \cs{reserved@a}}
% \changes{v1.0m}{1995/05/03}{TO: Promoted documentation to doc.sty
%         standard}
% \changes{v1.1d}{2019/08/27}{Make various commands robust}
%
%    \begin{macrocode}
%<*2ekernel>
\message{title,}
%    \end{macrocode}
%
% \subsection{The Title}
%
% \DescribeMacro{\title}
% The user defines the title and  author by the declarations
% |\title|\marg{name},
% \DescribeMacro{\author}
% |\author|\marg{name}
%
% \DescribeMacro{\date}
% Similarly the date is declared with
% |\date|\marg{date}.
%
% \DescribeMacro{\thanks}
% Inside these, the |\thanks|\marg{footnote text} command may be used
% to make acknowledgements, notice of address, etc.\ in a footnote.
% \DescribeMacro{\and}
% If there are multiple authors, they have to be separated with the
% |\and| command.
%
% \DescribeMacro{\maketitle}
% And finally, the |\maketitle| command produces the actual title,
% using the information previously saved with the other commands.
%
%
%
%    \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2019/10/01}%
%<latexrelease>                 {\title}{Make commands robust}%
%    \end{macrocode}
%
%
%  \begin{macro}{\title}
% \changes{LaTeX2e}{1993/12/11}{Added default}
% |\title| for use in |\maketitle|. If not given |\maketitle| will
% produce an error message.
%    \begin{macrocode}
\DeclareRobustCommand\title[1]{\gdef\@title{#1}}
%    \end{macrocode}
%  \end{macro}
%
%
%  \begin{macro}{\author}
% \changes{LaTeX2e}{1993/12/11}{Added default}
% \changes{v1.1e}{2020/07/27}{Don't make the command \cs{long} (gh/354)}
%
%  |\author| for use in |\maketitle|. If not given |\maketitle| will
%  produce a warning message.
%
%    \begin{macrocode}
\DeclareRobustCommand*\author[1]{\gdef\@author{#1}}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\date}
%    |\date| for use in |\maketitle|. If not given |\maketitle| will
%    produce |\today| as the default.
% \changes{v1.1e}{2020/07/27}{Don't make the command \cs{long} (gh/354)}
%    \begin{macrocode}
\DeclareRobustCommand*\date[1]{\gdef\@date{#1}}
%    \end{macrocode}
%  \end{macro}
%
% \changes{1.0h}{1994/11/04}{(ASAJ) Added \cs{protected@xdef} to
%    \cs{thanks}.}
% \begin{macro}{\thanks}
%    \begin{macrocode}
\DeclareRobustCommand\thanks[1]{\footnotemark
    \protected@xdef\@thanks{\@thanks
        \protect\footnotetext[\the\c@footnote]{#1}}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\and}
%    \begin{macrocode}
\DeclareRobustCommand\and{%   % \begin{tabular}
  \end{tabular}%
  \hskip 1em \@plus.17fil%
  \begin{tabular}[t]{c}}%     % \end{tabular}
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</2ekernel|latexrelease>
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{0000/00/00}%
%<latexrelease>                 {\title}{Make commands robust}%
%<latexrelease>
%<latexrelease>\kernel@make@fragile\title
%<latexrelease>\kernel@make@fragile\author
%<latexrelease>\kernel@make@fragile\date
%<latexrelease>\kernel@make@fragile\thanks
%<latexrelease>\kernel@make@fragile\and
%<latexrelease>
%<latexrelease>\EndIncludeInRelease
%<*2ekernel>
%    \end{macrocode}
%
%
%
%  \begin{macro}{\@title}
%    \begin{macrocode}
\def\@title{\@latex@error{No \noexpand\title given}\@ehc}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\@author}
%    \begin{macrocode}
\def\@author{\@latex@warning@no@line{No \noexpand\author given}}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\@date}
%    \begin{macrocode}
\gdef\@date{\today}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\@thanks}
%    \begin{macrocode}
\let\@thanks\@empty
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
\message{sectioning,}
%    \end{macrocode}
% \subsection{Sectioning}
%
%
% \begin{macro}{\@secpenalty}
%    \begin{macrocode}
\newcount\@secpenalty
\@secpenalty = -300
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\if@noskipsec}
% \begin{macro}{\@noskipsectrue}
% \changes{1.0w}{1996/09/29}{Added documentation}
% Way back in 1991 (08/26) FMi \& RmS set the |\@noskipsec| switch
% to true for the preamble and to false in |\document|.
% This was done to trap lists and related text in the preamble but it
% does not catch everything.
%    \begin{macrocode}
\newif\if@noskipsec \@noskipsectrue
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@startsection}
%
% The |\@startsection{|\meta{name}|}{|\meta{level}|}{|%
%       \meta{indent}|}{|\meta{beforeskip}|}|\\
%     |{|\meta{afterskip}|}{|\meta{style}|}*[|\meta{altheading}%
%     |]{|\meta{heading}|}|
% command is the mother of all the user level sectioning commands.
% The part after the |*|, including the |*| is optional.
%
% \begin{description}
% \item[name:] e.g., 'subsection'
% \item[level:] a number, denoting depth of section -- e.g.,
%                  chapter = 0, section = 1, etc.
% \item[indent:] Indentation of heading from left margin
% \item[beforeskip:] Absolute value = skip to leave above the heading.
%                If negative, then paragraph indent of text following
%                heading is suppressed.
% \item[afterskip:] if positive, then skip to leave below heading, else
%                negative of skip to leave to right of run-in heading.
% \item[style:] Commands to set style. Since June 1996 release the
%               \emph{last} command in this argument may be a command
%                such as |\MakeUppercase| or |\fbox| that takes an
%                argument. The section heading will be supplied as the
%                argument to this command. So setting |#6| to, say,
%                |\bfseries\MakeUppercase| would produce bold,
%                uppercase headings.
% \end{description}
%
%  If `|*|' is  missing, then increment the counter.  If it is
%  present, then there should be no |[|\meta{altheading}|]| argument.
%  The command uses the counter 'secnumdepth'. It contains a pointer
%  to the highest section level that is to be numbered.
%
%  \textbf{Warning:}
%  The |\@startsection| command should be at the same or higher
%  grouping level as the text that follows it.  For example, you should
%  \emph{not} do something like
%  \begin{verbatim}
%      \def\foo{ \begingroup ...
%                   \paragraph{...}
%                 \endgroup}
%  \end{verbatim}
%
% Pseudocode for the |\@startsection| command
% \begin{oldcomments}
% \@startsection {NAME}{LEVEL}{INDENT}{BEFORESKIP}{AFTERSKIP}{STYLE} ==
%    BEGIN
%     IF  @noskipsec = T  THEN  \leavevmode  FI
%                              % true if previous section had no body.
%
%     \par
%     \@tempskipa  := BEFORESKIP
%     @afterindent := T
%     IF \@tempskipa < 0  THEN  \@tempskipa  := -\@tempskipa
%                               @afterindent := F
%     FI
%     IF @nobreak = true
%       THEN \everypar == null
%       ELSE \addpenalty{\@secpenalty}
%            \addvspace{\@tempskipa}
%     FI
%     IF * next
%       THEN \@ssect{INDENT}{BEFORESKIP}{AFTERSKIP}{STYLE}
%       ELSE \@dblarg{\@sect
%                {NAME}{LEVEL}{INDENT}
%                {BEFORESKIP}{AFTERSKIP}{STYLE}}
%     FI
% END
% \end{oldcomments}
%
%    \begin{macrocode}
\def\@startsection#1#2#3#4#5#6{%
  \if@noskipsec \leavevmode \fi
  \par
  \@tempskipa #4\relax
  \@afterindenttrue
  \ifdim \@tempskipa <\z@
    \@tempskipa -\@tempskipa \@afterindentfalse
  \fi
  \if@nobreak
    \everypar{}%
  \else
    \addpenalty\@secpenalty\addvspace\@tempskipa
  \fi
  \@ifstar
    {\@ssect{#3}{#4}{#5}{#6}}%
    {\@dblarg{\@sect{#1}{#2}{#3}{#4}{#5}{#6}}}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@sect}
% Pseudocode for the |\@sect| command
% \begin{oldcomments}
% \@sect{NAME}{LEVEL}
%       {INDENT}{BEFORESKIP}{AFTERSKIP}
%       {STYLE}[ARG1]{ARG2}
%           ==
%   BEGIN
%    IF LEVEL > \c@secnumdepth
%      THEN \@svsec :=L null
%      ELSE \refstepcounter{NAME}
%           \@svsec :=L BEGIN \@seccntformat{#1}\relax END
%    FI
%    IF AFTERSKIP > 0
%      THEN \begingroup
%              STYLE
%              \@hangfrom{\hskip INDENT\@svsec}
%              {\interlinepenalty 10000 ARG2\par}
%           \endgroup
%           \NAMEmark{ARG1}
%           \addcontentsline{toc}{NAME}
%              { IF  LEVEL > \c@secnumdepth
%                  ELSE \protect\numberline{\theNAME}  FI
%                ARG1 }
%      ELSE \@svsechd == BEGIN  STYLE
%                               \hskip INDENT\@svsec
%                               ARG2
%                               \NAMEmark{ARG1}
%                               \addcontentsline{toc}{NAME}
%                                  { IF  LEVEL > \c@secnumdepth
%                                      ELSE
%                                        \protect\numberline{\theNAME}
%                                      FI
%                                    ARG1 }
%                        END
%    FI
%    \@xsect{AFTERSKIP}
% END
% \end{oldcomments}
%
% \changes{LaTeX2.09}{1992/08/25}
%         {(FMi) replaced explicit setting of \cs{@svsec}
%               by call to \cs{@seccntformat}}
% \changes{LaTeX2.09}{1993/08/05}
%         {(RmS) Made sure that \cs{protect} works correctly in
%               expansion of \cs{the} counter}
% \changes{1.0h}{1994/11/04}
%         {(ASAJ) Added \cs{protected@edef}.}
%    \begin{macrocode}
\def\@sect#1#2#3#4#5#6[#7]#8{%
  \ifnum #2>\c@secnumdepth
    \let\@svsec\@empty
  \else
    \refstepcounter{#1}%
%    \end{macrocode}
%    Since |\@seccntformat| might end with an improper |\hskip| which
%    is scanning forward for |plus| or |minus| we end the definition
%    of |\@svsec| with |\relax| as a precaution.
% \changes{1.0n}{1995/05/06}{Added \cs{relax} after
%                            \cs{@seccntformat} just in case}
%    \begin{macrocode}
    \protected@edef\@svsec{\@seccntformat{#1}\relax}%
  \fi
  \@tempskipa #5\relax
  \ifdim \@tempskipa>\z@
    \begingroup
%    \end{macrocode}
% \changes{v1.0s}{1996/05/21}
%         {(DPC) Moved brace to allow commands like
%           \cs{MakeUppercase} in 6th argument.
%            Changed \cs{par} to \cs{endgraf} to allow non-long
%            commands. internal/2148}
% \changes{v1.0t}{1996/06/10}
%         {(DPC) Changed \cs{endgraf} to \cs{@@par}}
% This |{| used to be after the argument to |\@hangfrom| but was moved
% here to allow commands such as |\MakeUppercase| to be used at the end
% of |#6|.
%    \begin{macrocode}
      #6{%
        \@hangfrom{\hskip #3\relax\@svsec}%
          \interlinepenalty \@M #8\@@par}%
    \endgroup
    \csname #1mark\endcsname{#7}%
    \addcontentsline{toc}{#1}{%
      \ifnum #2>\c@secnumdepth \else
        \protect\numberline{\csname the#1\endcsname}%
      \fi
      #7}%
  \else
%    \end{macrocode}
% |\relax| added 2 May 90
% \changes{v1.0s}{1996/05/21}
%         {(DPC) Added extra braces for internal/2148}
%    \begin{macrocode}
    \def\@svsechd{%
      #6{\hskip #3\relax
      \@svsec #8}%
      \csname #1mark\endcsname{#7}%
      \addcontentsline{toc}{#1}{%
        \ifnum #2>\c@secnumdepth \else
          \protect\numberline{\csname the#1\endcsname}%
        \fi
        #7}}%
  \fi
  \@xsect{#5}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@xsect}%
% Pseudocode for the |\@xsect| command
% \begin{oldcomments}
% \@xsect{AFTERSKIP} ==
%  BEGIN
%    IF AFTERSKIP > 0
%      THEN \par \nobreak
%           \vskip AFTERSKIP
%           \@afterheading
%      ELSE @nobreak :=G F
%           @noskipsec :=G T
%           \everypar{ IF @noskipsec = T
%                        THEN @noskipsec :=G F
%                             \clubpenalty := 10000 % local
%                             \hskip -\parindent
%                             \begingroup
%                               \@svsechd
%                             \endgroup
%                             \unskip
%                             \hskip -AFTERSKIP \relax
%                                           %% relax added 14 Jan 91
%                        ELSE \clubpenalty := \@clubpenalty % local
%                             \everypar := NULL
%                      FI
%                    }
%    FI
%
%   END
% \end{oldcomments}
%
% \changes{0.0}{1992/08/19}
%     {(RmS) corrected bug: stretch and shrink in argument to
%               \cs{hskip} previously not negated}
%    \begin{macrocode}
\def\@xsect#1{%
  \@tempskipa #1\relax
  \ifdim \@tempskipa>\z@
%    \end{macrocode}
%    Why not combine |\@sect| and |\@xsect| and save doing the
%    same test twice? It is not possible to change this now as these
%    have become hooks!
%
%    This |\par| seems unnecessary.
%    \begin{macrocode}
    \par \nobreak
    \vskip \@tempskipa
    \@afterheading
  \else
%    \end{macrocode}
% \changes{v1.0u}{1996/07/26}{Removed \cs{global} before
%                             \cs{@nobreak...}}
% \changes{v1.0x}{1996/10/23}{Replaced \cs{hskip...} with \cs{setbox...}
%                             as used in \cs{@afterheading}}
%    \begin{macrocode}
    \@nobreakfalse
    \global\@noskipsectrue
    \everypar{%
      \if@noskipsec
        \global\@noskipsecfalse
       {\setbox\z@\lastbox}%
        \clubpenalty\@M
        \begingroup \@svsechd \endgroup
        \unskip
        \@tempskipa #1\relax
        \hskip -\@tempskipa
      \else
        \clubpenalty \@clubpenalty
        \everypar{}%
      \fi}%
  \fi
  \ignorespaces}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@seccntformat}
%    This command formats the section number including the space
%    following it.
% \changes{1.0n}{1995/05/06}{Use \cs{quad} instead of \cs{hskip}}
%    \begin{macrocode}
\def\@seccntformat#1{\csname the#1\endcsname\quad}
%    \end{macrocode}
% \end{macro}
%
% Pseudocode for the |\@ssect| command
% \begin{oldcomments}
% \@ssect{INDENT}{BEFORESKIP}{AFTERSKIP}{STYLE}{ARG} ==
%   BEGIN
%    IF AFTERSKIP > 0
%      THEN \begingroup
%             STYLE
%             \@hangfrom{\hskip INDENT}
%                       {\interlinepenalty 10000 ARG\par}
%           \endgroup
%      ELSE \@svsechd == BEGIN STYLE
%                              \hskip INDENT
%                              ARG
%                        END
%    FI
%    \@xsect{AFTERSKIP}
%   END
% \end{oldcomments}
%
% Pseudocode for the |\@afterheading| command
% \begin{oldcomments}
% \@afterheading ==
%  BEGIN
%    @nobreak :=G true
%    \everypar := BEGIN IF @nobreak = T
%                         THEN @nobreak  :=G false
%                              \clubpenalty := 10000 % local
%                              IF @afterindent = F
%                                THEN remove \lastbox
%                              FI
%                         ELSE \clubpenalty := \@clubpenalty % local
%                              \everypar := NULL
%                      FI
%                 END
%  END
% \end{oldcomments}
%
%
% \begin{macro}{\@ssect}
%    \begin{macrocode}
\def\@ssect#1#2#3#4#5{%
  \@tempskipa #3\relax
  \ifdim \@tempskipa>\z@
    \begingroup
%    \end{macrocode}
% \changes{v1.0s}{1996/05/21}
%         {(DPC) Moved brace to allow commands like
%           \cs{MakeUppercase} in 4th argument.
%            Changed \cs{par} to \cs{endgraf} to allow non-long
%            commands. internal/2148}
% \changes{v1.0t}{1996/06/10}
%         {(DPC) Changed \cs{endgraf} to \cs{@@par}}
% This |{| used to be after the argument to |\@hangfrom| but was moved
% here to allow commands such as |\MakeUppercase| to be used at the end
% of |#4|.
%    \begin{macrocode}
      #4{%
        \@hangfrom{\hskip #1}%
          \interlinepenalty \@M #5\@@par}%
    \endgroup
  \else
%    \end{macrocode}
% \changes{v1.0s}{1996/05/21}
%         {(DPC) Added extra braces for internal/2148}
%    \begin{macrocode}
    \def\@svsechd{#4{\hskip #1\relax #5}}%
  \fi
  \@xsect{#3}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\if@afterindent}
% \begin{macro}{\@afterindenttrue}
%    \begin{macrocode}
\newif\if@afterindent \@afterindenttrue
%    \end{macrocode}
% \end{macro}\end{macro}
%
% \begin{macro}{\@afterheading}
% \changes{v1.0v}{1996/08/02}{Removed \cs{global}
%                             before \cs{@nobreak...}}
%
% This hook is used in setting up custom-built headings in classes.dtx.
%
%    \begin{macrocode}
\def\@afterheading{%
  \@nobreaktrue
  \everypar{%
    \if@nobreak
      \@nobreakfalse
      \clubpenalty \@M
      \if@afterindent \else
        {\setbox\z@\lastbox}%
      \fi
    \else
      \clubpenalty \@clubpenalty
      \everypar{}%
    \fi}}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\@hangfrom}
%
% |\@hangfrom{|\meta{text}|}| : Puts \meta{text} in a box, and makes a
% hanging indentation of the following material up to the first
% |\par|. Should be used in vertical mode.
%
% \changes{v1.0a}{1994/03/07}{(DPC)Extra groups for colour}
%    \begin{macrocode}
\def\@hangfrom#1{\setbox\@tempboxa\hbox{{#1}}%
      \hangindent \wd\@tempboxa\noindent\box\@tempboxa}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\c@secnumdepth}
% \begin{macro}{\c@tocdepth}
%    \begin{macrocode}
\newcount\c@secnumdepth
\newcount\c@tocdepth
%    \end{macrocode}
% \end{macro}\end{macro}
%
% \begin{macro}{\secdef}
%
% |\secdef{|\meta{unstarcmds}|}{|\meta{unstarcmds}|}{|%
%           \meta{starcmds}|}|\\
% When defining a |\chapter| or |\section| command without using
% |\@startsection|, you can use |\secdef| as follows:
% \begin{enumerate}
% \item |\def\chapter{| \ldots  |\secdef|
%                |\|\meta{starcmd} |\|\meta{unstarcmd} |}|
% \item |\def\|\meta{starcmd}|[#1]#2{| \ldots |}|
%            |%| Command to define |\chapter[|\ldots|]{|\ldots|}|
% \item |\def\|\meta{unstarcmd}|#1{| \ldots |}|
%   |%| Command to define |\chapter*{|\ldots|}|
% \end{enumerate}
%
%    \begin{macrocode}
\def\secdef#1#2{\@ifstar{#2}{\@dblarg{#1}}}
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Initializations}
% \begin{macro}{\sectionmark}
% \begin{macro}{\subsectionmark}
% \begin{macro}{\subsubsectionmark}
% \begin{macro}{\paragraphmark}
% \begin{macro}{\subparagraphmark}
% \changes{v1.0q}{1995/10/25}{Use \cs{let} not \cs{def} to save space.}
%    \begin{macrocode}
\let\sectionmark\@gobble
\let\subsectionmark\@gobble
\let\subsubsectionmark\@gobble
\let\paragraphmark\@gobble
\let\subparagraphmark\@gobble
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
%    \begin{macrocode}
\message{contents,}
%    \end{macrocode}
%
% \subsection{Table of Contents etc.}
%
% \subsubsection{Convention}
% |\tf@|\meta{foo} = file number for output for table foo.
%       The file is opened only if |@filesw| = |true|.
%
% \subsubsection{Commands}
%
%
%  A |\l@|\meta{type}|{|\meta{entry}|}{|\meta{page}|}| Macro needs to
%  defined by document style for making an entry of type \meta{type}
%  in a table of contents, etc.  E.g., the document style
%  should define |\l@chapter|, |\l@section|, etc.
%
%  \textbf{Note:} When the |\protect| command is
%  used in the \meta{entry} or \meta{text} of one of the commands
%  below, it causes the following control sequence to be written on
%  the file without being expanded.  The sequence will be expanded
%  when the table of contents entry is processed.
%
%  \textbf{Surprise:} Inside an |\addcontentsline| or |\addtocontents|
%  command argument, the commands: |\index|, |\glossary|,  and |\label|
%  are  no-ops .  This could cause a problem if the user puts an
%  |\index| or |\label| into one of the commands he writes, or into the
%  optional `short version' argument of a |\section| or |\caption|
%  command.
%
% \begin{macro}{\@starttoc}
% The |\@starttoc|\marg{ext} command is used to define the commands:\\
% |\tableofcontents|, |\listoffigures|, etc.
%
% For example:
% |\@starttoc{lof}| is used in |\listoffigures|.  This command
% reads the |.|\meta{ext} file and sets up to write the new
% |.|\meta{ext} file.
%
% \begin{oldcomments}
% \@starttoc{EXT} ==
%   BEGIN
%     \begingroup
%        \makeatletter
%        read file \jobname.EXT
%        IF @filesw = true
%          THEN  open \jobname.EXT as file \tf@EXT
%        FI
%        @nobreak :=G FALSE  %% added 24 May 89
%     \endgroup
%   END
% \end{oldcomments}
%
% \changes{0.0}{1992/01/14}{(RmS) added \cs{immediate} to \cs{openout}
%               as all \cs{write} commands
%               are also executed \cs{immediate}}
% \changes{v1.0u}{1996/07/26}{removed \cs{global}
%                             before \cs{@nobreak...}}
%    \begin{macrocode}
\def\@starttoc#1{%
  \begingroup
    \makeatletter
    \@input{\jobname.#1}%
    \if@filesw
      \expandafter\newwrite\csname tf@#1\endcsname
      \immediate\openout \csname tf@#1\endcsname \jobname.#1\relax
    \fi
    \@nobreakfalse
  \endgroup}
%    \end{macrocode}
% \end{macro}
%
%  \begin{macro}{\addcontentsline}
%  The |\addcontentsline{|\meta{table}|}{|\meta{type}|}{|%
%  \meta{entry}|}| command allows the user to  add
%  his/her own entry to a table of contents, etc. The command adds the
%  entry |\contentsline{|\meta{type}|}{|\meta{entry}|}{|\meta{page}|}{}|
%  to the |.|\meta{table} file.
%
%  This macro is implemented as an application of |\addtocontents|.
%  Note that |\thepage| is not expandable during |\protected@write|
%  therefore one gets the page number at the time of the |\shipout|.
%
% \changes{v1.0c}{1994/05/20}{Correct setting of \cs{protect}.}
% \changes{v1.0j}{1995/04/23}{Use \cs{contentsline} internally.}
% \changes{v1.0h}{1994/11/04}{Added \cs{protected@write} to
%                \cs{addcontentsline}.  ASAJ.}
% \changes{v1.1c}{2018/09/26}{Sometimes mask the endline char when
%    writing to files (github/73)}
% \changes{v1.1e}{2020/10/01}{add a fourth argument for better
%    hyperref compatibility}
%    \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2020/10/01}%
%<latexrelease>                 {\addcontentsline}{fourth argument}%
\def\addcontentsline#1#2#3{%
%    \end{macrocode}
%    We add an empty brace pair at the end of \cs{contentsline}
%    so that the number of argument is identical in documents
%    with and without hyperref.
%    \begin{macrocode}
  \addtocontents{#1}{\protect\contentsline{#2}{#3}{\thepage}{}%
                     \protected@file@percent}}
%</2ekernel|latexrelease>
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{2018/12/01}%
%<latexrelease>                 {\addcontentsline}{Mask line endings}%
%<latexrelease> \def\addcontentsline#1#2#3{%
%<latexrelease>  \addtocontents{#1}{\protect\contentsline{#2}{#3}{\thepage}%
%    \end{macrocode}
%    We add \cs{protected@file@percent} at the end which is turned inside
%   \cs{@writefile} into a percent character to mask the newline after
%   the closing argument brace.
%    \begin{macrocode}
%<latexrelease>            \protected@file@percent}}
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{0000/00/00}%
%<latexrelease>                 {\addcontentsline}{Mask line endings}%
%<latexrelease>\def\addcontentsline#1#2#3{%
%<latexrelease>  \addtocontents{#1}{\protect\contentsline{#2}{#3}{\thepage}}}
%<latexrelease>\EndIncludeInRelease
%<*2ekernel>
%    \end{macrocode}
%  \end{macro}
%
% \changes{v1.0c}{1994/05/20}{Correct setting of \cs{protect}.}
% \changes{v1.0h}{1994/11/04}{Added \cs{protected@write} to
%    \cs{addtocontents}.  ASAJ.}
% \begin{macro}{\addtocontents}
%
%   The |\addtocontents{|\meta{table}|}{|\meta{text}|}| command
%   adds \meta{text} to the |.|\meta{table} file, with no
%   page number.
%
%    \begin{macrocode}
\long\def\addtocontents#1#2{%
  \protected@write\@auxout
      {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
      {\string\@writefile{#1}{#2}}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\contentsline}
% The |\contentsline{|\meta{type}|}{|\meta{entry}|}{|\meta{page}|}{}|
% macro produces a \meta{type} entry in a table of contents, etc.
% It will appear in the |.toc| or other file.
% For example, the entry for subsection 1.4.3 in the table of contents,
% might be produced by:
%
%  \begin{verbatim}
%       \contentsline{subsection}
%           {\numberline{1.4.3}Gnats and Gnus}{22}{}
%  \end{verbatim}
%
%  The |\protect| command causes command sequences to be written
%  without expanding them.
%
%    \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2021/11/15}%
%<latexrelease>                 {\contentsline}{Four arguments}%
%    \end{macrocode}
%
%    In the toc file \cs{contentsline} is followed by 4 arguments
%    these days, but only the first 3 are used in the old
%    interface. The fourth was by default empty and only used when
%    \pkg{hyperref} was loaded. We now pick up all 4 arguments, save
%    the last one away in \cs{@contentsline@destination} and then call
%    the old interface. This is done to simplify the interface to
%    \pkg{hyperref} and to prepare for future changes.
% \changes{v1.1f}{2021/07/28}{Pick up four arguments (gh/633)}
%    \begin{macrocode}
\def\contentsline#1#2#3#4{\gdef\@contentsline@destination{#4}%
                          \csname l@#1\endcsname{#2}{#3}}
%    \end{macrocode}
%    Default definition.
%    \begin{macrocode}
\let\@contentsline@destination\@empty
%    \end{macrocode}
%
%    \begin{macrocode}
%</2ekernel|latexrelease>
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{0000/00/00}%
%<latexrelease>                 {\contentsline}{Four arguments}%
%<latexrelease>
%<latexrelease>\def\contentsline#1{\csname l@#1\endcsname}
%<latexrelease>\let\@contentsline@destination\@undefined
%<latexrelease>\EndIncludeInRelease
%<*2ekernel>
%    \end{macrocode}
% \end{macro}
%
%
%
% |\@dottedtocline{|\meta{level}|}{|\meta{indent}|}{|\meta{numwidth}%
%        |}{|\meta{title}|}{|\meta{page}|}|:
%   Macro to produce a table of contents line with the following
%   parameters:
%   \begin{description}
%   \item[level] If \meta{level} $>$ |\c@tocdepth|, then no line
%                produced.
%   \item[indent] Total indentation from the left margin.
%   \item[numwidth] Width of box for number if the \meta{title} has a
%                |\numberline| command.
%                As of 25 Jan 1988, this is also the amount of extra
%                indentation added to second and later lines of a
%                multiple line entry.
%   \item[title] Contents of entry.
%   \item[page] Page number.
%  \end{description}
%
%  Uses the following parameters, which must be set by the document
%  style. They should be defined with |\def|'s.
%  \begin{description}
%  \item[|\@pnumwidth|]  Width of box in which page number is set.
%  \item[|\@tocrmarg|] Right margin indentation for all but last line
%        of multiple-line entries.
%  \item[|\@dotsep|] Separation between dots, in mu units.
%                  Should be |\def|'d to a number like 2 or 1.7
%  \end{description}
%
% \begin{macro}{\@dottedtocline}
% \changes{LaTeX2.09}{1991/09/29}
%         {(RmS) added \cs{reset@font} for page number}
% \changes{v1.0e}{1994/05/25}{Put braces around argument 4
%          (the actual toc entry) to avoid font (and possibly other)
%           changes leaking out to the leaders.}
% \changes{v1.0g}{1994/10/18}{Added \cs{normalcolor} for page number}
% \changes{v1.0z}{1996/12/20}{Added \cs{nobreak} for latex/2343}
%    \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2018/12/01}%
%<latexrelease>                 {\@dottedtocline}{Prevent protrusion}%
\def\@dottedtocline#1#2#3#4#5{%
  \ifnum #1>\c@tocdepth \else
    \vskip \z@ \@plus.2\p@
    {\leftskip #2\relax \rightskip \@tocrmarg \parfillskip -\rightskip
     \parindent #2\relax\@afterindenttrue
     \interlinepenalty\@M
     \leavevmode
     \@tempdima #3\relax
%    \end{macrocode}
% \changes{v1.0z}{1996/12/20}{Added \cs{nobreak} for latex/2343}
%    \begin{macrocode}
     \advance\leftskip \@tempdima \null\nobreak\hskip -\leftskip
     {#4}\nobreak
     \leaders\hbox{$\m@th
%    \end{macrocode}
%    If a document uses fonts other than computer modern, the use of a
%    dot from math can be very disturbing despite the fact that this
%    might be the only place in a document that then uses computer
%    modern.
%    Therefore we surround the dot with an |\hbox| to escape to the
%    surrounding text font.
% \changes{v1.0k}{1995/04/25}{Added \cs{hbox} around dots.}
% \changes{v1.0l}{1995/05/02}{Don't reset to \cs{rmfamily}}
%    \begin{macrocode}
        \mkern \@dotsep mu\hbox{.}\mkern \@dotsep
        mu$}\hfill
     \nobreak
     \hb@xt@\@pnumwidth{\hfil\normalfont \normalcolor #5%
%    \end{macrocode}
%    We finish off by preventing
%    any protrusion if that is enabled. If protrusion happens the
%    number may shift to the right and as a result you may end up with
%    an additional dot in the toc line in some situations.
% \changes{v1.1b}{2018/09/02}{Prevent protrusion
%     (\url{https://tex.stackexchange.com/q/172785/10109})}
%    \begin{macrocode}
                        \kern-\p@\kern\p@}%
     \par}%
  \fi}
%    \end{macrocode}
% \end{macro}
%
%

%  \begin{macro}{\noprotrusion}
%    This command, if placed directly to the right (or left) of a
%    word, will prevent protrusion of that word into the
%    margin. It is used in the toc entry lines as they shouldn't
%    protrude. It is implemented as to kerns that cancel each other
%    but being there hide the word so that protrusion is not
%    added. Note that a zero kern or an empty box would not work as
%    the protrusion mechanism will skip over those.
%    \begin{macrocode}
\DeclareRobustCommand\noprotrusion{\leavevmode\kern-\p@\kern\p@}
%    \end{macrocode}
%  \end{macro}
%
%
%    \begin{macrocode}
%</2ekernel|latexrelease>
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{0000/00/00}%
%<latexrelease>                 {\@dottedtocline}{Prevent protrusion}%
%<latexrelease>\def\@dottedtocline#1#2#3#4#5{%
%<latexrelease>  \ifnum #1>\c@tocdepth \else
%<latexrelease>    \vskip \z@ \@plus.2\p@
%<latexrelease>    {\leftskip #2\relax \rightskip \@tocrmarg \parfillskip -\rightskip
%<latexrelease>     \parindent #2\relax\@afterindenttrue
%<latexrelease>     \interlinepenalty\@M
%<latexrelease>     \leavevmode
%<latexrelease>     \@tempdima #3\relax
%<latexrelease>     \advance\leftskip \@tempdima \null\nobreak\hskip -\leftskip
%<latexrelease>     {#4}\nobreak
%<latexrelease>     \leaders\hbox{$\m@th
%<latexrelease>        \mkern \@dotsep mu\hbox{.}\mkern \@dotsep
%<latexrelease>        mu$}\hfill
%<latexrelease>     \nobreak
%<latexrelease>     \hb@xt@\@pnumwidth{\hfil\normalfont \normalcolor #5}%
%<latexrelease>     \par}%
%<latexrelease>  \fi}
%<latexrelease>
%<latexrelease>\let\noprotrusion\@undefined
%<latexrelease>\EndIncludeInRelease
%<*2ekernel>
%    \end{macrocode}
%
%
%
% \textbf{Note:} |\nobreak|'s added 7 Jan 86 to prevent bad line break
% that left the page number dangling by itself at left edge of a new
% line.
%
% Changed 25 Jan 88 to use |\leftskip| instead of |\hangindent| so
% leaders of multiple-line contents entries would line up properly.
% \begin{macro}{\numberline}
% |\numberline{|\meta{number}|}|: For use in a |\contentsline| command.
%   It puts \meta{number} flushleft in a box of width |\@tempdima|
%   (Before 25
%   Jan 88 change, it also added |\@tempdima| to the hanging
%   indentation.)
%
%    \begin{macrocode}
\def\numberline#1{\hb@xt@\@tempdima{#1\hfil}}
%</2ekernel>
%    \end{macrocode}
% \end{macro}
%
% \Finale
%