Previous: , Up: Sectioning   [Contents][Index]

6.8 \@startsection: Typesetting sectional unit headings

Synopsis: 

\@startsection{name}{level}{indent}{beforeskip}{afterskip}{style}

Used to help redefine the behavior of commands that start sectioning divisions such as \section or \subsection.

The titlesec package makes manipulation of sectioning easier. Further, while most requirements for sectioning commands can be satisfied with \@startsection, some cannot. For instance, in the standard LaTeX book and report classes the commands \chapter and \report are not constructed using this. To make such a command you may want to use the \secdef command.

The \@startsection macro is used like this: 

\@startsection{name}
  {level}
  {indent}
  {beforeskip}
  {afterskip}
  {style}*[toctitle]{title}

so that issuing 

\renewcommand{\section}{\@startsection{name}
  {level}
  {indent}
  {beforeskip}
  {afterskip}
  {style}}

redefines \section while keeping its standard calling form \section*[toctitle]{title} (in which, as a reminder, the star * is optional). See Sectioning. This implies that when you write a command like \renewcommand{\section}{...}, the \@startsection{...} must come last in the definition. See the examples below.

name

Name of the counter used to number the sectioning header. This counter must be defined separately. Most commonly this is either section, subsection, or paragraph. Although in those cases the counter name is the same as the sectioning command itself, you don’t have to use the same name.

Then \thename displays the title number and \namemark is for the page headers. See the third example below.

level

An integer giving the depth of the sectioning command. See Sectioning, for the list of standard level numbers.

If level is less than or equal to the value of the counter secnumdepth then titles for this sectioning command will be numbered (see Sectioning/secnumdepth). For instance, if secnumdepth is 1 in an article then the command \section{Introduction} will produce output like “1 Introduction” while \subsection{Discussion} will produce output like “Discussion”, without the number prefix.

If level is less than or equal to the value of the counter tocdepth then the table of contents will have an entry for this sectioning unit (see Sectioning/tocdepth). For instance, in an article, if tocdepth is 1 then the table of contents will list sections but not subsections.

indent

A length giving the indentation of all of the title lines with respect to the left margin. To have the title flush with the margin use 0pt. A negative indentation such as -\parindent will move the title into the left margin.

beforeskip

The absolute value of this length is the amount of vertical space that is inserted before this sectioning unit’s title. This space will be discarded if the sectioning unit happens to start at the beginning of a page. If this number is negative then the first paragraph following the header is not indented; if it is non-negative then the first paragraph is indented. (Example: the negative of 1pt plus 2pt minus 3pt is -1pt plus -2pt minus -3pt.)

For example, if beforeskip is -3.5ex plus -1ex minus -0.2ex then to start the new sectioning unit, LaTeX will add about 3.5 times the height of a letter x in vertical space, and the first paragraph in the section will not be indented. Using a rubber length, with plus and minus, is good practice here since it gives LaTeX more flexibility in making up the page (see Lengths).

The full accounting of the vertical space between the baseline of the line prior to this sectioning unit’s header and the baseline of the header is that it is the sum of the \parskip of the text font, the \baselineskip of the title font, and the absolute value of the beforeskip. This space is typically rubber so it may stretch or shrink. (If the sectioning unit starts on a fresh page so that the vertical space is discarded then the baseline of the header text will be where LaTeX would put the baseline of the first text line on that page.)

afterskip

This is a length. If afterskip is non-negative then this is the vertical space inserted after the sectioning unit’s title header. If it is negative then the title header becomes a run-in header, so that it becomes part of the next paragraph. In this case the absolute value of the length gives the horizontal space between the end of the title and the beginning of the following paragraph. (Note that the negative of 1pt plus 2pt minus 3pt is -1pt plus -2pt minus -3pt.)

As with beforeskip, using a rubber length, with plus and minus components, is good practice here since it gives LaTeX more flexibility in putting together the page.

If afterskip is non-negative then the full accounting of the vertical space between the baseline of the sectioning unit’s header and the baseline of the first line of the following paragraph is that it is the sum of the \parskip of the title font, the \baselineskip of the text font, and the value of after. That space is typically rubber so it may stretch or shrink. (Note that because the sign of afterskip changes the sectioning unit header’s from standalone to run-in, you cannot use a negative afterskip to cancel part of the \parskip.)

style

Controls the styling of the title. See the examples below. Typical commands to use here are \centering, \raggedright, \normalfont, \hrule, or \newpage. The last command in style may be one that takes one argument, such as \MakeUppercase or \fbox that takes one argument. The section title will be supplied as the argument to this command. For instance, setting style to \bfseries\MakeUppercase would produce titles that are bold and uppercase.

These are LaTeX’s defaults for the first three sectioning units that are defined with \@startsection, for the article, book, and report classes.

Some examples follow. These go either in a package or class file or in the preamble of a LaTeX document. If you put them in the preamble they must go between a \makeatletter command and a \makeatother. (Probably the error message You can't use `\spacefactor' in vertical mode. means that you forgot this.) See \makeatletter & \makeatother.

This will put section titles in large boldface type, centered. It says \renewcommand because LaTeX’s standard classes have already defined a \section. For the same reason it does not define a section counter, or the commands \thesection and \l@section. 

\renewcommand\section{%
  \@startsection{section}% name
    {1}% level
    {0pt}% indent
    {-3.5ex plus -1ex minus -.2ex}% beforeskip
    {2.3ex plus.2ex}% afterskip
    {\centering\normalfont\Large\bfseries}% style
  }

This will put subsection titles in small caps type, inline with the paragraph. 

\renewcommand\subsection{%
  \@startsection{subsection}%  name
    {2}% level
    {0em}% indent
    {-1ex plus 0.1ex minus -0.05ex}% beforeskip
    {-1em plus 0.2em}% afterskip
    {\scshape}% style
  }

The prior examples redefined existing sectional unit title commands. This defines a new one, illustrating the needed counter and macros to display that counter. 

\setcounter{secnumdepth}{6}% show counters this far down
\newcounter{subsubparagraph}[subparagraph]% counter for numbering
\renewcommand{\thesubsubparagraph}%               how to display 
  {\thesubparagraph.\@arabic\c@subsubparagraph}%  numbering
\newcommand{\subsubparagraph}{\@startsection
                         {subsubparagraph}%
                         {6}%
                         {0em}%
                         {\baselineskip}%
                         {0.5\baselineskip}%
                         {\normalfont\normalsize}}
\newcommand*\l@subsubparagraph{\@dottedtocline{6}{10em}{5em}}% for toc
\newcommand{\subsubparagraphmark}[1]{}% for page headers
Unofficial LaTeX2e reference manual