ltsect.dtx

Johannes Braams  David Carlisle  Alan Jeffrey
Leslie Lamport  Frank Mittelbach  Chris Rowley
Tobias Oetiker^{∗}  Rainer Schöpf

1995/11/28

1 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 L^{A}TEX 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.

1 ⟨∗2ekernel⟩

 2 \message{title,}

1.1 The Title

\title The user defines the title and author by the declarations \title{⟨name⟩},

\author  \author{⟨name⟩}

\date Similarly the date is declared with \date{⟨date⟩}. \thanks Inside these, the \thanks{⟨footnote text⟩} command may be used to make

\and acknowledgements, notice of address, etc. in a footnote. If there are multiple

authors, they have to be separated with the \and command.

\maketitle And finally, the \maketitle command produces the actual title, using the information previously saved with the other commands.

\title \@title  \title for use in \maketitle. If not given \maketitle will produce an error

message.

 3 \def\title#1{\gdef\@title{#1}}
 4 \def\@title{\@latex@error{No \noexpand\title given}\@ehc}
\author \@author  \author for use in \maketitle. If not given \maketitle will produce a warning

message.

 5 \def\author#1{\gdef\@author{#1}}
 6 \def\@author{\@latex@warning@no@line{No \noexpand\author given}}

∗Tobi updated the comments to ‘doc’ conventions

\date \@date  \date for use in \maketitle. If not given \maketitle will produce \today as the

default.

 7 \def\date#1{\gdef\@date{#1}}
 8 \gdef\@date{\today}
\thanks
 9 \def\thanks#1{\footnotemark
