This file contains suggestions for how to write TeX files, with four
different goals in mind:
Making sure the output is of good quality. There are standard ways in
TeX to handle a number of slightly unusual situations, which beginners
are often never told about. Through lack of knowledge, beginners often
adopt naive workarounds which produce ugly output.
Making sure the file will run properly under all TeX programs and can
easily be converted between different versions of TeX. I have had
several nasty experiences. I don't know that everything I do is really
important for this purpose, but it is better to be safe than sorry.
Making sure that the source file is easily readable--important when you
want to revise a paper, when several people work on the same paper, when
you want to reuse exam problems with small changes, etc.
Reducing the number of false complaints by spell check programs. You
can't stop this entirely (even with ones which know not to flag TeX
commands), but you can reduce the number of false complaints.
A separate file addresses writing mathematics well.
This file is intended to be displayed in a fixed width font. Otherwise,
the spacing will not work properly.
========================================================================
Rules for producing good output:
________________________________________________________________________
Use large enough parentheses ("\bigl( ... \bigr)", or, for larger
expressions, "\left( ... \right)"). (See below for warning on
"\left( ... \right)".)
The second version automatically chooses the size: the least size that
is at least as tall as whatever is inside the parentheses. This should
usually be your default choice. (There are a few constructions in which
this fails, so pay attention to the output.) The first has bigger
variants (\Big etc.; see a TeX manual).
The second alternative tends to produce parentheses that look too large
around such expressions as S^{(0)} and \frac{1}{2^n} (in text). The
problem is that the possible sizes form a small discrete set, and
sometimes one that is slightly too small looks better that one that is
substantially too big.
Also, the first can be used even if the heights of the symbols inside
don't demand larger parentheses. You might want to do this in
expressions like:
\bigl( a_1 (x_1 + y_1) + \cdots + a_n (x_n + y_n) \bigr) (\xi - \eta)
The following is, to me, nasty behavior. The expression
"$f \left( x \right)$" is a TeX error (at least in AMSLaTeX). By
comparison with "$f (x)$", the opening parenthesis is too far from
the letter f (like "f (x)" instead of "f (x)", although less extreme).
I have not checked how "\bigl(" etc. behave.
________________________________________________________________________
Add extra space if needed, usually in comma separated lists in which
some of the individual entries are long. Thus:
$(a + b, \, x + y)$, not $(a + b, x + y)$
$(a, \, x + y)$, not $(a, x + y)$
$a_0, \, a_1, \, \ldots, \, a_{n - 1}, \, a_n$, not
$a_0, a_1, \ldots, a_{n - 1}, a_n$
My best guess is that if you put in extra space in one place is such a
list, you should put it everywhere.
________________________________________________________________________
Here are three related examples in which an extra space ("\,") is
needed regardless of the sizes of the expressions:
$\int_X f \, d \mu$
$\int_X f (x) \, d \mu (x)$
$\int_a^b t^2 f (t) \, d t$
________________________________________________________________________
Never put a blank line before a displayed equation, and, unless it is at
the end of a paragraph, never put a blank line after a displayed
equation. Thus:
Suppose $x > y > 0$.
Then
\[
\frac{1}{1 + x^2} < \frac{1}{1 + y^2}.
\]
Therefore ...
It is wrong to use:
Suppose $x > y > 0$.
Then
\[
\frac{1}{1 + x^2} < \frac{1}{1 + y^2}.
\]
Therefore ...
You get excessive vertical space after "Then", and you get inappropriate
indentation (and maybe excessive vertical space) at "Therefore".
________________________________________________________________________
$\| a \| \| b \|$ produces norm signs which may seem too close together.
I often use $\| a \| \cdot \| b \|$. Similarly, $| a | \cdot \| b \|$
and $| a | \cdot | b |$. (One can also try adding extra space. Despite
the comments above, I am usually reluctant to play with spacing this
way. In the situations above, I feel I have no choice. I have seen
conversions to TeX from other formats which, I think, put a bit of
extra space for _any_ product.)
________________________________________________________________________
$a \frac{x}{y}$ makes poor output. You need $a \cdot \frac{x}{y}$ or
$a \bigl( \frac{x}{y} \bigr)$ or $a \left( \frac{x}{y} \right)$.
________________________________________________________________________
Colons in the following math expressions must be "\colon" rather
than ":". (Otherwise, the spacing will be wrong.)
$f \colon X \to Y$, $\{ x \in X \colon f (x) > 0 \}$.
________________________________________________________________________
Related to the issue with colons: Use the correct choice of symbol in
math. There are often several codes which give the same symbol, yet are
actually different (like : and \colon) in "spacing rules". Every TeX
math symbol comes with spacing rules which specify how much space
should be on each side of it, and these rules are different for
different symbols. (This is the only difference between : and \colon.)
To see the effect of this, look at the spacing in the output from what
happens is you try to use "<" and ">" (which TeX considers to be
relation symbols) as brackets for scalar products:
< \xi_1, \eta_1 > = < \xi_2, \eta_2 >
vs.
\langle \xi_1, \eta_1 \rangle = \langle \xi_2, \eta_2 \rangle
In the output from the first, there is too much space between "\eta_1"
and ">" and too little between ">" and "="; in fact, "> = <" comes out
looking like a single unit.
Sometimes you are stuck with abusing symbols. (Mathematicians tend to
do this.) Here are three common things I encounter, and what to do about
them.
Suppose your output is supposed to look like
x = a + b + c
+ r + s + t
(This isn't really right: the first "+" on the second line should be
farther to the right, but for the purpose of making a point let's ignore
that.) The obvious coding is
\begin{align*}
x & = a + b + c
\\
& + r + s + t
\end{align*}
The output from this will have strange spacing: there will be less
space between the first + sign on the second line and the symbol r
than surrounding the other + signs. This results from TeX spacing
rules which distinguish between + as a binary operator and + as a
unary operator. The fix is to put an invisible symbol which nevertheless
makes TeX think the offending + sign is a binary operator:
\begin{align*}
x & = a + b + c
\\
& {\mbox{}} + r + s + t
\end{align*}
The second example is a quotient by an equivalence relation, such as
X / ~. The obvious TeX code is "X / \sim". This gives excess space
between "/" and "\sim", because "\sim" is a relation symbol. I have
tried to fix this by inserting negative space, but I think the right
fix is as follows: "X / {\sim}".
The third example is using commas to separate blocks of digits in
numbers with many digits. For example, "$11,111,111,119$" produces
ugly output: there is too much space after the commas (even though
there is no space in the input). The code "$11{,}111{,}111{,}119$"
produces the correct output.
In general, I think surrounding a symbol with { } kills special
spacing rules, leaving the symbol treated as a variable. Although I
have not tried it, if you really want to use < and > in your notation
for scalar products, I think the following will give correct (or at
least better) spacing:
{<} \xi_1, \eta_1 {>} = {<} \xi_2, \eta_2 {>}
________________________________________________________________________
Sequences of dots: Never use "...". The spacing is much too small.
Use \ldots for lists like $a_1, a_2, \ldots, a_n$ and \cdots for
operations and relations like $a_1 + a_2 + \cdots + a_n$ and
$a_1 \sim a_2 \sim \cdots \sim a_n$. (The command "\dots" is supposed
to let TeX make the choice, but sometimes it chooses wrongly.)
________________________________________________________________________
Never use "$...$" for emphasis or anything else except mathematical
symbols. This is intended _only_ for mathematics. TeX has other
commands for italicizing or emphasizing text, such as \emph and
\textit. The spacing of text is different from the spacing in
mathematical expressions. For an example mating this particularly
visible, compare the output from "$different$" and
"{\emph{different}}$". The first gives visibly ugly output.
________________________________________________________________________
Dashes:
Hyphen (in text), minus sign (in math): -
Range designation (as pages 36 to 48): -- (thus: "pages 36--48")
Dash as punctuation: --- (thus, "He went home---not to his office.")
________________________________________________________________________
Separate mathematical expressions must have their own enclosing
"$...$". Thus, "$x = 1$, $y = 2$, and $z = 3$.", _not_
"$x = 1, y = 2$, and $z = 3$.". The second version produces poor
spacing. (However, "$x, y \in X$" is probably right.)
________________________________________________________________________
If a period is followed by a space in the file but is not the end of a
sentence, it usually needs to be followed by the characters "\ "
(backslash and two spaces). Otherwise, there may be excess space in the
output after the period. (If only one space is used rather than two, the
output will be correct, but some spell checkers will skip the beginning
of the next word and therefore falsely claim it was misspelled.)
________________________________________________________________________
Bar and hat: TeX instructions say to use "${\bar{z}}$" and
"${\hat{g}}$" (although with fewer braces) for overlines and hats
on single characters, but "${\overline{w + z}}$" and
"${\widehat{f + g}}$". The second version produces variable width
overlines and hats. Unfortunately, the first version produces overlines
and hats which are so small as to be easily overlooked when reading
the output. I therefore never use it.
________________________________________________________________________
Words and abbreviations used as mathematical symbols are supposed to be
in Roman type. For standard ones, TeX already provides commands, such as
\exp, \log, \sup, \sin, etc. But if you use one TeX doesn't know, you
must specify this, via {\mathrm{exp}} or (perhaps better)
{\operatorname{exp}}.
________________________________________________________________________
To produce reasonable output for
{ (x, y, z): f (x) = f (y) and g (z) = x },
you are likely to find yourself artificially adding space around
"and" (and maybe even getting it typeset as a product of variables,
which messes up the spacing of the letters). The following works much
better:
\[
\big\{ (x, y, z) \colon {\mbox{$f (x) = f (y)$ and $g (z) = x$}} \big\}
\]
The conditions after the colon are typeset as if they were normal text
containing math, which is what you want. (There will be trouble if the
conditions are too long to fit on one line, or contain integrals or
other "large" operators.)
________________________________________________________________________
Here is one I am not certain of (and I have seen conflicting
information), but it does make a (small) difference in the output. I
have been putting periods and commas outside $...$. Thus, "Therefore
$a < b$.", not "Therefore $a < b.$"
________________________________________________________________________
The following example is specific to operator algebras. "A factor of
type II_1" in TeX should be, I think, "A factor of type
${\mathrm{II}}_1$".
========================================================================
Justifications for writing safe TeX files:
You want your TeX files to be undamaged by likely changes in the
program, conversion between LaTeX and AMSTeX, and things commonly done
with files.
Many things are likely to be done with a significant TeX file:
sending it by email (as an attachment or not) (sharing your work
or exam problems and solutions with colleagues), processing it on
a variety of systems (your colleagues don't have the same computer
system or TeX program you do; this is especially significant if
you post your file on your web site or to the arXiv), extracting
short pieces of it as "pseudoTeX" for use in an email message,
running a spell check program on it, etc. You may want to convert
it from LaTeX to AMSTeX (perhaps because a coauthor uses a different
version than you do). You want it to still work on TeX programs that
don't yet exist, such as LaTeX 3.0.
Here are five nasty things that have happened to me. (The last two are
the fault of bad email programs, and can't be prevented by what you do
to the TeX file.)
(1) Somebody emailed me a TeX file in which Greek letter subscripts
and superscripts were done without braces: "_\alpha" instead of
"_{\alpha}". There were many of them, and every one caused an error
in the TeX program I tried to process it with.
(2) Because of something involving a coauthor, I has to convert
something from LaTeX to AMSTeX. In one version, boldface text was
\bf{...}, and in the other it was {\bf ...}. I had to go through and
change every instance of boldface text; there were quite a few.
Note, though, that {\bf{...}} worked properly in both.
(3) Somebody emailed me a TeX file containing lines starting "From ...".
Since email delivery software interprets "From ..." as a header, many
email programs replace "From ..." by ">From ...". If the extra ">" is
still present in the TeX file when you run it, it generates an upside
down question mark in the output.
(4) Somebody emailed me a TeX file which had been encoded as something
called "quoted-printable". The main defect was the replacement of every
"=" by "=3D", corrupting every equation with "=" in the entire output.
(5) Somebody emailed me a TeX file using a horrible "modern" email
program which corrupts line breaks (and also people have tried to use my
emailed TeX files using programs to read their email which corrupt line
breaks in incoming messages). Line breaks matter in TeX files. The most
serious problem I have seen so far involves comments: some material
which was supposed to be commented out no longer was, and some material
intended to be processed was in fact commented out. Both faults ruined
the meaning wherever they occurred. (This particular issue won't occur
if the character "%" doesn't occur in the TeX file, but corrupting the
line breaks may well cause other problems.)
========================================================================
Rules for writing safe TeX files:
________________________________________________________________________
Every multicharacter subscript or superscript, even something like
\alpha, needs to be in braces. (The expression $n_\alpha$ is not
acceptable because it does not work properly in some implementations.
Use $n_{\alpha}$. One can make a case that _every_ subscript or
superscript should be inside braces.)
________________________________________________________________________
Font changing and related commands should use two sets of braces.
For example, "{\emph{...}}" and "{\textbf{...}}". In some versions,
only the inner set is required, in some versions, only the outer set
is required, but the extra set does no damage. Similarly, do this
with things like "{\overline{...}}", "{\mathcal{...}}", "{\mbox{...}}".
________________________________________________________________________
Never start a line with "From". Use "{}From" instead. (If the file is
sent in email, "From " will become ">From ", and the output will
have an upside down question mark.)
________________________________________________________________________
Do not put a space at the end of a line. If the line is really supposed
to end with a space (such as backslash, space, space), put the character
"%" at the end. (This is a comment character, and produces no output.)
________________________________________________________________________
TeX files should contain only 7 bit ASCII characters.
________________________________________________________________________
The following rules address things I have not actually had trouble with,
but which look suspiciously like they could easily cause trouble.
________________________________________________________________________
Attach "\label{...}" to the thing to which it applies with no space
or line break. Thus:
"\begin{lemma}\label{Lemma1}".
________________________________________________________________________
Don't separate arguments from commands, or arguments of commands from
each other, with spaces or line breaks.
Write:
\frac{x}(y}
Don't write:
\frac {x} {y}
\frac{x}
{y}
\frac
{x}{y}
The last forms probably actually work properly on most implementations
of TeX, but I don't trust them. This means that if the numerator and
denominator are long enough that a line break is required somewhere,
I usually put the analog of:
\frac{x_1 + x_2 + x_3 + x_4 + x_5 + x_6 + x_7}{
y_1 + y_2 + y_3 + y_4 + y_5 + y_6 + y_7}
========================================================================
Justifications for writing readable TeX files:
TeX files are often not things you write once and forget about. You
need to be able to read your TeX files for many reasons:
Correcting errors.
Improving or extending (partial) drafts. If you write a proof of a
theorem to show your colleague or thesis advisor, you may well
eventually want to incorporate it, with suitable modifications,
in a paper or thesis.
If you write a paper based on your thesis, or a survey article based
on one or more of your papers, you will want to reuse (possibly large)
sections of text.
If you submit a paper, or give your advisor a (draft) copy of your
thesis, you are likely to be asked to make changes.
You are likely to want to reuse exam problems, often with minor
changes (such as changing the numbers).
If you write a joint paper, your coauthors need to be able to read
your TeX (and you need to be able to read your couathors' TeX).
(Some of the suggestions here are more aimed at making searches easier
than at making the file more readable.)
========================================================================
Rules for writing readable TeX files:
________________________________________________________________________
Use spaces. Examples:
a times b is $a b$ not $ab$. Especially, don't write $a_nb_n$.
(Besides readability, the expression "$axy$" will trigger
complaints by spell check programs, even those that claim to
be TeX aware, but "$a x y$" won't.)
________________________________________________________________________
Leave a space on each side of every operation or relation symbol:
$a + b$ not $a+b$
$a < b$ not $a** b$,
so we conclude $a = b$.
________________________________________________________________________
Don't break an in-line formula ("$..$.") across lines, unless it
is more than 72 characters long. If it is, break it at a logically
sensible place (especially at "=" or a relation symbol; next best
is an operation symbol), indent the second part, and don't put
anything else on any line containing part of the formula.
========================================================================
Rules for reducing false alerts by spell checkers:
________________________________________________________________________
Put spaces between variables in products. $xyz$ will generate a
complaint by a spell check program, even one that claims to be TeX
aware, but $x y z$ won't. (This is also under rules for readable TeX.)
________________________________________________________________________
If you use "\ " for a forced space (for example, after a macro in text
or after a period which is not the end of a sentence), put in an extra
space: "\ ". It has no effect on the output. Without the extra space,
at least one spell checker (which I often use because it knows not to
flag TeX commands) will not read the first character or two of the next
word, and will therefore generate a spurious warning.
Examples:
\newcommand{\hm}{homomorphism}
Let $\psi \colon A \to B$ be a \hm.
All \hm s are continuous.
[Or, better: "All \hm{s} are continuous."]
Every \hm\ from $A$ to $B$ is continuous.
[This also works: "Every \hm{} from $A$ to $B$ is continuous." However,
"Every \hm\ from $A$ to $B$ is continuous." generates warnings about
the word "rom", or maybe "om", being misspelled.]
========================================================================
**