Document classes (LaTeX2e unofficial reference manual (October 2018))

## Document classes

The document’s overall class is defined with this command, which is normally the first command in a LaTeX source file.

    \documentclass[options]{class}

The following document class names are built into LaTeX. (Many other document classes are available as separate packages; see Overview.)

`article`

  For a journal article, a presentation, and miscellaneous general use.

`book`

  Full-length books, including chapters and possibly including front matter, such as a preface, and back matter, such as an appendix (see Front/back matter).

`letter`

  Mail, optionally including mailing labels (see Letters).

`report`

  For documents of length between an `article` and a `book`, such as technical reports or theses, which may contain several chapters.

`slides`

  For slide presentations—rarely used today. In its place the `beamer` package is perhaps the most prevalent (see beamer template).

Standard options are described in the next section.

### Document class options

You can specify global options or class options to the `\documentclass` command by enclosing them in square brackets. To specify more than one option, separate them with a comma.

    \documentclass[option1,option2,...]{class}

Here is the list of the standard class options.

All of the standard classes except `slides` accept the following options for selecting the typeface size (default is `10pt`):

    10pt  11pt  12pt

All of the standard classes accept these options for selecting the paper size (these show height by width):

`a4paper`

  210 by 297mm (about 8.25 by 11.75 inches)

`a5paper`

  148 by 210mm (about 5.8 by 8.3 inches)

`b5paper`

  176 by 250mm (about 6.9 by 9.8 inches)

`executivepaper`

  7.25 by 10.5 inches

`legalpaper`

  8.5 by 14 inches

`letterpaper`

  8.5 by 11 inches (the default)

When using one of the engines pdfLaTeX, LuaLaTeX, or XeLaTeX (see TeX engines), options other than `letterpaper` set the print area but you must also set the physical paper size. One way to do that is to put `\pdfpagewidth=\paperwidth` and `\pdfpageheight=\paperheight` in your document’s preamble.

The `geometry` package provides flexible ways of setting the print area and physical page size.

Miscellaneous other options:

`draft`
`final`

  Mark (`draft`) or do not mark (`final`) overfull boxes with a black box in the margin; default is `final`.

`fleqn`

  Put displayed formulas flush left; default is centered.

`landscape`

  Selects landscape format; default is portrait.

`leqno`

  Put equation numbers on the left side of equations; default is the right side.

`openbib`

  Use “open” bibliography format.

`titlepage`
`notitlepage`

  Specifies whether there is a separate page for the title information and for the abstract also, if there is one. The default for the `report` class is `titlepage`, for the other classes it is `notitlepage`.

The following options are not available with the `slides` class.

`onecolumn`
`twocolumn`

  Typeset in one or two columns; default is `onecolumn`.

`oneside`
`twoside`

  Selects one- or two-sided layout; default is `oneside`, except that in the `book` class the default is `twoside`.

  For one-sided printing, the text is centered on the page. For two-sided printing, the `\evensidemargin` (`\oddsidemargin`) parameter determines the distance on even (odd) numbered pages between the left side of the page and the text’s left margin, with `\oddsidemargin` being 40% of the difference between `\paperwidth` and `\textwidth`, and `\evensidemargin` is the remainder.

`openright`
`openany`

  Determines if a chapter should start on a right-hand page; default is `openright` for `book`, and `openany` for `report`.

The `slides` class offers the option `clock` for printing the time at the bottom of each note.

### Additional packages

Load a package pkg, with the package options given in the comma-separated list options, as here.

    \usepackage[options]{pkg}.

To specify more than one package you can separate them with a comma, as in `\usepackage{pkg1,pkg2,...}`, or use multiple `\usepackage` commands.

Any options given in the `\documentclass` command that are unknown to the selected document class are passed on to the packages loaded with `\usepackage`.

### Class and package construction

You can create new document classes and new packages. For instance, if your memos must satisfy some local requirements, such as a standard header for each page, then you could create a new class `smcmemo.cls` and begin your documents with `\documentclass{smcmemo}`.

