Creating a TeX file
The bulk of the work in producing a TeX'ed document consists in
actually creating the .tex file (which serves as the "source file" for
the TeX program) with an editor.
Most of the time, the tex file will need to be edited and re-edited
many times over, to fix compile problems, correct typos, etc. Thus, it
is important that the TeX file be in a form that makes such repeated
edits as easy as possible. While TeX does not care about the "looks"
of the tex file, with a messy file the editing is more difficult,
and there is a greater risk of introducing errors in the editing
process. A lot of time can be saved and headaches and frustration
prevented by following some simple stylistic guidelines when creating
the tex file in the first place.
Use a "TeX aware" editor, with "tex mode" turned on if necessary
Editors (like winedit) that come with tex systems, and the Unix editors
emacas and vim (but not vi) have a "tex mode", where different logical
structures in a TeX document (e.g., macros, math expressions, comments)
are displayed in different colors. This makes it easy to spot such
things as a missing dollar sign, or a mismatched pair of braces, and to
correct these errors. Usually, tex mode is automatically turned on for
tex files, but sometimes (e.g., with nonstandard file extensions) it may
have to be turned on manually.
Avoid overlong lines
A file with entire paragraphs without linebreaks is very hard to
maintain, and easy to mess up.
Any of the common TeX editors has an "autowrap" feature that
automatically inserts linebreaks. Turn on that feature, if necessary,
and make sure that the line length is set to no more than 80 characters,
the standard size of a terminal window. When editing a TeX
file, it is best to restrict the window size to 80 characters rather
that using the full screen width.
Use comment symbols (%) sparingly, if at all
The percentage symbol (%) is TeX's comment symbol; TeX ignores
everything from such a symbol through the end of the line.
Thus, one could "comment out" entire paragraphs of text by placing a
comment symbol at the beginning of each line. However, this makes
the file very hard to maintain as with every edit there is a chance that
a comment symbol gets inadvertently deleted, or a linebreak gets
inserted in the midst of a commented out section, creating a new
uncommented line. [To make large chunks of text "invisible", use
the verbatim package, or enclose the chunk within an \iffalse ... \fi
pair. The latter is not a perfect solution, but works almost all the
time and is far safer than putting comment symbols at the beginning of
each line.]
Instead of using a single comment symbol, a safer method is to insert
multiple comment symbols, or an entire line of such symbols. This can be
used to highlight particular places in the document (e.g., the start of
a new section, or the beginning of the bibliography). I use this method
frequently, and I have a macro in vim that creates a line of %'s
with two keystrokes.
Add multiple blank lines at major breaking points in a document (e.g.,
between sections)
As far as TeX is concerned,
multiple blank lines are equivalent to a single blank line, and
adding several blank lines instead of a single one at major breaking
points (e.g., between sections) makes these places easier to spot.
Add line breaks and spaces in math mode, to avoid overlong lines
and to improve the readability of complex math expressions
Remember that in math mode
TeX ignores any spaces (except blank lines). Thus, you are free to
insert spaces and line breaks.
For example, in "\frac{...}{...}", it is okay to insert a line break
between the two pairs of braces (and even between the macro "\frac"
and the first brace). This makes complex fractions more readable
and avoids overlong lines.
Place \begin{...}, \end{...} constructs and \[ ... \] on lines by
themselves
This makes these environments visually stand out and easy to spot.
Do NOT add blank lines before or after displays unless you want a
paragraph break there
A very common mistake is to add blank lines before and after equations
in order to make the displays stand out. However, TeX interprets
these lines as paragraph breaks, which may cause additional (undesirable)
spacing to be added and the next piece of text to be indented.
The best way to make displays stand out is by
putting the \begin{..} and \end{...} commands on lines by themselves
as mentioned above.
If you really want to do something further to highlight a display, add a
line of comment symbols (%) before and after the display.
Add one or more blank lines before and after titles, section headings,
etc., and environments such as
theorem or proof (but not displayed equation environments)
TeX automatically inserts the appropriate spacing before and after such
environments, and the extra blank lines make no difference at all as far
as TeX is concerned, but they make these constructs visually stand out.
Put all macros in a single place near the top of the document, group
macros by function, and put each macro on a separate line
Don't scatter macros throughout the document. If midway through editing
a document you find that could use another macro, insert it in the
preamble at the top of the document. Having all macros in a single place
makes it easier to maintain these macros, and to detect any problems or
inconsistencies.
Similarly, grouping similar macros (e.g., all theorem declarations
(\newtheorem{...}), followed by math font macros (\mathbb{N}), followed
by operator definitions (\operatorname{...}), etc.), and by putting each
macro on a line by itself makes it easier to spot a macro, and the file
more maintainable.
Back to the LaTeX Tips Page
Last modified: Tue 23 Aug 2011 05:48:17 PM CDT
A.J. Hildebrand