Formatting information

A beginner's introduction to typesetting with LATEX

Peter Flynn

Silmaril ConsultantsTextual Therapy Division

v. 3.6 (March 2005)

Contents

Introduction
Foreword
Preface
References
Index

This edition of Formatting Information was prompted by the generous help I have received from TEX users too numerous to mention individually. Shortly after TUGboat published the November 2003 edition, I was reminded by a spate of email of the fragility of documentation for a system like LATEX which is constantly under development. There have been revisions to packages; issues of new distributions, new tools, and new interfaces; new books and other new documents; corrections to my own errors; suggestions for rewording; and in one or two cases mild abuse for having omitted package X which the author felt to be indispensable to users. ¶ I am grateful as always to the people who sent me corrections and suggestions for improvement. Please keep them coming: only this way can this book reflect what people want to learn. The same limitation still applies, however: no mathematics, as there are already a dozen or more excellent books on the market — as well as other online documents — dealing with mathematical typesetting in TEX and LATEX in finer and better detail than I am capable of. ¶ The structure remains the same, but I have revised and rephrased a lot of material, especially in the earlier chapters where a new user cannot be expected yet to have acquired any depth of knowledge. Many of the screenshots have been updated, and most of the examples and code fragments have been retested. ¶ As I was finishing this edition, I was asked to review an article for The PracTEX Journal, which grew out of the Practical TEX Conference in 2004. The author specifically took the writers of documentation to task for failing to explain things more clearly, and as I read more, I found myself agreeing, and resolving to clear up some specific problems areas as far as possible. It is very difficult for people who write technical documentation to remember how they struggled to learn what has now become a familiar system. So much of what we do is second nature, and a lot of it actually has nothing to do with the software, but more with the way in which we view and approach information, and the general level of knowledge of computing. If I have obscured something by making unreasonable assumptions about your knowledge, please let me know so that I can correct it.

Peter Flynn is author of The HTML Handbook and Understanding SGML and XML Tools, and editor of The XML FAQ.

CHAPTER
 2

Using your editor to create documents

LATEX documents are all plain-text files.1 You can edit them with any editor, and transfer them to any other computer system running LATEX and they will format exactly the same. Because they are plain text they cannot corrupt your system, as they cannot be used for hiding or transporting virus infections as binary wordprocessor files can. Everything you can see is in the file and everything in the file is there for you to see: there is nothing hidden or secret and there are no manufacturers' proprietary ‘gotchas’ like suddenly going out of date with a new version.

1. ‘Plain-text’ originally meant just the 95 printable characters of the American Standard Code for Information Interchange (ASCII) — see Table C.1 — but now more commonly includes both these and the relevant 8-bit characters from one (only) character set such as ISO-8859-1 (Western Latin–1) or ISO-8859-15 (Western Latin plus the Euro sign). These are international standards which work everywhere: you should avoid using manufacturers' proprietary character sets like Microsoft Windows–1252 or Apple Macintosh Roman–8, because they may make your documents unusable on some other systems.

2.1 Markup

In a LATEX document, you type your text along with markup which identifies the important parts of your document by name, for example ‘title’, ‘section’, ‘figure’, etc. LATEX does all the formatting for you automatically, using the markup to guide its internal rules and external stylesheets for typesetting.

You do not need to format any of your text in your editor, because LATEX does it all by itself when it typesets. You can of course regularise or neaten its appearance in your editor for ease of editing (for example, keeping each item in a list on a separate line), but this is not required.

You will often hear LATEX markup referred to as ‘commands’ or sometimes ‘control sequences’ (the proper TEXnical term for them). For all practical purposes these terms all mean the same thing.

This course assumes that users have one of TEXshell, TEXnicCenter, WinShell, or WinEdt (Windows only), or Emacs or LYX (any platform) installed. These are discussed briefly in section 2.3, and the menus and toolbars for running LATEX are explained in Chapter 4.

2.2 Quick start for the impatient