What separates a package from a document class is that the commands in a package are useful across classes while those in a document class are specific to that class. Thus, a command to set page headers is for a package while a command to make the page headers say `Memo from the SMC Math Department` is for a class.

Inside of a class or package file you can use the at-sign `@` as a character in command names without having to surround the code containing that command with `\makeatletter` and `\makeatother`. See \makeatletter & \makeatother. This allow you to create commands that users will not accidentally redefine. Another technique is to preface class- or package-specific commands with some string to prevent your class or package from interfering with others. For instance, the class `smcmemo` might have commands `\smc@tolist`, `\smc@fromlist`, etc.

#### Class and package structure

A class file or package file typically has four parts.

1. In the identification part, the file says that it is a LaTeX package or class and describes itself, using the `\NeedsTeXFormat` and `\ProvidesClass` or `\ProvidesPackage` commands.
2. The preliminary declarations part declares some commands and can also load other files. Usually these commands will be those needed for the code used in the next part. For example, an `smcmemo` class might be called with an option to read in a file with a list of people for the to-head, as `\documentclass[mathto]{smcmemo}`, and therefore needs to define a command `\newcommand{\setto}[1]{\def\@tolist{#1}}` used in that file.
3. In the handle options part the class or package declares and processes its options. Class options allow a user to start their document as `\documentclass[option list]{class name}`, to modify the behavior of the class. An example is when you declare `\documentclass[11pt]{article}` to set the default document font size.
4. Finally, in the more declarations part the class or package usually does most of its work: declaring new variables, commands and fonts, and loading other files.

Here is a starting class file, which should be saved as `stub.cls` where LaTeX can find it, for example in the same directory as the `.tex` file.

    \NeedsTeXFormat{LaTeX2e}
    \ProvidesClass{stub}[2017/07/06 stub to start building classes from]
    \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
    \ProcessOptions\relax
    \LoadClass{article}

It identifies itself, handles the class options via the default of passing them all to the `article` class, and then loads the `article` class to provide the basis for this class’s code.

For more, see the official guide for class and package writers, the Class Guide, at http://www.latex-project.org/help/documentation/clsguide.pdf (much of the descriptions here derive from this document), or the tutorial https://www.tug.org/TUGboat/tb26-3/tb84heff.pdf.

#### Class and package commands

These are the commands designed to help writers of classes or packages.

`\AtBeginDvi{specials}`

  Save in a box register things that are written to the `.dvi` file at the beginning of the shipout of the first page of the document.

`\AtEndOfClass{code}`
`\AtEndOfPackage{code}`

  Hook to insert code to be executed when LaTeX finishes processing the current class or package. You can use these hooks multiple times; the `code` will be executed in the order that you called it. See also \AtBeginDocument.

`\CheckCommand{cmd}[num][default]{definition}`
`\CheckCommand*{cmd}[num][default]{definition}`

  Like `\newcommand` (see \newcommand & \renewcommand) but does not define cmd; instead it checks that the current definition of cmd is exactly as given by definition and is or is not long as expected. A long command is a command that accepts `\par` within an argument. The cmd command is expected to be long with the unstarred version of `\CheckCommand`. Raises an error when the check fails. This allows you to check before you start redefining `cmd` yourself that no other package has already redefined this command.

`\ClassError{class name}{error text}{help text}`
`\PackageError{package name}{error text}{help text}`
`\ClassWarning{class name}{warning text}`
`\PackageWarning{package name}{warning text}`
`\ClassWarningNoLine{class name}{warning text}`
`\PackageWarningNoLine{package name}{warning text}`
`\ClassInfo{class name}{info text}`
`\PackageInfo{package name}{info text}`
`\ClassInfoNoLine{class name}{info text}`
`\PackageInfoNoLine{package name}{info text}`

  Produce an error message, or warning or informational messages.

  For `\ClassError` and `\PackageError` the message is error text, followed by TeX’s `?` error prompt. If the user then asks for help by typing `h`, they see the help text.

  The four warning commands are similar except that they write warning text on the screen with no error prompt. The four info commands write info text only in the transcript file. The `NoLine` versions do not show the number of the line generating the message, while the other versions do show that number.

  To format the messages, including the help text: use `\protect` to stop a command from expanding, get a line break with `\MessageBreak`, and get a space with `\space` when a space character does not allow it, like after a command. Note that LaTeX appends a period to the messages.

