There are 16 character categories:ref
catcode | Description | Literal in plain TeX |
---|---|---|
0 | Escape character | \ |
1 | Begin grouping | { |
2 | End grouping | } |
3 | Math shift | $ |
4 | Alignment tab | & |
5 | End of line | 〈return〉 |
6 | Parameter | # |
7 | Superscript | ^ |
8 | Subscript | _ |
9 | Ignored character | 〈null〉 |
10 | Space | 〈space〉 and 〈tab〉 |
11 | Letter | only contains the letters a, …, z and A, …, Z. These characters can be used in command names |
12 | Other | everything else not listed in the other categories |
13 | Active character | ~ |
14 | Comment character | % |
15 | Invalid character | 〈delete〉 |
Characters can be assigned a different catcode (which is local to the current group) with the \catcode
command.
For example, \makeatletter
is a commonly used catcode manipulation helper in LaTeX. Start latex
and run:
\*\*\show\makeatletter
> \makeatletter=macro:
->\catcode \`\@11\relax .
I.e., makeatletter
is a macro that uses \catcode
to put the @
character into the “Letter” category so that it can participate in command names. We can look at its default setting:
\showthe\catcode\`\@
> 12.
Which produces 12.
, meaning @
, by default, is in the “Other” category.
TeX has ten special characters (TeXBook, ch. 7, pg. 38): \ { } $ & # ^ _ % ~
Note that @
is not one of those characters.
There are two types of control sequences:
A control sequence can be composed from raw tokens with the \csname
and \endcsname
commands.
E.g., \csname TeX\endcsname
is like saying \TeX
.
Literal characters can be specified by ASCII code with the \char
command; for example:
\char98
= \char'142
= \char"62
= b
Since decimal 98 = octal 142 = hexadecimal 62.
There is also a \symbol
command, which simply wraps \char
and adds a \relax
after the given character code.
This can be handy if you’re not sure what will follow your \char
macro.
The following are all equivalent and produce the Unicode character, “U+221E (INFINITY)”:
\symbol{8734}
= \symbol{'21036}
= \symbol{"221E}
= ∞
ASCII’s control characters can be represented by a special prefix, ^^
.
E.g.: ^^@
= “U+0000 NUL” (Null), ^^A
= “U+0001 SOH” (Start of Heading), etc. up to ^^_
= “U+001F US” (Unit Separator)
Calling tex
and latex
without arguments will bring up interactive prompts for the respective compilers.
It’s probably handy to run them under rlwrap
, e.g., rlwrap tex
.
By default, these will write a texput.dvi
file when done, which can be converted to texput.pdf
with dvipdf texput.dvi
.
\show
expands a macro and displays the expanded equivalent at the interactive prompt.
If the thing following \show
is a primitive, the resulting message is not very helpful.
\*\show\badness
> \badness=\badness.
\the
extracts a representation of the thing following it, and puts that on the output.
So it doesn’t show up at the interactive prompt, which is unfortunate.ref\showthe
is like \the
, but outputs to the interactive prompt / log, like \show
. Nice!\overfullrule=1em
prints a big black box (in the right margin) where there are are overfull lines.
Dedicated packages
showkeys
is a package that causes \label
and \bibitem
to print their key values in the margin,
and causes \ref
, \pageref
, and \cite
to print their argument(s) directly above their normal output.
Simply import the package to achieve this effect: \usepackage{showkeys}
showlabels
is similar, but can also typeset the keys in the text if you like (thus affecting the overall flow).
By default, it only prints out keys for \label
commands.
E.g., to print out all labels in the left margin:
\usepackage[left]{showlabels}
And to use a slightly smaller font for these keys (the default is \small\ttfamily
):
\renewcommand{\showlabelfont}{\scriptsize\ttfamily}
showframe
draws frames around each of the page layout components.
Very useful alongside this Page Layout reference.
\usepackage{showframe}
LaTeXref
\newcommand\mycmd{...}
: Creates a new command and breaks if mycmd
already exists.\renewcommand\mycmd{...}
: Overwrites mycmd
, and breaks if mycmd
doesn’t already exist.\providecommand\mycmd{...}
: Overwrites mycmd
only if mycmd
doesn’t already exist, otherwise creates a new command.There is no \declarecommand\mycmd{...}
to overwrite mycmd
regardless, but you could define it like so:ref
\newcommand{\declarecommand}[1]{\providecommand{#1}{}\renewcommand{#1}}
Plain TeXref
\def\mycmd{...}
\gdef\mycmd{}
, which declares \mycmd
as a global, which may be useful if you’re already inside some scope and you want the variable to apply outside of it. For example:Some packages or document classes facilitate configuring internal variables via proxy commands, e.g., a 3rd-party library might have this snippet:
\newcommand{\submissiondate}[1]{\gdef\@submissiondate{#1}}
% Later on, perhaps in \maketitle, call \@submissiondate{}
Which you would call in your consuming document, probably in the preamble:
\submissiondate{2014-11-20}
In such a case, not calling \submissiondate{...}
in the consuming document will induce an error in the 3rd-party library, since \@submissiondate
was never defined. There are two ways to handle this error.
\def\@submissiondate{A long time ago}
Condition on @submissiondate
having been defined, using the LaTeX standard macro \@ifundefined
:
\@ifundefined{@submissiondate}{Submission date not recorded}%
{Submitted on \@submissiondate}
N.b. We use @submissiondate
, without the \
. If we had used \@submissiondate
, it would try to evaluate that before passing control to \@ifundefined
.
These are all primitives (i.e., they are built into the TeX compiler, not defined in latex.ltx
or article.cls
):
\def
takes two arguments; it defines a local macro that expands to the contents of the second argument.
\def\sayhello{Hello}
does nothing immediately, but whenever \sayhello
is subsequently used, it expands to the string “Hello”.\global
makes the subsequent definition/assignment (\def
, \let
, \count
, among others) global.
\gdef
is short for \global\def
: it defines a global macro.
\expandafter
takes two arguments; it expands the second in place (by exactly one level of expansion), then returns to normal processing flow, expanding the first as usual.\noexpand
wraps its single argument in a single level/layer of indirection.
\expandafter
over something that has been \noexpand
‘ed, it would only unwrap that single level, down to the pre-\noexpand
value, but no further.\edef
is like \def
, but immediately expands the second argument.
\xdef
is short for \global\edef
These are helpers that are defined in latex.ltx
:
\g@addto@macro
takes two arguments, 1) a macro and 2) something that can be expanded. It expands the second, appends it to the current definition of the original macro.
\xdef
internally, so the new content effectively gets expanded twice.References: What does \z@ do?
Macro | Value | Source / explanation / description |
---|---|---|
\z@ |
0pt |
\newdimen\z@ \z@=0pt ; i.e., zero (equivalently, 0pt ) - useful because it avoids the need to say 0\relax in some cases. |
\@empty |
{} |
\def\@empty{} ; i.e., nothing. |
Character definitions (defined with \chardef
in latex.ltx
):
Macro | Value |
---|---|
\@ne |
1 |
\tw@ |
2 |
\thr@@ |
3 |
\sixt@@n |
16 |
\@cclv |
255 |
References: What are the differences between TeX counts and LaTeX counters?, LaTeX/Counters
Plain TeX:
\newcount <register>
defines a number variable, a.k.a., a “count”. E.g., \newcount\mycounter
.
<register> <number>
sets the value of a register. You’ll often also see <register>=<number>
, which does the same thing.
\advance <register> <number>
increases the measure/width indicated by <register>
by the amount indicated. Most often you’ll see something like \advance\mycounter 1\relax
, which increases mycounter
by 1. The \relax
apparently tells LaTeX that’s the end of the number.
\the <register>
prints out (i.e., into the document) the current value of the register, e.g., \the\mycounter
or \the\leftmargin
. \number
can be used instead of \the
in this case.
LaTeX:
\newcounter{<register>}
defines a new counter, and there are several functions for manipulating it.
\newcounter{mycounter}
initialize the counter variable and sets it to 1.\setcounter{mycounter}{10}
sets the counter to 10\stepcounter{mycounter}
then sets the counter to 11\addtocounter{mycounter}{9}
then sets the counter to 20\value{mycounter}
outputs the content “20”Creating a LaTeX counter also creates a function to retrieve its value, with the name \the<register>
, so that \themycounter
will return the value of the “mycounter” counter, same as \value{mycounter}
.
There are several helpers for formatting the current values of counters, e.g., \Roman{mycounter}
:
\arabic
: 1, 2, 3…\alph
: a, b, c…\Alph
: A, B, C…\roman
: i, ii, iii…\Roman
: I, II, III…\fnsymbol : *, †, ‡, §, ¶, |
, **, ††, … |
All of these, except \arabic
, will output blanks for non-positive numbers.
LaTeX counters are just wrappers around TeX counters, and can be accessed prefixed under the prefix “c@”, so the following are equivalent after calling \newcounter{somecount}
:
\the\c@somecount
\thesomecount
Due to the prefix assumption, you can’t access TeX counters with LaTeX counter mechanisms unless the counter was named using the “c@” prefix.
There are four primitives for doing arithmetic that operate on and return specific types.ref
Expression | Result type |
---|---|
\numexpr |
integer |
\dimexpr |
dimension |
\glueexpr |
glue expression |
\muexpr |
muskip value |
The different expressions determine what values each will consume.
The expression is greedily captured, so expressions are often terminated with a \relax
, just to be safe/explicit.
\numexpr
: this consumes only integers, so if you give it a dimension, like 10pt
, it will stop reading at p
.\dimexpr
: this consumes a dimension and then other values as makes sense. E.g.:
\dimexpr 20pt / 10
makes sense, and produces 2pt
.\dimexpr 20pt / 10pt
, like \numexpr
, reads only up until the p
, since you can’t divide a dimension by a dimension (which would be expected to result in a ratio, not a dimension)\dimexpr 6pt + 1in
makes sense, and produces 78.27pt
\glueexpr
: this is \dimexpr
, but for use with “rubber” lengths (a.k.a. skips). E.g.:
\glueexpr 2pt plus 1pt minus .5pt * 2
results in 4.0pt plus 2.0pt minus 1.0pt
\glueexpr 2pt plus 1pt minus .5pt / 2
results in 1.0pt plus 0.5pt minus 0.25pt
\ifnum <left><R><right> <iftrue> /fi
runs the code in the “iftrue” block if “left R right”, where R can be <
, >
, or =
. E.g., \ifnum \the\mycounter =0 \textbf{First} \fi
would insert the bold “First” if “mycounter” is 0, but do nothing for other values of “mycounter”. You can optionally specify a \else <iffalse>
branch, e.g., \ifnum \the\mycounter =0 \textbf{First} \else Not first \fi
Boolean variables can be emulated with \newif
:ref
\newif\ifdraft
That declares two macros for setting the “draft” variable: \drafttrue
and \draftfalse
.
\drafttrue
% \ifdraft now expands to \iftrue
\draftfalse
% \ifdraft now expands to \iffalse
This makes conditionals easy to read. Supposing we want to turn on double-spacing when we’re in “draft mode”, and ensure we’re using single-spacing otherwise:
\ifdraft
\doublespacing
\else
\singlespacing
\end
For example, in a class or package:
\def\@coauthors{}
\newcommand{\coauthors}[1]{\gdef\@coauthors{#1}}
\newcommand{\signatureline}[1]{\parskip=12pt\par\hrulefill\parskip=-8pt\par#1}
\newcommand{\makesigntureform}{
\signature{\@author, Corresponding Author}
\@for\@i:=\@coauthors\do{\signatureline{\@i}}
}
Then, in your consuming document:
\author{Me}
\coauthors{Alice, Bob, Chandralan}
...
\makesignatureform
\maketitle
@
Reference: What do \makeatletter and \makeatother do?
Many packages use @ in their counter / macro names, which signals a sort of ‘private’ status.
In a class (.cls
) or package (.sty
) declaration, you can use @
in variable names without doing anything extra.
To use or modify these in normal LaTeX, you need to tell the compiler to treat the @
character as a normal word character:
\makeatletter
Then you can, for example, override the built-in list label command: \def\@mklab#1{#1\hfil}
(which makes it align left instead of right). To set things back to normal:
\makeatother
ref.
\DeclareOption{flag}{\commands}
: runs \commands
(can be a whole bunch of commands) if flag
was included in the optional arguments when the package or class was loaded, e.g., \documentclass[flag]{exam}
or \usepackage[flag]{anim}
.\DeclareOption*{\PassOptionsToClass{\CurrentOption}{report}}
is a handy way to cascade unhandled commands to be implicitly supplied when calling, e.g., \LoadClass[letterpaper]{report}
.
report
handles 10pt
, then 11pt
, then 12pt
, by overwriting the \@ptsize
command with a different value. Thus, the argument that wins is the last one handled, which in this case, is the max of the supplied arguments. So, you can’t call \DeclareOption*...
and then \ExecuteOptions{12pt}
to set the default (or \LoadClass[12pt]{report}
), because that 12pt
will override whatever 10pt
or 11pt
the consuming document specifies.\LoadClass[letterpaper]{report}
: Load the report
class with the letterpaper
option and whatever other options have been queued up via preceding \PassOptionsToClass{someoption}{report}
calls.\LoadClassWithOptions{report}
: Load the report
class with all the same options that were supplied to this class.\hsize
: apparently equivalent to to \textwidth
, but more primal (plain TeX).\textwidth
: total width of the text area, potentially spanning multiple columns.\columnwidth
: total width of the column’s text area, equal to \textwidth
if there are no columns (well, “no columns” is more properly considered as a single column)\linewidth
: total width of the current line / working area, if in a column or indented list environment.\centering
vs. the center
environment.ref
\centering
scope should end with a \par
or empty line, which is usually the case inside environments where you find \centering
calls, like a \begin{figure} ... \end{figure}
(or even the document
environment, if the whole document should be centered), but something like {\centering The End}
is usually an anti-pattern.\begin{center} ... \end{center}
is defined in terms of the trivlist
environment, and adds vertical margins according to the \parskip
measurement, but these will be absorbed into the page margins if set at the top or bottom of a page.
center
but without the extra space:ref\newenvironment{centerzero}{\parskip=0pt\par\nopagebreak\centering}{\par\noindent\ignorespacesafterend}
\centerline
is an undocumented LaTeX primitive, which doesn’t allow line breaks, so you’ll generally prefer the alternatives above.\hspace*{\fill}
or \hfill
.\tolerance
defaults to 200 (which isn’t a length, just a value)ref
\hspace{10pt}
will dissipate if used at a line break; use \hspace*{10pt}
to avoid this. (I think it’s kind of like having empty \mbox{}
s on either side?)\hfill
is equivalent to \hspace{\fill}
memoir
document class provides a vplace
environment, which takes an optional floating point argument (which defaults to 1) describing the ratio of space above to space below.#1
is your text to be centered):
\begin{vplace}[0.5]#1\end{vplace}
\vspace*{\fill}#1\vspace*{\fill}
, preceded, if necessary, by \topskip0pt
\strut\vfill#1\vfill\strut
\vfill
is equivalent to \vspace{\fill}
, but there is no \vfill*
\vspace*{\fill}
.
\strut
s to center something on page: it gives the \vfill
commands something to push up against.Built in vertical measurements:ref via ref
Length name | Description | Default value for article class |
---|---|---|
\floatsep |
space left between floats | 12.0pt plus 2.0pt minus 2.0pt |
\textfloatsep |
space between last top float or first bottom float and the text | 20.0pt plus 2.0pt minus 4.0pt |
\intextsep |
space left on top and bottom of an in-text float | 12.0pt plus 2.0pt minus 2.0pt |
\dbltextfloatsep |
\textfloatsep for 2 column output |
20.0pt plus 2.0pt minus 4.0pt |
\dblfloatsep |
\floatsep for 2 column output |
12.0pt plus 2.0pt minus 2.0pt |
\abovecaptionskip |
space above caption | 10.0pt |
\belowcaptionskip |
space below caption | 0.0pt |
\stretch{2}
works for both horizontal and vertical alignment, and whereas \fill
produces the skip length 0pt plus 1fill
, \stretch{N}
produces a skip length 0pt plus Nfill
, so you could align something 3/4 down the page by like so:
\vspace*{\stretch{3}} Footer Fragment Here \vspace*{\stretch{1}}
\raggedright
\raggedleft
\begin{flushleft}
\begin{flushright}
\endgraf
is a relic of TeX and is usually defined to \par
. It’s unclear if it’s ever useful, or where.ref\@@par
seems to be the new \endgraf
, but again, unclear where it’d be useful.
\par
is a TeX primitive and (usually) equivalent to a blank line in the .tex
source.
It’s more about starting a new paragraph than the current line.
\\
tells LaTeX to start a new line. It’s more about the current line (what precedes the \\
) than what comes after.\\*
does the same, but avoids a page break (à la \nobreak
).ref\\[12pt]
starts a new line and inserts 12pt of vertical space before it. ref.\newline
is similar to \\
; it breaks the line immediately, but it only works in paragraph mode. \\
, on the other hand, is used in lots of other environments, like tabular
and align
, to separate rows.\linebreak
breaks the line but continues as the same paragraph, so the broken line stretches to fill the full width.\linebreak[priority]
suggests a line break with varying insistence
(0: vague insinuation … 4: offer you can’t refuse).
\allowbreak
can be used to allow a line break, if needed, where there isn’t any whitespace.
E.g., minipage
environments that are back-to-back with each other.
It is treated like an actual gap, so it does not insert a hyphen.\\
to break a line. The better solution is to use \par
in some form (setting \parskip
and \parindent
as needed).ref
For line-by-line needs, where the whole text shouldn’t all flow as it usually does, a minimal custom environment might be in order.
For example, here’s how the report
class defines the quote
environment:
\newenvironment{quote}{\list{}{\rightmargin\leftmargin}\item\relax}{\endlist}
\list
is the label for each item. In this case, it’s empty.\rightmargin\leftmargin
sets the \rightmargin
length to the current value of the \leftmargin
length
(this is particular to the quote environment, which is center-set, but not center justified).Using proper environment bookkeeping and \setlength
, we can rewrite this as:
\newenvironment{quote}{\begin{list}{}{\setlength{\rightmargin}{\leftmargin}}\item\relax}{\end{list}}
\usepackage{indentfirst}
, which is a minimalist package that simply aliases the \@afterindentfalse
boolean setter command to \@afterindenttrue
, which prevents any other package from setting \@afterindent
to false (like would be done when calling \section{...}
), which would cause the subsequent paragraph not to be indented. It is defined (in $TEXMFDIST/tex/latex/tools/indentfirst.sty
) as: \let\@afterindentfalse\@afterindenttrue
and then calls \@afterindenttrue
once to set that if’s value (which seems like overkill to me).\usepackage{parskip}
. This package:
\parbox[pos][height][contentpos]{width}{text}
pos
and contentpos
are vertical alignment indicators, and must be one of the following:
t
(top), c
(center), b
(bottom), or s
(stretch)pos
defaults to t
, and contentpos
defaults to pos
.height
is optional and must be a valid measurement / dimension expressionwidth
is required and must be a valid width measurement (not a flexible length)\rule[raise]{width}{thickness}
raise
: optional dimension expression, defaulting to 0pt
.width
: required dimension expression, indicating how far, horizontally, the rule should extend.thickness
: required dimension expression, indicating how wide (thick) the rule should be.\hrule
is a LaTeX primitive; you should use \rule
instead.\hrulefill
pads out a line with a horizontal rule;
its effect on the rest of the line is identical to \hfill
.
So it’s like \rule{\hfill}{0.4pt}
(0.4pt is an internal constant), but uses \hrule
directly.\strut
produces a(n invisible) box with zero width and a height determined by the current font size.
\def\strut{\relax\ifmmode\copy\strutbox\else\unhcopy\strutbox\fi}
(latex.ltx:558
)\vphantom
takes a single argument, figures out what height it would have, if rendered, and produces a zero-width box (a \strut
) with that height. It’s especially handy in a math environment where you want to emulate a symbol of specific height so that your braces look right, e.g.:
$\left[10^{100^{100}}$ (a.k.a., a googol) $\vphantom{10^{100^{100}}}\right]$
\smallskipamount
is defined as 3pt plus 1pt minus 1pt
\medskipamount
is defined as 6pt plus 2pt minus 2pt
\bigskipamount
is defined as 12pt plus 4pt minus 4pt
Predefined / globally used lengths:ref
\columnsep
: gap between columns\topmargin
: gap above header\topskip
: between header and text\textheight
: height of main text\textwidth
: width of text\oddsidemargin
: odd page left margin\evensidemargin
: even page left margin\parindent
: indentation of paragraphs\parskip
: gap between paragraphs\floatsep
: space left between floats.\textfloatsep
: space between last top float or first bottom float and the text.\intextsep
: space left on top and bottom of an in-text float.\dbltextfloatsep
is \textfloatsep
for 2 column output.\dblfloatsep
is \floatsep
for 2 column output.\abovecaptionskip
: space above caption\belowcaptionskip
: space below caption\abovedisplayskip
: space before maths\belowdisplayskip
: space after maths\arraycolsep
: gap between columns of an array\topsep
: space between first item and preceding paragraph.\partopsep
: extra space added to \topsep
when environment starts a new paragraph.\itemsep
: space between successive items.
\arraystretch
: row height (vertical) multiplier for tabular
environments;
Use \renewcommand{\arraystretch}{1.4}
to get something resembling booktabs
spacing.\tabcolsep
(defaults to 6pt): horizontal space separating columns in tabular
environments;
Use \setlength{\tabcolsep}{3pt}
to cut the default in half.\newpage
vs. \clearpage
.ref
\newpage
is simpler. It just says ‘end this page here,’ but floats may get allocated to that page, or to the next page where the text picks up again. Or if you are in a non-final column of a multi-column layout, it will not cause a pagebreak, but only advance to the next column.\clearpage
calls \newpage
internally, but beyond \newpage
, it flushes all floats, so that when the text picks up again, it will start at the top of a fresh new page that is sure to have nothing on it except for the content following \newpage
.
\cleardoublepage
ensures the next page starts on the right-hand side (inserting a totally blank page if needed), i.e., on an odd-numbered page.\pagebreak
induces a page break.\pagebreak[priority]
suggests a page break…
\pagebreak[0]
: “I dunno, you could start a new page here, or not, whatever. This page is nice, too.”\pagebreak[1]
: “Well I was thinking, this might be a nice place for a page break?”\pagebreak[2]
: “Some of this stuff would probably look better on the next page, what do you think?”\pagebreak[3]
: “Next page would sure be nice, but look I’m not gonna force you to do anything.”\pagebreak[4]
: “You know what, let’s do the next page. Nope, yep, next page. DON’T MAKE ME REMOVE THIS OPTIONAL ARGUMENT.”\textbf{...}
use {\bfseries ...}
.\tiny
, \scriptsize
, \footnotesize
, \small
, \normalsize
, \large
, \Large
, \LARGE
, \huge
, \Huge
) are defined relative to the base font size (10pt
, 11pt
, 12pt
) used when loading the document class (e.g., report
, article
, etc.). \normalsize
is set to that value, which defaults to 10pt
if not specified. ref\fontsize{14}{16.8}
, which sets the font size to 14pt
, and the line-spacing to 16.8pt
(14pt * 1.2
, which is the recommended factor for most fonts). The built-in measurement \baselineskip
gets set to the second argument (16.8pt
in this case). Unlike the predefined font size commands, you must call \selectfont
after \fontsize{size}{linespacing}
to get the new font size to take, but like them, the setting lasts throughout the current scope / group. ref.setspace
package to handle double-spacing / one-and-a-half-spacing. It’s not too hard to change spacing with LaTeX primitives like \linespread{1.5}
(or, alternatively, \renewcommand{\baselinestretch}{1.5}
), but setspace
reverts back to single-spacing for areas outside the main text (e.g., footnotes, tables, captions, among others), which is generally what you want.
setspace
provides \singlespacing
, \onehalfspacing
, and \doublespacing
commands, which apply to the whole current scope, as well as environments with the same names.As noted on the Wikibooks page, there are some conventional prefixes for label names in specific environments:
Prefix | Environment |
---|---|
ch: |
chapter |
sec: |
section |
subsec: |
subsection |
fig: |
figure |
tab: |
table |
eq: |
equation |
lst: |
code listing |
itm: |
enumerated list item |
alg: |
algorithm |
app: |
appendix subsection |
cleveref
and others are clever enough to look up the type of labeled entity when referencing it,
but this makes it easier to check your label name quickly.