10  \protected@xdef\@thanks{\@thanks
11  \protect\footnotetext[\the\c@footnote]{#1}}%

12 }

\@thanks
13 \let\@thanks\@empty
\and
14 \def\and{%%                             % \begin{tabular}
15 \end{tabular}\hskip 1em \@plus.17fil%
16 \begin{tabular}[t]{c}%% \end{tabular}

17 }

18 \message{sectioning,}

1.2 Sectioning

\@secpenalty
19 \newcount\@secpenalty
20 \@secpenalty = -300
\if@noskipsec
\@noskipsectrue
21 \newif\if@noskipsec \@noskipsectrue
\@startsection The \@startsection{⟨name⟩}{⟨level⟩}{ ⟨indent⟩}{⟨beforeskip⟩}

{⟨afterskip⟩}{⟨style⟩}*[⟨altheading⟩ ]{⟨heading⟩} command is the mother of all the user level sectioning commands. The part after the *, including the * is optional.

name: e.g., ’subsection’

level: a number, denoting depth of section – e.g., chapter=1, section = 2, etc.

indent: Indentation of heading from left margin

beforeskip: Absolute value = skip to leave above the heading. If negative, then paragraph indent of text following heading is suppressed.

afterskip: if positive, then skip to leave below heading, else negative of skip to leave to right of run-in heading.

style: commands to set style

If ‘*’ is missing, then increment the counter. If it is present, then there should be no [⟨altheading⟩] argument. The command uses the counter ’secnumdepth’. It contains a pointer to the highest section level that is to be numbered.

Warning: The \@startsection command should be at the same or higher grouping level as the text that follows it. For example, you should not do something like

\def\foo{ \begingroup ...
             \paragraph{...}
           \endgroup}

Pseudocode for the \@startsection command

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

22 \def\@startsection#1#2#3#4#5#6{\if@noskipsec \leavevmode \fi
23 \par \@tempskipa #4\relax
24 \@afterindenttrue
25 \ifdim \@tempskipa <\z@
26  \@tempskipa -\@tempskipa \@afterindentfalse
27 \fi
28 \if@nobreak \everypar{}\else
29  \addpenalty\@secpenalty\addvspace\@tempskipa
30 \fi
31 \@ifstar

32  {\@ssect{#3}{#4}{#5}{#6}}%
33  {\@dblarg{\@sect{#1}{#2}{#3}{#4}{#5}{#6}}}}

\@sect Pseudocode for the \@sect command

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

34 \def\@sect#1#2#3#4#5#6[#7]#8{%
35  \ifnum #2>\c@secnumdepth
36  \let\@svsec\@empty\else
37  \refstepcounter{#1}%

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.

38  \protected@edef\@svsec{\@seccntformat{#1}\relax}%
39  \fi
40  \@tempskipa #5\relax
41  \ifdim \@tempskipa>\z@
42  \begingroup #6\relax
43  \@hangfrom{\hskip #3\relax\@svsec}%
44  {\interlinepenalty \@M #8\par}%
45  \endgroup
46  \csname #1mark\endcsname{#7}\addcontentsline
47  {toc}{#1}{\ifnum #2>\c@secnumdepth \else
48  \protect\numberline{\csname the#1\endcsname}\fi
49  #7}\else
50  \def\@svsechd{#6\hskip #3\relax  %% \relax added 2 May 90
51  \@svsec #8\csname #1mark\endcsname
52  {#7}\addcontentsline
53  {toc}{#1}{\ifnum #2>\c@secnumdepth \else
54  \protect\numberline{\csname the#1\endcsname}%
55  \fi
56  #7}}\fi
57  \@xsect{#5}}

\@xsect Pseudocode for the \@xsect command \@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 :=G 10000
                             \hskip -\parindent
                             \begingroup
                               \@svsechd
                             \endgroup
                             \unskip
                             \hskip -AFTERSKIP \relax

%% relax added 14 Jan 91

                        ELSE \clubpenalty :=G \@clubpenalty
                             \everypar := NULL

FI

                    }

FI

END

58 \def\@xsect#1{\@tempskipa #1\relax
59  \ifdim \@tempskipa>\z@
60  \par \nobreak
61  \vskip \@tempskipa
62  \@afterheading
63  \else \global\@nobreakfalse \global\@noskipsectrue
64  \everypar{\if@noskipsec \global\@noskipsecfalse
65  \clubpenalty\@M \hskip -\parindent
66  \begingroup \@svsechd \endgroup \unskip
67  \@tempskipa #1\relax
68  \hskip -\@tempskipa
69  \else \clubpenalty \@clubpenalty
70  \everypar{}\fi}\fi\ignorespaces}

\@seccntformat This command formats the section number including the space following it.

71 \def\@seccntformat#1{\csname the#1\endcsname\quad}

Pseudocode for the \@ssect command \@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 Pseudocode for the \@afterheading command

\@afterheading ==

BEGIN @nobreak :=G true \everypar := BEGIN IF @nobreak = T

THEN @nobreak :=G false

                           \clubpenalty :=G 10000

IF @afterindent = F

THEN remove \lastbox FI

                      ELSE \clubpenalty :=G \@clubpenalty

                               \everypar := NULL

FI END

END

\@ssect
72 \def\@ssect#1#2#3#4#5{\@tempskipa #3\relax
73 \ifdim \@tempskipa>\z@
74  \begingroup #4\@hangfrom{\hskip #1}{\interlinepenalty \@M #5\par}%
75  \endgroup
76 \else \def\@svsechd{#4\hskip #1\relax #5}\fi
77  \@xsect{#3}}
\if@afterindent
\@afterindenttrue
78 \newif\if@afterindent \@afterindenttrue
\@afterheading
79 \def\@afterheading{\global\@nobreaktrue
80  \everypar{\if@nobreak
81  \global\@nobreakfalse
82  \clubpenalty \@M
83  \if@afterindent \else {\setbox\z@\lastbox}\fi
84  \else \clubpenalty \@clubpenalty
85  \everypar{}\fi}}

\@hangfrom \@hangfrom{⟨text⟩} : Puts ⟨text⟩ in a box, and makes a hanging indentation of the following material up to the first \par. Should be used in vertical mode.

86 \def\@hangfrom#1{\setbox\@tempboxa\hbox{{#1}}%
87  \hangindent \wd\@tempboxa\noindent\box\@tempboxa}
\c@secnumdepth
\c@tocdepth
88 \newcount\c@secnumdepth
89 \newcount\c@tocdepth

\secdef \secdef{⟨unstarcmds⟩}{⟨unstarcmds⟩}{ ⟨starcmds⟩} When defining a \chapter or \section command without using \@startsection, you can use \secdef as follows:

1. \def\chapter{ … \secdef \⟨starcmd⟩ \⟨unstarcmd⟩ }

2. \def\⟨starcmd⟩[#1]#2{ … } % Command to define \chapter[…]{… }

3. \def\⟨unstarcmd⟩#1{ … } % Command to define \chapter*{… }

90 \def\secdef#1#2{\@ifstar{#2}{\@dblarg{#1}}}

1.2.1 Initializations

\sectionmark
\subsectionmark
\subsubsectionmark
\paragraphmark
\subparagraphmark

91 \let\sectionmark\@gobble
92 \let\subsectionmark\@gobble
93 \let\subsubsectionmark\@gobble
94 \let\paragraphmark\@gobble
95 \let\subparagraphmark\@gobble
96 \message{contents,}

1.3 Table of Contents etc.

1.3.1 Convention

\tf@⟨foo⟩ = file number for output for table foo. The file is opened only if @filesw

= true.

1.3.2 Commands

A \l@⟨type⟩{⟨entry⟩}{⟨page⟩} Macro needs to defined by document style for making an entry of type ⟨type⟩ in a table of contents, etc. E.g., the document style

should define \l@chapter, \l@section, etc.

Note: When the \protect command is used in the ⟨entry⟩ or ⟨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.

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.

\@starttoc The \@starttoc{⟨ext⟩} command is used to define the commands:

\tableofcontents, \listoffigures, etc.

For example: \@starttoc{lof} is used in \listoffigures. This command reads the .⟨ext⟩ file and sets up to write the new .⟨ext⟩ file.

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

97 \def\@starttoc#1{\begingroup
98 \makeatletter
99 \@input{\jobname.#1}\if@filesw
100 \expandafter\newwrite\csname tf@#1\endcsname
101  \immediate\openout
102  \csname tf@#1\endcsname \jobname.#1\relax
103 \fi \global\@nobreakfalse \endgroup}

\addcontentsline The \addcontentsline{⟨table⟩}{⟨type⟩}{ ⟨entry⟩} command allows the user to add his/her own entry to a table of contents, etc. The command adds the entry \contentsline{⟨type⟩}{⟨entry⟩}{⟨page⟩} to the .⟨table⟩ file.

This macro is implemented as an aplication of \addtocontents. Note that \thepage is not expandable during \protected@write therefore one gets the page number at the time of the \shipout.

104 \def\addcontentsline#1#2#3{%
105 \addtocontents{#1}{\protect\contentsline{#2}{#3}{\thepage}}%

106 }

\addtocontents The \addtocontents{⟨table⟩}{⟨text⟩} command adds ⟨text⟩ to the .⟨table⟩ file, with no page number.

107 \long\def\addtocontents#1#2{%
108 \protected@write\@auxout
109  {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
110  {\string\@writefile{#1}{#2}}%

111 }

\contentsline The \contentsline{⟨type⟩}{⟨entry⟩}{⟨page⟩} macro produces a ⟨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 for example, might be produced by:

       \contentsline{subsection}
           {\makebox{30pt}[r]{1.4.3} Gnats and Gnus}{22}

The \protect command causes command sequences to be written without expanding them.

112 \def\contentsline#1{\csname l@#1\endcsname}

\@dottedtocline{⟨level⟩}{⟨indent⟩}{⟨numwidth⟩ }{⟨title⟩}{⟨page⟩}: Macro to produce a table of contents line with the following parameters:

level If ⟨level⟩ > \c@tocdepth, then no line produced.

indent Total indentation from the left margin. numwidth Width of box for number if the ⟨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.

title Contents of entry.

page Page number.

Uses the following parameters, which must be set by the document style. They should be defined with \def’s.

pnumwidth Width of box in which page number is set.

tocrmarg Right margin indentation for all but last line of multiple-line entries.

dotsep Separation between dots, in mu units. Should be \def’d to a number like 2 or 1.7

\@dottedtocline
113 \def\@dottedtocline#1#2#3#4#5{\ifnum #1>\c@tocdepth \else
114 \vskip \z@ \@plus.2\p@
115 {\leftskip #2\relax \rightskip \@tocrmarg \parfillskip -\rightskip
116  \parindent #2\relax\@afterindenttrue
117 \interlinepenalty\@M
118 \leavevmode
119 \@tempdima #3\relax
120 \advance\leftskip \@tempdima \null\hskip -\leftskip
121  {#4}\nobreak\leaders\hbox{$\m@th

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.

122  \mkern \@dotsep mu\hbox{.}\mkern \@dotsep
123  mu$}\hfill \nobreak
124  \hb@xt@\@pnumwidth{%
125  \hfil\normalfont \normalcolor #5}\par}\fi}

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.

\numberline  \numberline{⟨number⟩}: For use in a \contentsline command. It puts

⟨number⟩ flushleft in a box of width \@tempdima (Before 25 Jan 88 change, it also added \@tempdima to the hanging indentation.)

126 \def\numberline#1{\hb@xt@\@tempdima{#1\hfil}}

127 ⟨/2ekernel⟩