If you already know all this stuff about editors and plain-text files and running programs, and you know your system is already correctly installed (including your editor), you'd probably like to type something in and see LATEX do its job. If you don't, then skip forward to section 2.4 and read a bit more about LATEX first.

Figure 2.1Sample document
\documentclass[12pt]{article}
\usepackage{palatino,url}
\begin{document}
\section*{My first document}

This is a short example of a \LaTeX\ document I wrote
on \today. It shows a few simple features of automated
typesetting, including

\begin{itemize}
\item setting the default font size to 12pt;
\item specifying article' type for formatting;
\item using the Palatino typeface;
\item adding special formatting for URIs;
\item formatting a heading in section' style;
\item using the \LaTeX\ logo;
\item generating today's date;
\item formatting a list of items;
\item centering and italicizing;
\item autonumbering the pages.
\end{itemize}

This example was taken from Formatting Information',
\url{http://www.ctan.org/tex-archive/info/beginlatex/}
and use as a teach-yourself guide.

\begin{center}
\textit{Have a nice day!}
\end{center}

\end{document}

Up and running in a few minutes
1. Install the software

Make sure you have a properly-installed LATEX system and a copy of a suitable editor.

2. Create a sample document

Open your editor and type in the text exactly as shown in Figure 2.1. Do not make any changes or miss anything out or add anything different at this stage.

3. Save the document

Save the document as demo.tex

4. Run LATEX or pdfLATEX

Click on the LATEX or pdfLATEX toolbar icon or the TEXTEX File menu item; or type latex demo or pdflatex demo in a command window.

5. Preview the typesetting

Click on the DVI or PDFview toolbar icon or the TEXTEX View menu item; or type your previewer command in a terminal shell.

(Note that there may be a pause the first time you use your DVI viewer, while WYSIWYG font files are created.2)

6. Print it

Click on the Print toolbar icon within the viewer, or use the TEXTEX Print menu item, or type dvips -f demo | lpr (Unix/Linux).

If you encounter any errors, it means you do need to study this chapter after all!

1. DVI previewers use their own font files specially created from the font outlines (TrueType, OpenType, PostScript, METAFONT, etc). The first time you use a font at a size not used before, there will be a second or two's pause while it gets created. The more you use LATEX, the less this happens.

2.3 Editors

All the text of your documents can be typed into your LATEX document from a standard keyboard using any decent plain-text editor. However, it is more convenient to use an editor with special features to make using LATEX easier. Some of the most popular are TEXshellWinShell, TEXnic Center, and WinEdt (Windows only); and LYX and Emacs (all platforms).

2.3.1 LYX

The LYX document editor (all platforms) is a special case, as it uses the What You See Is What You Mean (WYSIWYM) model of synchronous typographic editing as opposed to What You See Is What You Get (WYSIWYG), and many users prefer this interface (but see the reservations in the item ‘Synchronous typographic displays’ in section 3).

LYX makes a strong case for using synchronous typographical editing: it is possible to create even quite large and complex documents without seeing a backslash very often, although with math or complex macros there is probably no way to avoid having to do some manual insertion of LATEX code.

The free availability on multiple platforms makes this a clear answer to the myth of ‘having to edit like a programmer’, and as it is an Open Source project, there is constant improvement, both to the facilities and to the interface.

Probably the only real reservation is that it does not save native LATEX files by default. It uses its own internal format, and it can export LATEX for use in other editors, but the exported files are not designed for human legibility, only for LATEX processing. In a co-operative environment this would be a serious drawback, but for the individual user this interface is an excellent tool.

2.3.2 TEXshell

This is one of the simplest of all the plaintext Windows editors, but it has most of the tools needed to begin with. Sectioning, lists, and graphics can be inserted from the menus, and there are buttons for running LATEX on the open document and for previewing the typeset document.

The syntactic highlighting distinguishes between commands and your text, and it comes with options for spellchecking (you need to install ispell), and for adding math, Greek (math), and some symbol characters from a pickchart. The typeset display is done using your installed DVI viewer (there is no provision for PDF, although as it is configurable, that could probably be edited into the menus).

Download the .tar.gz file from CTAN in the support/TeXshell/ directory and unwrap it into somewhere like C:\Program Files\TeXshell\.3 There is a tsconfig program in the same directory on CTAN, which is designed to help with reconfiguring TEXshell.

2.3.3 WinShell

This is another free Windows editor for beginners with LATEX. Despite its simplicity, it is capable of a considerable amount of document management and assistance with editing. As well as handling stand-alone LATEX files, you can create a ‘Project’ for larger documents, which helps you keep track of additional files like separate chapters, illustrations, diagrams, indexes, etc.

You run LATEX direct from the toolbar icons or with F-key shortcuts. Both standard LATEX and pdfLATEX are supported, as well as creation and previewing of PostScript and PDF output. There are additional toolbars for math characters, and there is a ‘Table Wizard’ for handling tables. The syntax highlighting distinguishes between commands (in blue) and delimiters (in red), leaving your text in black.

Download the WinShellnn.exe program (self-contained setup: the nn changes with the version) from CTAN in the systems/win32/winshell/ directory and double-click it to start the setup.

2.3.4 TEXnicCenter

TEXnicCenter is a powerful Windows editor suitable both for the beginner and the more advanced user. Its ‘Project’ environment keeps track of multiple files, and the processing function (the bit which actually runs LATEX, here called ‘Build’) tries to ensure that all the files you need for a large or complex document are in place before you start typesetting, to avoid errors like missing illustrations.

It's a much more wordprocessor-like control interface, with configurable toolbars and button-controls for lists, math, tables, and previewing options.

Download the TXCSetupxxx.exe program (self-contained setup: the xxx bit changes with the version) from CTAN in the systems/win32/TeXnicCenter/ directory and double-click it to start the setup.

2.3.5 WinEdt

WinEdt is a highly configurable plain-text editor for Windows. It comes with a host of special functions and shortcuts for TEX and LATEX, based on the MikTEX distribution. It is supplied on the TEX Collection 2004 DVD and the proTEXt CD. You can also download it from http://www.winedt.com — in either case there's a 1-month free trial, then it reminds you to buy it.

WinEdt uses a built-in toolbar of configurable buttons, preset for use with LATEX, and it provides syntactic coloring of LATEX commands. Both the positioning and effect of the buttons can be changed, using an editable file of icons and a configuration panel. This flexibility lets you bind a program and arguments (equivalent to a typed command) to a particular icon.

There are default buttons on the toolbar for one-click typesetting, previewing, and PostScript or PDF generation from LATEX documents, and it manages multi-file document projects like most of the other editors. Winedt is also used by many people for normal plaintext file-editing tasks, in preference to more limited programs like Notepad. If you're using the fpTEX which came with the 2003 TEX Collection, some editing of the menus is required (explained in the local installation document) because the default setup is for MikTEX/proTEXt.

2.3.6 GNU Emacs

Emacs is a product of the GNU Project.4 Versions are available for all makes and models of computer, and it has a LATEX-mode which provides syntactic colouring (‘fontification’ in Emacs-speak) and mouseclick processing from a menu or toolbar.

Emacs is a very large and powerful editor, with ‘modes’ (plug-ins) to handle almost everything you do on a computer. Many users run Emacs once on logging in, and never leave it for the rest of the day — or month. As well as edit, you can use it to read your mail, browse the Web, read Usenet news, do wordprocessing and spreadsheets, compile programs, help you write in any computer language — including XML and LATEX — and it provides a few games as well.

Emacs knows about LATEX and how to process it, so it comes with a menu full of LATEX operations to click on. If you are editing complex documents with mathematics, there is a mode (AUCTEX) which has even more functionality. LATEX support is well-developed, and there is a hierarchy of newsgroups for Emacs support.

Because Emacs runs on Microsoft Windows, Macs, Linux, and most other platforms, many LATEX users who have multiple machines (and those who have multiple users to support) prefer it to other editors because it provides the same environment regardless of which platform they are using.

It's sometimes criticised for a steep learning curve, but in fact it's no worse in this respect than any other editor, given the power that it provides, and it is significantly better than most which lack many of the authorial tools available in Emacs.

1. GNU's Not Unix (GNU)’ is a project to make a computing environment completely free of restrictions.

2.3.7 Mac editors

Mac users will be disappointed that I haven't included any of the Mac interfaces here. It's simple: I don't have a Mac right now to try them out on. I hope to remedy this for a future edition.

2.4 LATEX commands

LATEX commands all begin with a backslash (\)5 and are usually made up of lowercase letters only, for example:

\tableofcontents

The \tableofcontents command is an instruction to LATEX to insert the Table of Contents at this point. You would usually use this in a book or report (or perhaps a very long article) somewhere close to the beginning. You don't have to do anything else. Provided that you have used the sectioning commands described in section 3.5, all the formatting and numbering for the Table of Contents is completely automated.

2.4.1 Simple commands

Simple one-word commands like \tableofcontents must be separated from any following text with white-space. This means a normal space, or a newline [linebreak] or a TAB character. For example either of these two forms will work:

\tableofcontents Thanks to Aunt Mabel for all her help
with this book.

\tableofcontents
Thanks to Aunt Mabel for all her help with this book.

If you forget the white-space, as in the following example, LATEX will try to read it as a command called \tableofcontentsThanks. There's no such command, of course, so LATEX will complain at you by displaying an error message (see section 4.2.3.2).

\tableofcontentsThanks to Aunt Mabel for all her help
with this book.

LATEX swallows any white-space which follows a command ending in a letter. It does this automatically, so you don't get unwanted extra space in your typeset output, but it does mean that any simple command which ends in a letter and has no arguments (see below) must be followed by white-space before normal text starts again, simply to keep it separate from the text.

2.4.2 Commands with arguments

Many LATEX commands are followed by one or more arguments, a term from the field of Computer Science, meaning information to be acted upon. Here are two examples:

\chapter{Poetic Form}
\label{pform}

Such arguments always go in {curly braces} like those shown above. Be careful not to confuse the curly braces on your keyboard with round parentheses ( ), square brackets [ ], or angle brackets < >. They are all different and they do different things.

With commands that take arguments you do not need to use extra white-space after the command, because there is an argument following it which will keep it separate from any normal text with follows after that. The following is therefore perfectly correct (although unusual because it's harder to edit: normally you'd leave a blank line between the chapter title or label and the start of the first paragraph).

\chapter{Poetic Form}\label{pform}The shape of poetry
when written or printed distinguishes it from prose.

2.4.3 White-space in LATEX

In LATEX documents, all multiple spaces, newlines (linebreaks), and TAB characters are treated as if they were a single space or newline during typesetting. LATEX does its own spacing and alignment using the instructions you give it, so you have extremely precise control. You are therefore free to use extra white-space in your editor for optical ease and convenience when editing.

The following is therefore exactly equivalent to the example in the preceding section:

\chapter        {Poetic
Form}\label
{pform}

The shape of poetry when written or printed
distinguishes it from prose.

That is, it will get typeset exactly the same. In general, just leave a blank line between paragraphs and a single space between words and sentences. LATEX will take care of the formatting.

2.5 Special characters

There are ten keyboard characters which have special meaning to LATEX, and cannot be used on their own except for the following purposes:

Key Meaning If you need
the actual character
itself, type:
Character
\ The command character \textbackslash \
$Math typesetting delimiter \$ $% The comment character \% % ^ Math superscript character \^ ^ & Tabular column separator \& & _ Math subscript character \_ _ ˜ Non-breaking space ˜ # Macro parameter symbol \# # { Argument start delimiter$\{${ } Argument end delimiter$\}$} These characters were deliberately chosen, either because they are rare in normal text, or (in the case of$, #, &, and %) they already had an established special meaning on computers as metacharacters (characters standing as symbols for something else) by the time TEX was written, and it would have been misleading to choose others.

2.5.1 Using the special characters

We have already seen (the first paragraph in section 2.4) how to use the backslash to start a command, and curly braces to delimit an argument. The remaining special characters are: