# Formatting information

## An introduction to typesetting with LATEX

### Peter Flynn

#### Silmaril ConsultantsTextual Therapy Division

v. 5 (December 2009)

#### Contents

Foreword
Preface
References
Index

Earlier editions of ‘Formatting InformationTUGboat’ were prompted by the generous help I 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 any system which is constantly under development. While the core of LATEX is as stable as ever, there been revisions to packages, issues of new distributions, new tools, new interfaces, new books and online 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. ¶ The current edition is the result of a few years of allowing it to lie fallow, accumulating suggestions and finding errors, but taking on board the large number of changes which daily pass in front of all of us who read comp.text.tex, and the sometimes more obvious changes visible when one installs a new version of TEX. ¶ 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 online documents — dealing with mathematical typesetting in TEX and LATEX in finer and better detail than I am capable of (and listed in section 5). ¶ As I was finishing an earlier 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. I was delighted to see at the Practical TEX Conference, in 2006 and later, that more presenters, especially in the Humanities, have stepped up to Peter Flom's challenge. ¶ It is very difficult for people who write technical documentation to remember how they struggled to learn what has now become to them 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. As computer systems become more sophisticated, they require less detailed knowledge from users, even while the takeup of computer usage rises. The result is a generation of users who know what they want, but who are wholly incapable of knowing when they've got it; who have only ever seen one way of doing something, and believe that if the result looks pretty, it means it must be right. As technical writers, we need to explain why, not just how, so if I have obscured something by making unreasonable assumptions about your knowledge, please let me know so that I can correct it.

Peter Flynn has been using structured text systems since the early 1980s and is author of The HTML Handbook and Understanding SGML and XML Tools, and editor of The XML FAQ (all typeset with LATEX). Peter was Ireland's first webmaster, and also runs the text managment consultancy Silmaril. When not TEXing or XMLing, he likes to cook, surf, read science fiction, and listen to Early and Baroque music. In his increasingly fractal spare time he is finishing his PhD on the usability of editors for structured text.

This document is copyright © 1999–2009 by Silmaril Consultants under the terms of what is now the GNU Free Documentation License (copyleft).

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in Appendix D.

You are allowed to distribute, reproduce, and modify this document without fee or further requirement for consent subject to the conditions in section D.5. The author has asserted his right to be identified as the author of this document. If you make useful modifications you are asked to inform the author so that the master copy can be updated for the benefit of others.

CHAPTER
 2

# Using your editor to create documents

LATEX documents are all plain-text files. Originally this meant just the 95 printable characters of the American Standard Code for Information Interchange (ASCII) — see Table C.1 for this — but now it more commonly means ‘printable characters’ in whatever character set is native to your language and culture. Most Roman-based languages are covered by ISO-8859-1 (Western Latin–1), ISO-8859-2 (Western Latin–2) and ISO-8859-15 (Western Latin plus the Euro sign), but there are many others, all now included in Unicode (ISO 10646) which represents all known written human languages.

These are international standards which work everywhere: you should avoid using obsolete manufacturers' proprietary character sets like Microsoft Windows–1252, Apple Macintosh Roman–8, Big5 (Chinese-Japanese-Korean) and the like because they may make your documents unusable on other systems. Most modern computer systems now use Unicode as standard for all plaintext files.

If you stick to Unicode, you can edit your LATEX files 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, and they cannot be used for hiding or transporting virus infections like binary (non-plaintext) 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.

So if LATEX files are all plaintext, how does LATEX know how to format them? The answer is it uses markup: a system of labels which tells LATEX what's what. The LATEX stylesheets recognise the labels and know how to format them, so you don't usually need to add formatting by hand unless you want to do some thing special or out of the ordinary.

## 2.1 Markup

In a LATEX document, you type your text along with markup which identifies the relevant 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.

LATEX markup is all in (American) English, with a few abbreviations for long words to minimise typing, although you normally use a menu or toolbar button, so actually typing it is rare for the beginner.

You do not need to format any of your text in your editor, because LATEX does the formatting all by itself when it typesets. You can of course regularise or neaten its appearance in your editor for your own 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.

## 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 know this stuff yet, then still do this section now, and treat it as part of the learning experience.

1. Install LATEX

See Chapter 1.

2. Create a new, empty document

Open your editor and click on New Document.

Delete any template material it inserts, so that your document is completely empty.

3. Copy the example

Copy and paste the text from Figure 2.1. Make sure you get all of it, and don't change anything.

4. Save the document

Save the document as quickstart.tex

5. Typeset the document

TEXnicCenter users must pick the TeX --> PDF option in the toolbar drop-down menu first!

Click on the Typeset toolbar item for your system as indicated by the black cursor in Figure 2.2.

6. Preview the typesetting

Click on the Preview toolbar item (next to the Typeset icon) if this does not open automatically for you.

7. Print it

Click on the Print toolbar icon in the viewer.

 

If you encounter any errors, it means you do need to read the rest of this chapter after all!

## 2.3 LATEX commands

LATEX commands all begin with a backslash (\) and consist of lowercase letters only.

Do not confuse the backslash with the forward slash (/). They are two different characters. The forward slash is used on the Web and on Unix-based systems (including Macs and GNU/Linux) to separate directory names and filenames. The backslash is used for the same purpose in the Microsoft Windows file system, but you must always use the forward slash in folder and file names in LATEX, even if you use Microsoft Windows.

### 2.3.1 Simple commands

Simple commands are just the command name on its own, after the backslash, for example:

\tableofcontents


This example is an instruction to LATEX to insert the Table of Contents at that point. You would usually use this in a book or report (or perhaps a very long article) somewhere close to the beginning, normally after the title page but before the Preface or Introduction. 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 automatic.

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 treat everything up to the next space as a command, and end up with what it thinks is a command called \tableofcontentsThanks. There's no such command, of course, so LATEX will complain 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 in curly braces (see below) must be followed by white-space before normal text starts again, to keep it separate from the text.

### 2.3.2 Commands with arguments

Many LATEX commands are followed by one or more arguments, meaning information to be acted upon. Here are two examples, a chapter title (see section 3.5) and a cross-reference label (see section 7.4.1):

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


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 mean different things.

With commands that take arguments you do not need to use extra white-space after the command, because the argument in curly braces will keep it separate from any normal text which comes after it. The following example is therefore exactly equivalent to the earlier one above.

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


### 2.3.3 White-space in LATEX

In LATEX documents, all multiple spaces and TAB characters are treated as if they were a single space during typesetting. All multiple newlines (linebreaks) are treated as if they were a single newline. LATEX does its own spacing and alignment using the commands you give it and the layout in the stylesheet, 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 examples in the preceding section (although unusual!):

\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. Try it.

Why would you want odd spacing (or none)? The answer is usually never, but a lot of LATEX is created by computer programs from other systems such as web scripts, XML documents, or databases, and it maks life easier if you don't have to worry about the odd space or two creeping in here and there in normal text: it simply won't have any effect. It also means that you don't have to worry about extra linebreaks between sections or paragraphs, or tabbing in lists of items if you want to use them to make your text easier to edit.

## 2.4 Special characters

There are ten keyboard characters which have special meanings to LATEX, and cannot be used on their own except for the purposes shown in Table 2.1.

Table 2.1Special characters in LATEX
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 have an established special meaning on computers as metacharacters (characters standing as symbols for something else).

### 2.4.1 Using the special characters

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