# Formatting information ## A beginner's introduction to typesetting with LA TEX ### Introduction ### Peter Flynn #### Silmaril Consultants Textual Therapy Division v. 3.6 (March 2005)
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 LA TEX 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 LA TEX 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. | This document is Copyright © 1999–2005 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 the section entitled The GNU Free Documentation License. You are allowed to distribute, reproduce, and modify it 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. See the full text of the License in Appendix D.

### Introduction

This book originally accompanied a 2-day course on using the LA TEX typesetting system. It has been extensively revised and updated and can now be used for self-study or in the classroom. It is aimed at users of Linux, Macintosh, or Microsoft Windows but it can be used with LA TEX systems on any platform, including other Unix workstations, mainframes, and even your Personal Digital Assistant (PDA).

#### Who needs this book?

The audience for the original training course was assumed to be computer-literate and composed of professional, business, academic, technical, or administrative computer users. The readers of the book (you) are mostly assumed to be in a similar position, but may also come from many other backgrounds, including hobbyists, students, and just people interested in quality typesetting. You are expected to have one or more of the following or similar objectives:

- producing typesetter-quality formatting;

- formatting long, complex, highly-structured, repetitive, or automatically-generated documents;1

- saving time and effort by automating common tasks;

- achieving or maintaining your independence from specific makes or models of proprietary hardware, software, or file formats (portability);

- using Open Source software (free of restrictions, sometimes also free of charge).

1. LA TEX can easily be used for once-off or short and simple documents as well, but its real strengths lie in consistency and automation.

#### Skills needed

LA TEX is a very easy system to learn, and requires no specialist knowledge, although literacy and some familiarity with the publishing process is useful. It is, however, assumed that you are completely fluent and familiar with using your computer before you start. Specifically, effective use of this document requires that you already know and understand the following very thoroughly:

- how to use a good plain-text editor (not a wordprocessor like OpenOffice, WordPerfect, or Microsoft Word, and not a toy like Microsoft Notepad);

- where to find all 95 of the printable ASCII characters on your keyboard and what they mean, and how to type accents and symbols, if you use them;

- how to create, open, save, close, rename, move, and delete files and folders (directories);

- how to use a Web browser and/or File Transfer Protocol (FTP) program to download and save files from the Internet;

- how to uncompress and unwrap (unzip or detar) downloaded files.

If you don't know how to do these things yet, it's important to go and learn them first. Trying to become familiar with the fundamentals of using a computer at the same time as learning LA TEX is not likely to be as effective as doing them in order.

These are not specialist skills — they are all included in the European Computer Driving Licence (ECDL) and the relevant sections of the ECDL syllabus are noted in the margin above, so they are well within the capability of anyone who uses a computer.

#### Objectives of this book

By the end of this book, you should be able to undertake the following tasks:

- use a plain-text editor to create and maintain your documents;

- add LA TEX markup to identify your document structure and formatting requirements;

- typeset LA TEX documents, correct simple formatting errors, and display or print the results;

- identify, install, and use additional packages (using CTAN for downloading where necessary);

- recognise the limitations of procedural markup systems and choose appropriate generic markup methods where appropriate.

#### Synopsis

The original course covered the following topics as separate sessions, which are represented in the book as chapters:

1. Where to get and how to install LA TEX (teTEX, fpTEX, or proTEXt from the TEX Collection disks);

2. How to type LA TEX documents: using an editor to create files (half a dozen editors for LA TEX);

3. Basic structures (the Document Class Declaration and its layout options; the document environment with sections and paragraphs);

4. Typesetting, viewing, and printing;

5. The use of packages and CTAN to adapt formatting using standard tools;

6. Other document structures (lists, tables, figures, images, and verbatim text);

7. Textual tools (footnotes, marginal notes, cross-references, indexes and glossaries, and bibliographic citations);

8. Typographic considerations (white-space and typefaces; inline markup and font changes; extra font installation and automation);

9. Programmability and automation (macros and modifying LA TEX's behaviour);

10. Conversion and compatibility with other systems (XML, Word, etc.).

A few changes have been made in the transition to printed and online form, but the basic structure is the same, and the document functions as a workbook for the course as well as a standalone self-teaching guide.

#### Where's the math?

It is important to note that the document does not cover mathematical typesetting, complex tabular material, the design of large-scale macros and document classes, or the finer points of typography or typographic design, although it does refer to these topics in passing on a few occasions.

There are several other guides, introductions, and ‘get-started’ documents on the Web and on CTAN which cover these topics and more. Among the more popular are:

- Getting Started with TEX, LA TEX, and friends, where all beginners should start;

- The (Not So) Short Guide to LA TEXε: LA TEXε in 131 Minutes is a good beginner's tutorial;

- A Gentle Introduction to TEX: A Manual for Self-Study is a classic tutorial on Plain TEX;

- Using imported graphics in LA TEXε shows you how to do (almost) anything with graphics: side-by-side, rotated, etc.;

- Short Math Guide for LA TEX gets you started with the American Math Society's powerful packages;

- A comprehensive list of symbols in TEX shows over 2,500 symbols available.

This list was taken from the CTAN search page. There are also lots of books published about TEX and LA TEX: the most important of these for users of this document are listed in the last paragraph in the Foreword.

#### Availability of LA TEX systems

Because the TEX program (the ‘engine’ which actually does the typesetting) is separate from whichever editor you choose, TEX-based systems are available in a variety of different modes using different interfaces, depending on how you want to use them.

##### Graphical interface

The normal way to run LA TEX is to use a toolbar button (icon), a menu item, or a keystroke in your editor. Click on it and your document gets saved and typeset. All the other features of LA TEX systems (the typeset display, spellchecker, related programs like makeindex and BIBTEX) are run the same way. This works both in a normal Graphical User Interface (GUI) as well as in text-only interfaces.

In the popular LA TEX editors like Emacs, TEXshell, TEXnicCenter, WinShell, or WinEdt, a record of the typesetting process is shown in an adjoining window so that you can see the progress of pages being typeset, and any errors or warnings that may occur.2

##### Command-line interface

However, the graphical interface is useless if you want to run LA TEX unattended, as part of an automated system, perhaps in a web server or e-commerce environment, where there is no direct connection between user and program. The underlying TEX engine is in fact a Command-Line Interface (CLI) program, that is, it is used as a ‘console’ program which you run from a standard Unix or Mac terminal or shell window (or from an MS-DOS command window in Microsoft Windows systems). You type the command `latex` followed by the name of your document file (see in section 4.1.2 for an example).

Commands like these let you run LA TEX in an automated environment like a Common Gateway Interface (CGI) script on a web server or a batch file on a document system. All the popular distributions for Unix and Windows, both free and commercial, include this interface as standard (teTEX, fpTEX, MiKTEX, proTEXt, PC-TEX, TrueTEX, etc.).

##### Typeset displays

LA TEX usually displays your typeset results in a separate window, redisplayed automatically every time the document is reprocessed, because the typesetting is done separately from the editing. Some systems, however, can format the typesetting while you type, at the expense of some flexibility.

> Asynchronous typographic displays

>   This method is called an asynchronous typographic display because the typeset window only updates after you have typed something and reprocessed it, not while you are still typing, as it would with a wordprocessor.3

> Synchronous typographic displays

>   Some distributions of LA TEX offer a synchronous typographic interface. In these, you type directly into the typographic display, as with a wordprocessor. Three popular examples are Textures, Scientific Word, and VTEX (see table below). At least one free version (LYX, see Figure 2.1 in section 2.3) offers a similar interface.

>   With a synchronous display you get Instant Textual Gratification™, but your level of control is restricted to that of the GUI you use, which cannot provide access to everything that LA TEX can do. For complete control of the formatting you may still need access to your normal source (input) file in the same way as for asynchronous implementations.

> Near-synchronous displays

>   There are several other methods available free for Unix and some other systems for close-to-synchronous updates of the typeset display (including Jonathan Fine's Instant Preview and the TEX daemon), and for embedding typographic fragments from the typeset display back into the editor window (David Kastrup's preview-latex package).

##### Commercial distributions

Whatever method you choose, the TEX Collection CD and CTAN are not the only source of software. The vendors listed in Table offer excellent commercial implementations of TEX and LA TEX, and if you are in a position where their enhanced support and additional features are of benefit, I urge you to support them. In most cases their companies, founders, and staff have been good friends of the TEX and LA TEX communities for many years.

Table 1. Popular commercial implementations of TEX systems
Product | Platform | Company | URI
--- | --- | --- | ---
PCTEX | MS-Windows | Personal TEX, Inc | `www.pctex.com/`
TrueTEX | MS-Windows | True TEX | `truetex.com/`
Textures | Apple Mac | Blue Sky Research | `www.bluesky.com/`
Scientific Word | MS-Windows | Mackichan Software | `www.mackichan.com/`
VTEX | MS-Windows, Linux, OS/2 | MicroPress, Inc | `www.micropress-inc.com/`

2. Recent versions of some editors hide this display by default unless errors occur in the typesetting.
3. Among other reasons, TEX typesets whole paragraphs at a time, not line-by-line as lesser systems do, in order to get the hyphenation and justification (H&J) right (see section 2.8).

#### Production note

This document is written and maintained in XML, using a customized version of the DocBook DTD. Conversions were made to HTML and LA TEX using XSLT scripts and Michael Kay's Saxon processor.

The complete source, with all ancillary files, is available online at `http://www.ctan.org/tex-archive/info/beginlatex/src/` but if you want to try processing it yourself you must install Java (from Sun, IBM, or a number of others) and Saxon (from `http://saxon.sourceforge.net/`), in addition to LA TEX.

This document is published under the terms and conditions of the GNU Free Documentation License. Details are in this appendix.

#### Symbols and conventions

The following typographic notations are used:

Notation | Meaning
--- | ---
`\command` | Control sequences which perform an action, e.g. `\newpage`
`\length` | Control sequences which store a dimension (measurement in units), e.g. `\parskip`
`counter` | Values used for counting (whole numbers, as opposed to measuring in units), e.g. `secnumdepth`
term | Defining instance of a new term
environment | A LA TEX formatting environment
package | A LA TEX package (available from CTAN)
product | Program or product name
`typewriter type` | Examples of source code (stuff you type)
mybook or value | Mnemonic examples of things you have to supply real-life values for
`x` | A key on your keyboard
`Ctrl`–`x` | Two keys pressed together
`Esc` `q` | Two keys pressed one after another
Submit | On-screen button to click
Menu→Item | Drop-down menu with items

Examples of longer fragments of input are shown with a border round them. Where necessary, the formatted output is shown immediately beneath. Warnings are shown with a shaded background. Exercises are shown with a double border.