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