`\CurrentOption`

  Expands to the name of the currently-being-processed option. Can only be used within the code argument of either `\DeclareOption` or `\DeclareOption*`.

`\DeclareOption{option}{code}`
`\DeclareOption*{code}`

  Make an option available to a user to invoke in their `\documentclass` command. For example, the `smcmemo` class could have an option `\documentclass[logo]{smcmemo}` allowing users to put the institutional logo on the first page. The class file must contain `\DeclareOption{logo}{code}` (and later, `\ProcessOptions`).

  If you request an option that has not been declared, by default this will produce a warning like `Unused global option(s): [badoption].` Change this behaviour with the starred version `\DeclareOption*{code}`. For example, many classes extend an existing class, using a declaration such as `\LoadClass{article}`, and for passing extra options to the underlying class use code such as this.

      \DeclareOption*{%
      \PassOptionsToClass{\CurrentOption}{article}%
      }

  Another example is that the class `smcmemo` may allow users to keep lists of memo recipients in external files. Then the user could invoke `\documentclass[math]{smcmemo}` and it will read the file `math.memo`. This code handles the file if it exists and otherwise passes the option to the `article` class.

      \DeclareOption*{\InputIfFileExists{\CurrentOption.memo}{}{%
          \PassOptionsToClass{\CurrentOption}{article}}}

`\DeclareRobustCommand{cmd}[num][default]{definition}`
`\DeclareRobustCommand*{cmd}[num][default]{definition}`

  Like `\newcommand` and `\newcommand*` (see \newcommand & \renewcommand) but these declare a robust command, even if some code within the definition is fragile. (For a discussion of robust and fragile commands see \protect.) Use this command to define new robust commands or to redefine existing commands and make them robust. Unlike `\newcommand` these do not give an error if macro cmd already exists; instead, a log message is put into the transcript file if a command is redefined.

  Commands defined this way are a bit less efficient than those defined using `\newcommand` so unless the command’s data is fragile and the command is used within a moving argument, use `\newcommand`.

  The `etoolbox` package offers the commands `\newrobustcmd`, `\newrobustcmd*`, as well as the commands `\renewrobustcmd`, `\renewrobustcmd*`, and the commands `\providerobustcmd`, and `\providerobustcmd*`. These are similar to `\newcommand`, `\newcommand*`, `\renewcommand`, `\renewcommand*`, `\providecommand`, and `\providecommand*`, but define a robust cmd with two advantages as compared to `\DeclareRobustCommand`:

  1. They use the low-level e-TeX protection mechanism rather than the higher level LaTeX `\protect` mechanism, so they do not incur the slight loss of performance mentioned above, and
  2. They make the same distinction between `\new…`, `\renew…`, and `\provide…`, as the standard commands, so they do not just make a log message when you redefine cmd that already exists, in that case you need to use either `\renew…` or `\provide…` or you get an error.
`\IfFileExists{file name}{true code}{false code}`
`\InputIfFileExists{file name}{true code}{false code}`

  Execute true code if LaTeX finds the file `file name` or false code otherwise. In the first case it executing true code and then inputs the file. Thus the command

      \IfFileExists{img.pdf}{%
        \includegraphics{img.pdf}}{\typeout{!! img.pdf not found}

  will include the graphic `img.pdf` if it is found and otherwise give a warning.

  This command looks for the file in all search paths that LaTeX uses, not only in the current directory. To look only in the current directory do something like `\IfFileExists{./filename}{true code}{false code}`. If you ask for a filename without a `.tex` extension then LaTeX will first look for the file by appending the `.tex`; for more on how LaTeX handles file extensions see \input.

`\LoadClass[options list]{class name}[release date]`
`\LoadClassWithOptions{class name}[release date]`

  Load a class, as with `\documentclass[options list]{class name}[release info]`. An example is `\LoadClass[twoside]{article}`.

  The options list, if present, is a comma-separated list. The release date is optional. If present it must have the form YYYY/MM/DD.

  If you request a release date and the date of the package installed on your system is earlier, then you get a warning on the screen and in the log like this.

      You have requested, on input line 4, version `2038/01/19' of
      document class article, but only version `2014/09/29 v1.4h
      Standard LaTeX document class' is available.

  The command version `\LoadClassWithOptions` uses the list of options for the current class. This means it ignores any options passed to it via `\PassOptionsToClass`. This is a convenience command that lets you build classes on existing ones, such as the standard `article` class, without having to track which options were passed.

`\ExecuteOptions{options-list}`

  For each option option in the options-list, in order, this command executes the command `\ds@option`. If this command is not defined then that option is silently ignored.

  It can be used to provide a default option list before `\ProcessOptions`. For example, if in a class file you want the default to be 11pt fonts then you could specify `\ExecuteOptions{11pt}\ProcessOptions\relax`.

`\NeedsTeXFormat{format}[format date]`

  Specifies the format that this class must be run under. Often issued as the first line of a class file, and most often used as: `\NeedsTeXFormat{LaTeX2e}`. When a document using that class is processed, the format name given here must match the format that is actually being run (including that the format string is case sensitive). If it does not match then execution stops with an error like ‘`This file needs format `LaTeX2e' but this is `xxx'.`’

  To specify a version of the format that you know to have certain features, include the optional format date on which those features were implemented. If present it must be in the form `YYYY/MM/DD`. If the format version installed on your system is earlier than format date then you get a warning like this.

      You have requested release `2038/01/20' of LaTeX, but only
      release `2016/02/01' is available.

`\OptionNotUsed`

  Adds the current option to the list of unused options. Can only be used within the code argument of either `\DeclareOption` or `\DeclareOption*`.

`\PassOptionsToClass{option list}{class name}`
`\PassOptionsToPackage{option list}{package name}`

  Adds the options in the comma-separated list option list to the options used by any future `\RequirePackage` or `\usepackage` command for package package name or the class class name.

  The reason for these commands is: you may load a package any number of times with no options but if you want options then you may only supply them when you first load the package. Loading a package with options more than once will get you an error like `Option clash for package foo.` (LaTeX throws an error even if there is no conflict between the options.)

  If your own code is bringing in a package twice then you can collapse that to once, for example replacing the two `\RequirePackage[landscape]{geometry}` and `\RequirePackage[margins=1in]{geometry}` with the single command `\RequirePackage[landscape,margins=1in]{geometry}`.

  However, imagine that you are loading `firstpkg` and inside that package it loads `secondpkg`, and you need the second package to be loaded with option `draft`. Then before doing the first package you must queue up the options for the second package, like this.

      \PassOptionsToPackage{draft}{secondpkg}
      \RequirePackage{firstpkg}

  (If `firstpkg.sty` loads an option in conflict with what you want then you may have to alter its source.)

  These commands are useful for general users as well as class and package writers. For instance, suppose a user wants to load the `graphicx` package with the option `draft` and also wants to use a class `foo` that loads the `graphicx` package, but without that option. The user could start their LaTeX file with `\PassOptionsToPackage{draft}{graphicx}\documentclass{foo}`.

`\ProcessOptions`
`\ProcessOptions*\@options`

  Execute the code for each option that the user has invoked. Include it in the class file as `\ProcessOptions\relax` (because of the existence of the starred command).

  Options come in two types. Local options have been specified for this particular package in the options argument of `\PassOptionsToPackage{options}`, `\usepackage[options]`, or `\RequirePackage[options]`. Global options are those given by the class user in `\documentclass[options]` (If an option is specified both locally and globally then it is local.)

  When `\ProcessOptions` is called for a package `pkg.sty`, the following happens:

  1. For each option option so far declared with `\DeclareOption`, it looks to see if that option is either a global or a local option for `pkg`. If so then it executes the declared code. This is done in the order in which these options were given in `pkg.sty`.
  2. For each remaining local option, it executes the command `\ds@`option if it has been defined somewhere (other than by a `\DeclareOption`); otherwise, it executes the default option code given in `\DeclareOption*`. If no default option code has been declared then it gives an error message. This is done in the order in which these options were specified.

  When `\ProcessOptions` is called for a class it works in the same way except that all options are local, and the default code for `\DeclareOption*` is `\OptionNotUsed` rather than an error.

  The starred version `\ProcessOptions*` executes the options in the order specified in the calling commands, rather than in the order of declaration in the class or package. For a package this means that the global options are processed first.

`\ProvidesClass{class name}[release date brief additional information]`
`\ProvidesClass{class name}[release date]`
`\ProvidesPackage{package name}[release date brief additional information]`
`\ProvidesPackage{package name}[release date]`

  Identifies the class or package, printing a message to the screen and the log file.

  When you load a class or package, for example with `\documentclass{smcmemo}` or `\usepackage{test}`, LaTeX inputs a file. If the name of the file does not match the class or package name declared in it then you get a warning. Thus, if you invoke `\documentclass{smcmemo}`, and the file `smcmemo.cls` has the statement `\ProvidesClass{xxx}` then you get a warning like `You have requested document class `smcmemo', but the document class provides 'xxx'.` This warning does not prevent LaTeX from processing the rest of the class file normally.

  If you include the optional argument then you must include a date, before any spaces, of the form `YYYY/MM/DD`. The rest of the optional argument is free-form, although it traditionally identifies the class, and is written to the screen during compilation and to the log file. Thus, if your file `smcmemo.cls` contains the line `\ProvidesClass{smcmemo}[2008/06/01 v1.0 SMC memo class]` and your document’s first line is `\documentclass{smcmemo}` then you will see `Document Class: smcmemo 2008/06/01 v1.0 SMC memo class`.

  The date in the optional argument allows class and package users to ask to be warned if the version of the class or package is earlier than release date. For instance, a user could enter `\documentclass{smcmemo}[2018/10/12]` or `\usepackage{foo}[[2017/07/07]]` to require a class or package with certain features by specifying that it must be released no earlier than the given date. (Although, in practice package users only rarely include a date, and class users almost never do.)

`\ProvidesFile{file name}[additional information]`

  Declare a file other than the main class and package files, such as configuration files or font definition files. Put this command in that file and you get in the log a string like `File: test.config 2017/10/12 config file for test.cls` for file name equal to ‘`test.config`’ and additional information equal to ‘`2017/10/12 config file for test.cls`’.

`\RequirePackage[option list]{package name}[release date]`
`\RequirePackageWithOptions{package name}[release date]`

  Load a package, like the command `\usepackage` (see Additional packages). The LaTeX development team strongly recommends use of these commands over Plain TeX’s `\input`; see the Class Guide. An example is `\RequirePackage[landscape,margin=1in]{geometry}`.

  The option list, if present, is a comma-separated list. The release date, if present, must have the form YYYY/MM/DD. If the release date of the package as installed on your system is earlier than release date then you get a warning like `You have requested, on input line 9, version `2017/07/03' of package jhtest, but only version `2000/01/01' is available`.

  The `\RequirePackageWithOptions` version uses the list of options for the current class. This means it ignores any options passed to it via `\PassOptionsToClass`. This is a convenience command to allow easily building classes on existing ones without having to track which options were passed.

  The difference between `\usepackage` and `\RequirePackage` is small. The `\usepackage` command is intended for the document file while `\RequirePackage` is intended for package and class files. Thus, using `\usepackage` before the `\documentclass` command causes LaTeX to give error like `\usepackage before \documentclass`, but you can use `\RequirePackage` there.