1.4.1 proTEXt (TEX Collection 2004)

For proTEXt from the TEX Collection DVD, follow the instructions in the PDF documentation which opens automatically when you start the setup.

---

Figure 1.1: proTEXt comes with its own installation guide

---

The documentation contains links (in large blue type) that you click on in sequence to run the installation process. (This is actually very good: everything worked first time when I did it on XP.) Basically, you need to install a) MIKTEX; b) either WinEdt (with or without some of its add-ons) or TEXnicCenter; and c) GhostScript and GSview.

You only need to install items step 3 to step 5 if you install WinEdt.

---

Figure 1.2: First document in TEXnicCenter

---

1. Install MIKTEX
   

   proTEXt uses the MIKTEX distribution as its core, a long-established and popular distribution for Windows.

2. Install WinEdt
   

   This is optional: it's a good editor, especially for the heavy user of a MIKTEX-based system. This is a free month's trial — after that it reminds you to cough up and register.

3. Install the WinEdt New LATEX Document Interface
   

   Optional again, and only applicable if you installed WinEdt anyway. It lets you save commonly-used document settings for use in other documents of the same type.

4. Install the WinEdt Graphics Interface
   

   Another optional add-on for WinEdt to provide drag-and-drop graphics insertion.

5. Install the WinEdt Table Designer
   

   Last optional add-on for WinEdt, providing a new table editor.

6. Install TEXnicCenter
   

   This is a free equivalent to WinEdt. The interface is slightly different (see Figure 1.2) but it is becoming very popular.

7. Install GhostScript and GSview
   

   These are essential for viewing the PostScript and PDF output, especially if you don't have any other PDF viewer installed.

You get a choice of editors, but the one which features in proTEXt is TEXnicCenter. This is an Integrated Development Environment (IDE) which lets you manage all the files related to each document. In many cases, of course, you'll only have one (the text itself) but if you are working with anything beyond simple articles, you'll probably have illustrations (images or diagrams), and possibly separate chapter files for larger documents, plus indexes, glossaries, bibliographies, etc. I recommend that you create a new project for each new document, even if it's a single-file article, as I did for the example in Figure 1.2.

1.4.2 TEX Live (TEX Collection 2003)

Once the installation program is running:
1. LATEX
   

   Install LATEX itself from the TeXLive Software→Install on Hard Disk menu. If you're new to LATEX, pick Quick Install on the following screen. This gives you everything you need to get started, and doesn't ask any questions, it just installs it all straight away.

   If you're installing under Windows NT, 2000, or XP, you may want to click on the option to install for all users if you have other users on your system.

   If you want to use Emacs as your editor, click the option for XemTEX Support.²

2. Emacs
   

   After installation, right-click and drag Xemacs.exe from the C:\Program Files\TeXLive\bin\win32 folder out onto your desktop and let go, then pick ‘Create Shortcut’. This places Emacs on your desktop for easy access.

3. WinShell and WinEdt
   

   If you want to install WinShell, run the installer program in the support/winshell directory. For WinEdt you must go to their Web site (http://www.winedt.com/) for a downloadable version.

   You don't have to install just one editor: if you've got the space, install them all so you can try them out. You can always uninstall the ones you don't want afterwards.

4. GSView
   

   Ghostscript is installed automatically, but for GSView you need to go to http://www.cs.wisc.edu/~ghost/gsview/, and download the most recent version.

   If you use GSView, please register your copy with Ghostgum, Pty. (http://www.ghostgum.com.au/).

Please read the TEX Live update pages at http://www.tug.org/texlive/bugs.html for details of any changes since the disks were released, and download and install any additional software required.

2. Note this unfortunate choice of name is nothing to do with Eberhard Matthes' MS-DOS implementation of TEX called emTEX — the ‘Xem’ is short for Xemacs.

1.4.3 Installation problems

It's always annoying when a program that's supposed to install painlessly causes trouble, and none the more so when everyone else seems to have been able to install it without problems. I've installed TEX hundreds of times and very rarely had any difficulties, but these are a few of the occasions when I did.

Bad hard disks

As recommended in section 1.4, run a scan and defragmentation of your hard disk[s] before you start. It should take under an hour on a modern machine unless you have a very large disk, and it may need overnight on an older machine. Clean your CD or DVD drive if it's been in heavy use. TEX uses a very large number of very small files, so there is a lot of disk activity during an installation. As also recommended in section 1.2, if you have the chance to reformat the hard disk, pick the smallest granularity (cluster size) possible.

Registry errors

This only affects Microsoft Windows users. The Registry is where Microsoft want software companies automatically to store details of all the programs you install. Unfortunately the Registry is grossly abused by marketing departments to try and foist undesirable links on you, the user. You will see this with many commercial programs, where a particular type of file you've been able to double-click on for years suddenly runs a different program. Some programs install obsolete or broken copies of program libraries (DLL files), overwriting ones which were working perfectly. Worse, the viruses, trojans, and worms which typically infect unprotected Windows systems can leave unwanted links to web pages, or change some of the ways in which Windows operates. The overall effect can be that the whole machine slows down, or that files which are expected to do one thing do another. The best solution is a thorough Registry clean-out, using one of the many programs available for the purpose.

Use the latest versions

Before installing, check the CTAN web site (http://www.ctan.org/ for any updated copy of the installation program. This is called install-tl.sh for Linux and Mac systems, and Setup.exe for Microsoft Windows (on the TEX Collection 2003 CD it was called TeXSetup.exe). Just occasionally a bug slips through onto the production CD or DVD, and although it's always fixed and notified on comp.text.tex, that's a high-volume newsgroup and even the sharpest eyes may miss an announcement.

Stick to the defaults

Unless you're a computer scientist or a software engineer, I suggest you never change or fiddle with the default directories for installation. I know some of them look odd, but they're that way for a purpose, especially when it comes to avoiding directories will spaces in their names, like the notorious C:\Program Files. Although most modern systems cope happily with spaces in filenames and directory names, they are usually A Bad Design Idea, and should be avoided like the plague (spaces are forbidden in web addresses for the same reason: the people who designed them knew the pitfalls). It may look snazzier to put the installation in My Cute Stuff, but please don't: you'll just make it harder to find, harder to fix problems, and more embarrassing if you have to explain it to someone else trying to help you.

2.3.1 LYX

---

Figure 2.1: The LYX document editor

---

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

---

Figure 2.1: The TEXshell editor

---

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\.³ There is a tsconfig program in the same directory on CTAN, which is designed to help with reconfiguring TEXshell.

3. Yes, I know I said don't use directory names with spaces in them — and so you shouldn't, for your LATEX documents — but Windows programs are usually safe enough in them.

2.3.3 WinShell

---

Figure 2.1: The WinShell editor

---

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

---

Figure 2.1: The TEXnicCenter editor

---

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

---

Figure 2.1: The WinEdt editor

---

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

---

Figure 2.1: Emacs editing LATEX

---

Emacs is a product of the GNU Project.⁴ 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.

4. ‘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.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.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:

$

Because of the special mathematical meaning LATEX uses for the dollar-sign on its own, if you want to print $35.99 you type \$35.99

%

The comment character makes LATEX ignore the remainder of the line in your document, so you can see it in your editor, but it will never get typeset. For example
Today's price per kilo is £22.70 % get Mike to update this
If you want to print 45% you need to type 45\%

^

The caret sign lets you type \(E=mc^2\) to get E=mc². If you need the circumflex accent on a letter like ê, just type the letter or use the symbolic notation \^e.

&

The ampersand is used in tables to separate columns (see section 6.3). If you want to print AT&T you need to type AT\&T.

_

The underscore lets you type \(r_2\) for r2. If you want to underline text (extremely rare in typesetting) see the last paragraph in section 8.2.3.

˜

The tilde prints as a space, but prevents a linebreak ever occurring at that point. It's often used between a person's initials and their surname, eg Prof D.E.~Knuth

#

If you want a hash mark (the octothorpe or American number or ‘pound’ [weight] sign) you type \#. For a pound (sterling) sign £, now nearly obsolete except in the UK and some of its former dependencies, use your £ key or type \textsterling.

While we're on the subject of money, an unusual but interesting serif-font Euro sign € is got with the \texteuro command from the textcomp package. The standard sans-serif € needs the marvosym package and is done with the \EUR command.⁶

6. The European Commission has specified that everyone use the sans-serif design, even in serif text, but this is amazingly ugly and most designers rightly ignore it.

2.8.1 Specifying size units

Most people in printing and publishing habitually use points and picas and ems. Some designers use cm and mm. Many English-language speakers still use inches. You can specify lengths in LATEX in any of these units, plus some others (see Table 2.1).

The em can cause beginners some puzzlement because it's based on the ‘point size’ of the type, which is itself misleading. The point size refers to the depth of the metal body on which foundry type was cast in the days of metal typesetting, not the printed height of the letters themselves. Thus the letter-size of 10pt type in one face can be radically different from 10pt type in another (look at the table in section 8.2, where all the examples are 10pt). An em is the height of the type-body in a specific size, so 1em of 10pt type is 10pt and 1em of 24pt type is 24pt.

Another name for a 1em space is a ‘quad’, and LATEX has a command \quad for leaving exactly that much horizontal space. A special name is given to the 12pt em, a ‘pica’ em, as it has become a fixed measure in its own right.

If you are working with other DTP users, watch out for those who think that Adobe points (bp) are the only ones. The difference is only .27pt per inch, but in 10″ of text (a full page of A4) that's 2.7pt, which is nearly 1mm, enough to be clearly visible if you're trying to align one sample with another.

2.8.2 Hyphenation

LATEX hyphenates automatically according to the language you use (see section 2.8.6). To specify different breakpoints for an individual word, you can insert soft-hyphens (discretionary hyphens, done with \-) wherever you need them, for example:

When in Mexico, we visited Popoca\-tépetl by helicopter.
        

To specify hyphenation points for all occurrences of a word, use the \hyphenation command in your preamble (see the panel ‘The Preamble’ in section 3.4) with one or more words in its argument, separated by spaces. This will even let you break ‘helico-
pter’ correctly. In this command you use normal hyphens, not soft-hyphens.

\hyphenation{helico-pter Popoca-tépetl 
im-mer-sion}
        

If you have frequent hyphenation problems with long, unusual, or technical words, ask an expert about changing the value of \spaceskip, which controls the flexibility of the space between words. This is not something you would normally want to do, as it can change the appearance of your document quite significantly.

If you are using a lot of unbreakable text (see next section and also section 6.6.1) it may also cause justification problems. One possible solution to this is shown in section 9.3.

2.8.3 Unbreakable text

To force LATEX to treat a word as unbreakable, use the \mbox command: \mbox{pneumonoultramicroscopicsilicovolcanoconiosis}.
This may have undesirable results, however, if you change margins or the width of the text: pneumonoultramicroscopicsilicovolcanoconiosis...

To tie two words together with an unbreakable space (hard space), use a tilde (~) instead of the space (see the item ‘˜’ in section 2.5.1). This will print as a normal space but LATEX will never break the line at that point. You should make this standard typing practice for things like people's initials followed by their surname, as in Prof. D. E. Knuth: Prof.\ D.~E.~Knuth.

Note that a full point after a lowercase letter is treated as the end of a sentence, and creates more space before the next word. Here, after ‘Prof.’, it's not the end of a sentence, and the backslash-space forces LATEX to insert just an ordinary word-space because it's OK to break the line after ‘Prof.’, whereas it would look wrong to have initials separated with Prof. D.
E. Knuth broken over a line-end.

2.8.4 Dashes

For a long dash — what printers call an ‘em rule’ like this — use three hyphens typed together, like~--- this, and bind them to the preceding word with a tilde to avoid the line being broken before the dash. It's also common to see the dash printed without spaces—like that: the difference is purely æsthetic. Never use a single hyphen for this purpose.

Between digits like page ranges (35–47), it is normal to use the short dash (what printers call an en-rule) which you get by typing two hyphens together, as in 35--47. If you want a minus sign, use math mode (section 2.9).

2.8.5 Justification

The default mode for typesetting is justified (two parallel margins, with word-spacing adjusted automatically for the best optical fit). In justifying, LATEX will never add space between letters, only between words. There is a special package called so (‘space-out’) if you need special effects like letter-spacing, but these are best left to the expert.

There are two commands \raggedright and \raggedleft which set ragged-right (ranged left) and ragged-left (ranged right). Use them inside a group (see the panel ‘Grouping’ in section 8.2.2) to confine their action to a part of your text.

These modes also exist as ‘environments’ (see the last paragraph in section 3.2) called raggedright and raggedleft which are more convenient when applying this formatting to a whole paragraph or more, like this one.

\begin{raggedleft} 
These modes also exist as environments called raggedright 
and raggedleft which is more convenient when applying this 
formatting to a whole paragraph or more, like this one.
\end{raggedleft}
        

Ragged setting turns off hyphenation. There is a package ragged2e which retains hyphenation in ragged setting, useful when you have a lot of long words.

2.8.6 Languages

LATEX can typeset in the native manner for several dozen languages. This affects hyphenation, word-spacing, indentation, and the names of the parts of documents used as headings (e.g. Table of Contents).

Most distributions of LATEX come with US English and one or more other languages installed by default, but it is easy to add the babel package and specify any of the supported languages or variants, for example:

\usepackage[frenchb]{babel}
...
\selectlanguage{frenchb}
        

Changing the language with babel automatically changes the names of the structural units and identifiers like ‘Abstract’, ‘Index’, etc. to their translated version. For example, using French as above, chapters will start with ‘Chapitre’.¹⁰

10. Note that the babel package also sets the hyphenation patterns provided your version of LATEX has them precompiled (see the start of your log files for a list). For other languages you need to set the hyphenation separately (outside the scope of this book).

3.1.1 Document class options

The default layouts are designed to fit as drafts on US Letter size paper.³ To create documents with the correct proportions for standard A4 paper, you need to specify the paper size in an optional argument in square brackets before the document class name, e.g.

\documentclass[a4paper]{report}
        

The two most common options are a4paper and letterpaper. However, many European distributions of TEX now come preset for A4, not Letter, and this is also true of all distributions of pdfLATEX.

The other default settings are for: a) 10pt type (all document classes); b) two-sided printing (books and reports) or one-sided (articles and letters); and c) separate title page (books and reports only). These can be modified with the following document class options which you can add in the same set of square brackets, separated by commas:

11pt

to specify 11pt type (headings, footnotes, etc. get scaled up or down in proportion);

12pt

to specify 12pt type (again, headings scale);

oneside

to format one-sided printing for books and reports;

twoside

to format articles for two-sided printing;

titlepage

to force articles to have a separate title page;

draft

makes LATEX indicate hyphenation and justification problems with a small square in the right-hand margin of the problem line so they can be located quickly by a human.

If you were using pdfLATEX for a report to be in 12pt type on Letter paper, but printed one-sided in draft mode, you would use:

\documentclass[12pt,letterpaper,oneside,draft]{report}
	

There are extra preset options for other type sizes which can be downloaded separately, but 10pt, 11pt, and 12pt between them cover probably 99% of all document typesetting. In addition there are the hundreds of add-in packages which can automate other layout and formatting variants without you having to program anything by hand or even change your text.

---

  Exercise 1. Create a new document

1. Use your editor to create a new document.

2. Type in a Document Class Declaration as shown above.

3. Add a font size option if you wish.

4. In North America, omit the a4paper option or change it to letterpaper.

5. Save the file (make up a name) ensuring the name ends with .tex

---

3. Letter size is 8½″×11″, which is the trimmed size of the old Demi Quarto, still in use in North America. The other common US office size is ‘Legal’, which is 8½″×14″, a bastard cutting close to the old Foolscap (8¼″×13¼″). ISO standard ‘A’, ‘B’, and ‘C’ paper sizes are still virtually unknown in many parts of North America.

3.5.1 Section numbering

All document divisions get numbered automatically. Parts get Roman numerals (Part I, Part II, etc.); chapters and sections get decimal numbering like this document, and Appendixes (which are just a special case of chapters, and share the same structure) are lettered (A, B, C, etc.).

You can change the depth to which section numbering occurs, so you can turn it off selectively. In this document it is set to 3. If you only want parts, chapters, and sections numbered, not subsections or subsubsections etc., you can change the value of the secnumdepth counter using the the \setcounter command, giving the depth value from the table in section 3.5:

\setcounter{secnumdepth}{1}
        

A related counter is tocdepth, which specifies what depth to take the Table of Contents to. It can be reset in exactly the same way as secnumdepth. The current setting for this document is 2.

\setcounter{tocdepth}{3}
	

To get an unnumbered section heading which does not go into the Table of Contents, follow the command name with an asterisk before the opening curly brace:

\subsection*{Shopping List}
        

All the divisional commands from \part* to \subparagraph* have this ‘starred’ version which can be used on special occasions for an unnumbered heading when the setting of secnumdepth would normally mean it would be numbered.

4.1.1 Standard LATEX

There are also two ways of running LATEX: from the toolbar or menu, or from the command line. Toolbars and menus are most common in graphical systems, and are the normal way to run LATEX. Command lines are used in non-graphical systems and in automated processes where LATEX is run unattended (so-called ‘batch’ or ‘scripted’ processing).

Whichever way you run LATEX, it will process your file and display a log or record of what it's doing (see the example ‘Running LATEX in a terminal or console window’ in section 4.1.2: it looks the same no matter what system you use). This is to let you see where (if!) there are any errors or problems.

---

  Exercise 9. Running LATEX from the toolbar or menu

Run LATEX on your file. According to which system you're using this will either be the LATEX toolbar icon or the TEX→TEX File menu item.

Your editor may suggest you save your file if you haven't already done so. Do it.

---

If LATEX reports any errors — easily identifiable as lines in the log beginning with an exclamation mark (!) — don't panic! Turn to section 4.2, identify what went wrong, and fix it in your input file. Then re-run LATEX. If there were no errors, your file is ready for displaying or printing.

4.1.2 Running LATEX from a command window

This is worth practising even if you normally use a GUI, so that you understand what it does. See Figure 4.1 for an example.

---

  Exercise 10. Running LATEX in a terminal or console window

• Under graphical Unix-based systems (Linux and Mac) you open a command (shell) window by clicking on the shell or screen icon in the control panel at the bottom of your screen.

• Under Microsoft Windows you open a command window by clicking on the Start→Programs→MS-DOS or Start→Command Prompt menu item.

When the command window appears, type

cd documents
latex mybook 
          

Substitute the relevant directory and file name. Remember to press the Enter key at the end of each line.

---

---

Figure 4.1: Command-line usage

---

4.1.3 pdfLATEX

If your editor is set up to generate PDF files direct instead of DVI files, then you can click the pdfLATEX toolbar icon or type the command pdflatex filename in a terminal (console) window. Emacs does not have a default menu configured for pdfLATEX but if you have already run standard LATEX on the file, you can type ther pdflatex command in the *TeX-Shell* pane.

4.2.1 Error messages

The format of an error message is always the same. Error messages begin with an exclamation mark at the start of the line, and give a description of the error, followed by another line starting with the number, which refers to the line-number in your document file which LATEX was processing when the error was spotted. Here's an example, showing that the user mistyped the \tableofcontents command:

! Undefined control sequence.
l.6 \tableofcotnetns
      

When LATEX finds an error like this, it displays the error message and pauses. You must type one of the following letters to continue:

Some systems (Emacs is one example) run LATEX with a ‘non-stop’ switch turned on, so it will always process through to the end of the file, regardless of errors, or until a limit is reached.

4.2.2 Warnings

Warnings don't begin with an exclamation mark: they are just comments by LATEX about things you might want to look into, such as overlong or underrun lines (often caused by unusual hyphenations, for example), pages running short or long, and other typographical niceties (most of which you can ignore until later).

Unlike other systems, which try to hide unevennesses in the text — usually unsuccessfully — by interfering with the letter-spacing, LATEX takes the view that the author or editor should be able to contribute. While it is certainly possible to set LATEX's parameters so that the spacing is sufficiently sloppy that you will almost never get a warning about badly-fitting lines or pages, you will almost certainly just be delaying matters until you start to get complaints from your readers or publishers.

4.2.3 Examples

Only a few common error messages are given here: those most likely to be encountered by beginners. If you find another error message not shown here, and it's not clear what you should do, ask for help.

Most error messages are self-explanatory, but be aware that the place where LATEX spots and reports an error may be later in the file than the place where it actually occurred. For example if you forget to close a curly brace which encloses, say, italics, LATEX won't report this until something else occurs which can't happen until the curly brace is encountered (eg the end of the document!) Some errors can only be righted by humans who can read and understand what the document is supposed to mean or look like.

Newcomers should remember to check the list of special characters in : a very large number of errors when you are learning LATEX are due to accidentally typing a special character when you didn't mean to. This disappears after a few days as you get used to them.

4.3.1 Previewing DVI output

To see the typeset output, click on the dvi Preview toolbar icon or use the TeX→TeX View menu item. A WYSIWYG preview window will appear with your typeset display (see Figure 4.1).

  Bitmap preview fonts in DVI viewers

The first time you display your DVI output with a new installation of TEX, there may be a short pause if the previewer needs to create the special bitmaps used for screen previews of some fonts. These give greater accuracy on low-resolution devices like screens. As you continue to work with LATEX and your system accumulates these font files, the pause for generating them will disappear. Recent versions of TEX work directly with Type 1 fonts, however, and don't have this delay.

---

Figure 4.1: DVI preview

---

Most previewers have a wide range of scaling, zooming, and measuring functions, but remember this is a picture of your output: you cannot edit the image. To change it, you always edit your source text and reprocess the file.

With xdvi and its derivatives like dviview, you can leave the display window open, and after you've reprocessed your document through LATEX, moving your mouse back into the window will make the display update automatically (click your mouse if your windowing system needs a click to focus).

Figure 4.1 shows xdvi displaying a page. With a standard three-button mouse you get three levels of micro-zoom to let you inspect fine details.

4.3.2 Previewing with PostScript

PostScript is a page description language invented by Adobe and used in laser printers and high-end typesetters. It's been the universal standard for electronically-formatted print files for nearly two decades, and all printers and publishers are accustomed to using it. PDF is a descendant of PostScript, and is rapidly taking over, but PostScript itself is still extremely common, largely because it is very robust, and is usually an ASCII file, which makes it very portable and easy to generate (it is actually a programming language in its own right). The drawback is the large size of PostScript files, especially if they contain bitmapped graphics.

The dvips program which comes with all TEX systems is used to generate PostScript files directly from your DVI output. These .ps files can be viewed, printed, sent to a platemaker or filmsetter, or put online for downloading.

DVI viewers cannot render some PostScript graphical manipulations like rotating and deforming, so an alternative to viewing the DVI file direct is to generate a PostScript file and use a PostScript viewer. You may have to to do this for your publisher anyway, and many editors can be configured to do this by default. Look for a dvips toolbar icon or menu entry and click on it.

It's also very simple to do manually: let's assume your LATEX file was called mydoc.tex, so processing it has created mydoc.dvi. Just type:

dvips -o mydoc.ps mydoc
        

in a command window (see the example ‘Running LATEX in a terminal or console window’ in section 4.1.2 for how to use one) and dvips will create mydoc.ps which can be used both for previewing and printing.

To view a PostScript file, you need a PostScript previewer like GSview, which works with the PostScript interpreter Ghostscript, which should have been installed automatically along with your TEX system (if not, install both now: GSview is separately licensed and cannot legally be included in some older TEX distributions, so you may have to download it yourself).

GSview can be set to watch the PostScript file and automatically update the display any time the file is changed, without you even having to click on the window.

4.3.3 Previewing with PDF

The Portable Document Format (PDF) is a derivative of PostScript. Whereas PostScript is a programming language in itself, PDF is in effect the result of processing a document through PostScript: it's a binary file format, extremely compact, and well-supported on all platforms.

If your system is configured to generate PDF files direct instead of DVI files, just open the .pdf file using any PDF previewer or browser.

Most editors are configured to display a toolbar icon which will pop up Acrobat Reader or some other viewer with the current PDF output file.

Adobe's Acrobat Reader cannot automatically update the view if you reprocess your document, in the way that xdvi and GSview can. You have to close the display with Ctrl–W  and reload the file with Alt–F  1.

  Bitmap preview fonts in Acrobat Reader

Acrobat Reader is extremely poor at rendering Type 3 (bitmap) fonts. If you are using these (either in an old LATEX installation which has not been upgraded to Type 1, or with files using specialist fonts only available in Type 3 format), you will see a very fuzzy display at low magnifications. It will print perfectly, but Acrobat Reader's display is disappointing. The solution is to use a better previewer or to upgrade to the Type 1 versions of the fonts if possible, or both. If you need to use Type 3 fonts in PDFs, you probably need to warn your readers to expect a fuzzy display from Acrobat Reader (but good printout), and to change to a better reader if they can.

5.1.1 Using an existing package

To use a package already installed on your system, insert a \usepackage command in your document preamble with the package name in curly braces, as we have already seen in earlier chapters. For example, to use the color package, which lets you typeset in colours (I warned you this was coming!), you would type:

\documentclass[11pt,a4paper,oneside]{report}
\usepackage{color}
\begin{document}
...
\end{document}
        

You can include several package names in one \usepackage command by separating the names with commas, and you can have more than one \usepackage command.

Some packages allow optional settings in square brackets. If you use these, you must give the package its own separate \usepackage command, like geometry shown below:

\documentclass[11pt,a4paper,oneside]{report}
\usepackage{pslatex,palatino,avant,graphicx,color}
\usepackage[margin=2cm]{geometry}
\begin{document}

\title{\color{red}Practical Typesetting}
\author{\color{blue}Peter Flynn\\Silmaril Consultants}
\date{\color{green}December 2005}
\maketitle

\end{document}
        

(Incidentally, this is a rather crude way to do colours in titling on a once-off basis: if it's for a repeatable style we'll see in Chapter 9 how it can be automated and kept out of the author's way.)

Many packages can have additional formatting specifications in optional arguments in square brackets, in the same way as geometry does. Read the documentation for the package concerned to find out what can be done.

---

  Exercise 12. Add colour

Use the color package to add some colour to your document. Stick with primary colours for the moment.

Use the geometry package to change the margins.

Reprocess and print your document if you have a colour printer (monochrome printers should print it in shades of grey).

---

CMYK and RGB are not the only colour models. Uwe Kern's xcolor package defines half a dozen, and includes facilities for converting colour values from one model to another.

5.1.2 Package documentation

To find out what commands a package provides (and thus how to use it), you need to read the documentation. In the texmf/doc subdirectory of your installation there should be directories full of .dvi files, one for every package installed. These can be previewed or printed like any other DVI file (see section 4.3.1). If your installation procedure has not installed the documentation, the DVI files can all be downloaded from CTAN.

Before using a package, you should read the documentation carefully, especially the subsection usually called ‘User Interface’, which describes the commands the package makes available. You cannot just guess and hope it will work: you have to read it and find out.

See the next section for details of how to create the documentation .dvi file for additional packages you install yourself.

---

  Exercise 13. Read all about it

Find and view (or print) the documentation on the geometry package you used in the example ‘Add colour’ in section 5.1.1.

Investigate some of the other package documentation files in the directory.

---

5.2.1 Downloading packages

What you need to look for is always two files, one ending in .dtx and the other in .ins. The first is a DOCTEX file, which combines the package program and its documentation in a single file. The second is the installation routine (much smaller). You must always download both files.

If the two files are not there, it means one of two things:

• Either the package is part of a much larger bundle which you shouldn't normally update unless you change version of LATEX;¹

• or it's one of a few rare or unusual packages still supplied as a single .sty file intended for the now obsolete LATEX 2.09.²

Download both files to a temporary directory. If you use Windows, keep a folder like C:\tmp or C:\temp for this; Mac and Linux systems already have a /tmp directory.

1. For example, there is no color.dtx and color.ins for the color package because it forms part of the graphics bundle, which is installed on all LATEX systems anyway. Such packages change very rarely, as they form part of the core of LATEX and are very stable. In general you should never try to update these packages in isolation.
2. You can try to use these if you wish but they are not guaranteed to work, and have now almost all been replaced by LATEXε versions. Always look for the .dtx and .ins pair of files first.

5.2.2 Installing a package

There are four steps to installing a LATEX package:

1. Extract the files
   

   Run LATEX on the .ins file. That is, open the file in your editor and process it as if it were a LATEX document (which is it), or if you prefer, type latex followed by the .ins filename in a command window in your temporary directory.

   This will extract all the files needed from the .dtx file (which is why you must have both of them present in the temporary directory). Note down or print the names of the files created if there are a lot of them (read the log file if you want to see their names again).

2. Create the documentation
   

   Run LATEX on the .dtx file twice. This will create a .dvi file of documentation explaining what the package is for and how to use it. Two passes through LATEX are needed in order to resolve any internal crossreferences in the text (a feature we'll come onto later). If you prefer to create PDF then run pdfLATEX instead. View or print this file in the usual manner (see section 4.3).

3. Install the files
   

   While the documentation is printing, move or copy the files created in step 1 from your temporary directory to the right place[s] in your TEX local installation directory tree — always your ‘local’ directory tree, a) to prevent your new package accidentally overwriting files in the main TEX directories; and b) to avoid your newly-installed files being overwritten when you next update your version of TEX.

   Table 5.1. Where to put files from packages

   Type	Directory (under texmf-local/)	Description
   .cls	tex/latex/base	Document class file
   .sty	tex/latex/packagename	Style file: the normal package content
   .bst	bibtex/bst/packagename	BIBTEX style
   .mf	fonts/source/public/typeface	METAFONT outline
   .fd	tex/latex/mfnfss	Font Definition files for METAFONT fonts
   .fd	tex/latex/psnfss	Font Definition files for PostScript Type 1 fonts
   .pfb	/fonts/type1/foundry/typeface	PostScript Type 1 outline
   .afm	/fonts/afm/foundry/typeface	Adobe Font Metrics for Type 1 fonts
   .tfm	/fonts/tfm/foundry/typeface	TEX Font Metrics for METAFONT and Type 1 fonts
   .vf	/fonts/vf/foundry/typeface	TEX virtual fonts
   .dvi	/doc	package documentation
   .pdf	/doc	package documentation
   others	tex/latex/packagename	other types of file unless instructed otherwise

   ‘The right place’ sometimes causes confusion, especially if your TEX installation is old or does not conform to the TEX Directory Structure (UNDEFINED ACRONYM). For a TDS-conformant system, this is either a) for LATEX packages, a suitably-named subdirectory of texmf-local/tex/latex/³; or b) a suitably-named subdirectory of texmf-local/ for files like BIBTEX styles which are not just for LATEX but can be used in other TEX systems.

   ‘Suitably-named’ means sensible and meaningful (and probably short). For a package like paralist, for example, I'd call the directory paralist.

   Often there is just a .sty file to move but in the case of complex packages there may be more, and they may belong in different locations. For example, new BIBTEX packages or font packages will typically have several files to install. This is why it is a good idea to create a subdirectory for the package rather than dump the files into misc along with other unrelated stuff.

   If there are configuration or other files, read the documentation to find out if there is a special or preferred location to move them to.

4. Update your index
   

   Finally, run your TEX indexer program to update the package database. This program comes with every modern version of TEX and is variously called texhash, mktexlsr, or even configure, or it might just be a mouse click on a button or menu in your editor. Read the documentation that came with your installation to find out which it is.

This last step is utterly essential, otherwise nothing will work.

---

  Exercise 14. Install a package

Download and install the paralist package (which implements inline lists).

---

The reason this process has not been automated widely is that there are still thousands of installations which do not conform to the TDS, such as old shared Unix systems and some Microsoft Windows systems, so there is no way for an installation program to guess where to put the files: you have to know this. There are also systems where the owner, user, or installer has chosen not to follow the recommended TDS directory structure, or is unable to do so for political or security reasons (such as a shared system where she cannot write to a protected directory).

The reason for having the texmf-local directory (called texmf.local on some systems) is to provide a place for local modifications or personal updates, especially if you are a user on a shared or managed system (Unix, Linux, VMS, Windows NT/2000/XP, etc.) where you may not have write-access to the main TEX installation directory tree. You can also have a personal texmf subdirectory in your own login directory. Your installation must be configured to look in these directories first, however, so that any updates to standard packages will be found there before the superseded copies in the main texmf tree. All modern TEX installations should do this anyway, but if not, you can edit texmf/web2c/texmf.cnf yourself. There is an example in this appendix.

3. See section 5.2.3 for how to create a parallel structure in your local directory if your installation didn't create one for you.

5.2.3 Replicating the TDS

The TEX Directory Structure (TDS) is documented at http://www.tug.org/tds/. I find it useful to make the directory structure of texmf-local the same as that of texmf. Examine the subdirectories of texmf/tex/latex/ for examples. For updates of packages which came with your LATEX distribution (as distinct from new ones you are adding yourself), you can then use the same subdirectory name and position in texmf-local/... as the original used in texmf/....

If you want to create the entire subdirectory structure ready for use, you can do it under Unix with the following commands:

cd /usr/TeX/texmf
find . -type d -exec mkdir -p /usr/TeX/texmf-local/{} \;
        

If you are using Microsoft Windows, you can download Cygwin, which provides you with the standard Unix tools in a shell window. The above command should also work on a Mac running OS X. In all cases, if your installation directory is not /usr/TeX, you need to substitute the actual paths to your texmf and texmf-local directories.

5.3.1 The FAQ

For general queries you should read the Frequently-Asked Questions (FAQ) document so that you avoid wasting online time asking about things for which there is already an easily-accessible answer.

The FAQ is managed by the UK TEX Users Group and can be found at http://www.tex.ac.uk/faq/ .

5.3.2 The TEXhax mailing list

Another support resource is the mailing list texhax@tug.org. Again, feel free to ask questions, but again, try to answer the question yourself first (and say what you've tried in your message).

5.3.3 Web sites

The TEX Users Group, as well as most local user groups, maintains a web site (http://www.tug.org) with lots of information about various aspects of the TEX system. See this appendix for information on joining TUG.

5.3.4 News

The Usenet newsgroup comp.text.tex is the principal forum for other questions and answers about LATEX. Feel free to ask questions, but please do not ask frequently-asked questions: read the FAQ instead. The people who answer the questions do so voluntarily, unpaid, and in their own time, so please don't treat this as a commercial support service.

To access Usenet news, type the following URI into your browser's ‘Location’ or ‘Address’ window: news:comp.text.tex (if your browser doesn't support Usenet news properly, change it for one that does, like Mozilla), or download one of the many free newsreaders.⁴

4. Note that this means newsreaders for the Usenet News (NNTP) service. It does not mean syndication readers for RSS, which are a different thing entirely — these are unfortunately also sometimes referred to as ‘newsreaders’.

5.3.5 Commercial support

If you need commercial levels of support, such as 24-hour phone contact, or macro-writing services, you can buy one of the several excellent commercial versions of TEX, or contact a consultancy which deals with TEX (details on the TUG Web site).

6.2.1 Itemized lists

To create an itemized list, use the the itemize environment:

\begin{itemize}

\item Itemized lists usually have a bullet;

\item Long items use `hanging indentation', 
whereby the text is wrapped with a margin 
which brings it clear of the bullet used in 
the first line of each item;

\item The bullet can be changed for any other 
symbol, for example from the \textsf{bbding} 
or \textsf{pifont} package.

\end{itemize}
          

• Itemized lists usually have a bullet;

• Long items use ‘hanging indentation’, whereby the text is wrapped with a margin which brings it clear of the bullet used in the first line of each item;

• The bullet can be changed for any other symbol, for example from the bbding or pifont package.

The default list bullet is round and solid¹ (舦) which is also available with the command \textbullet if you load the textcomp package. See section 9.6.1 for details of how to change the settings for list item bullets.

1. If your browser font doesn't show it, don't worry: most don't. LATEX will.

6.2.2 Enumerated lists

To create an enumerated list, use the enumerate environment:

\begin{enumerate}

\item Enumerated lists use numbering on each 
item (can also be letters or roman numerals);

\item Long items use `hanging indentation' 
just the same as for itemized lists;

\item The numbering system can be changed for 
any level.

\end{enumerate}
          

1. Enumerated lists use numbering on each item (can also be letters or roman numerals);

2. Long items use ‘hanging indentation’, just the same as for itemized lists;

3. The numbering system can be changed for any level.

See section 6.2.6 for details of how to change the numbering schemes for each level.

In standard LATEX document classes, the vertical spacing between items, and above and below the lists as a whole, is more than between paragraphs. If you want tightly-packed lists, use the mdwlist package, which provides ‘starred’ versions (itemize*, enumerate*, etc).

6.2.3 Description lists

To create a description list, use the description environment:

\begin{description}

\item[Identification:] description lists 
require a topic for each item given in 
square brackets;

\item[Hanging indentation:] Long items use 
this in the same way as all other lists;

\item[Reformatting:] Long topics can be 
reprogrammed to fold onto multiple lines.

\end{description}
          

Identification:

description lists require a topic for each item given in square brackets;

Hanging indentation:

Long items use this in the same way as all other lists;

Reformatting:

Long topics can be reprogrammed to fold onto multiple lines.

All three of these types of lists can have multiple paragraphs per item: just type the additional paragraphs in the normal way, with a blank line between each. So long as they are still contained within the enclosing environment, they will automatically be indented to follow underneath their item.

6.2.4 Inline lists

Inline lists are a special case as they require the use of the paralist package which provides the inparaenum environment (with an optional formatting specification in square brackets):

\usepackage{paralist}
...
\textbf{\itshape Inline lists}, which are 
sequential in nature, just like enumerated 
lists, but are \begin{inparaenum}[\itshape 
a\upshape)]\item formatted within their 
paragraph; \item usually labelled with 
letters; and \item usually have the final
item prefixed with `and' or 
`or'\end{inparaenum}, like this example. 
          

Inline lists, which are sequential in nature, just like enumerated lists, but are a) formatted within their paragraph; b) usually labelled with letters; and c) usually have the final item prefixed with ‘and’ or ‘or’, like this example.

See Chapter 8 for details of the font-changing commands used in the optional argument to inparaenum.

---

  Exercise 15. List practice

Add some lists to your document. Pick any two of the ones described here to practice with.

If you successfully installed paralist in the example ‘Install a package’ in section 5.2.2 then you can use inline lists as described in section 6.2.4.

---

6.2.5 Reference lists and segmented lists

Reference lists are visually indistinguishable from numbered or lettered lists, but the numbering or lettering does not imply a sequence. The numbers or letters are just used as labels so that the items can be referred to from elsewhere in the text (as in ‘see item 501(c)3’). In this sense they are really a kind of sub-sectional division, and LATEX's \paragraph or \subparagraph commands (with appropriate renumbering) would probably be a far better solution than using a list. Label them and refer to them with \label and \ref as for any other cross-reference (see section 7.4).

Segmented lists are a highly specialised structure and outside the scope of this document. For details of their usage, see the the chapter ‘Segmentation and Alignment’ in Guidelines for the Text Encoding Initiative.

6.2.6 Lists within lists

You can start a new list environment within the item of an existing list, so you can embed one list inside another up to four deep. The lists can be of any type, so you can have a description list containing an item in which there is a numbered sub-list, within which there is an item containing a bulleted sub-sub-list.

1. by default an outer enumerated list is numbered in Arabic numerals;

   1. an embedded enumerated list is lettered in lowercase;

      1. a third level is numbered in lowercase Roman numerals;

         1. the fourth level uses uppercase alphabetic letters.

Multiple embedded lists automatically change the bullet or numbering scheme so that the levels don't get confused, and the spacing between levels is adjusted to become fractionally tighter for more deeply nested levels.

These are only defaults and can easily be changed by redefining the relevant set of values. You could also add a fifth and further levels, although I suspect that would mean your document structure needed some careful analysis, as lists embedded five deep will probably confuse your readers.

The values for lists come in pairs: for each level there is a counter to count the items and a command to produce the label:²

Note that each counter and command ends with the Roman numeral value of its level (this is to overcome the rule that LATEX commands can only be made of letters — digits wouldn't work here). To change the format of a numbered list item counter, just renew the meaning of its label:

\renewcommand{\theenumi}{\Alph{enumi}}
\renewcommand{\theenumii}{\roman{enumii}}
\renewcommand{\theenumiii}{\arabic{enumiii}}
        

This would make the outermost list use uppercase letters, the second level use lowercase roman, and the third level use ordinary Arabic numerals. The fourth level would remain unaffected.

---

  Exercise 16. Nesting

Extend your use of lists by nesting one type inside a different one.

---

  Lists: a caution to the unwary

Treat lists with care: people sometimes use tables for labelled information which is really a list and would be better handled as such. They often do this because their wordprocessor has no way to do what they want (usually to place the item label level with the description or explanation) except by using a table, hence they are misled into believing that their text is really a table when it's actually not.

2. In fact, any time you define a counter in LATEX, you automatically get a command to reproduce its value. So if you defined a new counter example to use in a teaching book, by saying \newcounter{example}, that automatically makes available the command \theexample for use when you want to display the current value of example.

6.3.1 Floats

Tables and Figures are what printers refer to as ‘floats’. This means they are not part of the normal stream of text, but separate entities, positioned in a part of the page to themselves (top, middle, bottom, left, right, or wherever the designer specifies). They always have a caption describing them and they are always numbered so they can be referred to from elsewhere in the text.

LATEX automatically floats Tables and Figures, depending on how much space is left on the page at the point that they are processed. If there is not enough room on the current page, the float is moved to the top of the next page. This can be changed by moving the Table or Figure definition to an earlier or later point in the text, or by adjusting some of the parameters which control automatic floating.

Authors sometimes have many floats occurring in rapid succession, which raises the problem of how they are supposed to fit on the page and still leave room for text. In this case, LATEX stacks them all up and prints them together if possible, or leaves them to the end of the chapter in protest. The skill is to space them out within your text so that they intrude neither on the thread of your argument or discussion, nor on the visual balance of the typeset pages. But this is a skill few authors have, and it's one point at which professional typographic advice or manual intervention may be needed.

There is a float package which lets you create new classes of floating object (perhaps Examples or Exercises).

6.3.2 Formal tables

To create a LATEX Table, use the table environment containing a \caption command where you type the caption, and a \label command to give the Table a label by which you can refer to it.

\begin{table}
\caption{Project expenditure to year-end 2006}
\label{ye2006exp}
...
\end{table}
        

Numbering is automatic, but the \label command must follow the \caption command, not precede it. The numbering automatically includes the chapter number in document classes where this is appropriate (but this can of course be overridden). The \caption command has an optional argument to provide a short caption if the full caption would be too long for the List of Tables:

\caption[Something short]{Some very long caption that 
will only look reasonable in the full figure.}
        

6.3.3 Tabular matter

Within a Table, you can either typeset the tabular matter using LATEX, or include a table captured as an image from elsewhere. We will see how to include images in section 6.4 on Figures, where they are more common.

To typeset tabular matter, use the tabular environment. The \begin{tabular} command must be followed by a compulsory second argument in curly braces giving the alignment of the columns. These are specified for each column using one of single letters l, c, and r for left-aligned, centered, or right-aligned text, or the letter p followed by a width argument if you want a long entry to wrap to several lines (a miniature paragraph as a single cell on each row).

TEX's original tabular settings were designed for classical numerical tabulations, where each cell contains a single value. The p specification allows a cell to be a miniature paragraph set to a specific width. These are p column specifications are not multi-row entries, they are single cells which contain multiple lines of typesetting: the distinction is very important. Auto-adjusting space between columns is possible with the tabularx package, but the auto-resizing column widths used in web pages are not available in LATEX.

The array package provides for many other typographic variations such as left-aligned, right-aligned, and centred multi-line columns, and other packages provide decimal-aligned columns, row-spanning and column-spanning, multi-page, and rotated (landscape format) tables.

As an example, a tabular setting with three columns, the first one centered, the second left-aligned, and the third one right-aligned, would therefore be specified as {clr}, as in the example below. Note the use of indentation to make the elements of the table clear for editing, and note also how the typeset formatting is unaffected by this (see Table 6.1).

\begin{table}
  \caption{Project expenditure to year-end 2006}
  \label{ye2006exp}
  \begin{center}
    \begin{tabular}{clr}
      &Item&\EUR\ Amount\\
    \hline
      a)&Salaries (2 research assistants)&28,000\\
      &Conference fees and travel expenses&14,228\\
      &Computer equipment (5 workstations)&17,493\\
      &Software&3,562\\
      b)&Rent, light, heat, etc.&1,500\\\cline{3-3}
      &Total&64,783
    \end{tabular}
    \par\medskip\footnotesize
The Institute also contributes to (a) and (b).
  \end{center}
\end{table}
          

You do not need to format the tabular data in your editor: LATEX does this for you when it typesets the table, using the column specifications you provided. Extra space is automatically added between columns, and can be adjusted by changing the \tabcolsep dimension. Takaaki Ota provides an excellent Tables mode for Emacs which provides a spreadsheet-like interface and can generate LATEX table source code (see Figure 6.1).

---

Figure 6.1: Tables mode for Emacs

---

It is conventional to centre the tabular setting within the Table, using the center environment (note US spelling) or the \centering command. The entries for each cell are separated by an ampersand character (&) and the end of a row is marked by the double-backslash (\\).

The \hline command draws a rule across all columns and the \cline command draws a rule across a range of columns (here, under column three only — the argument needs a range). If used, these commands follow the \\ of the row they apply to. There are some extra formatting commands after the tabular material in the example. These are explained in Chapter 8.

If there is no data for a cell, just don't type anything — but you still need the & separating it from the next column's data. The astute reader will already have deduced that for a table of n columns, there must always be n−1 ampersands in each row. The exception to this is when the \multicolumn command is used to create cells which span multiple columns. There is also a package (multirow) to enable cells to span multiple rows, but both of these techniques are outside the scope of this document.

6.3.4 Tabular techniques for alignment

As mentioned earlier, it's also perfectly possible to typeset tabular matter outside a formal Table, where you want to lay out an informal tabulation between paragraphs where a fully floating formal Table would be unnecessary (these are usually quite short: there are several of them in this document).

Tabular mode can also be used wherever you need to align material side by side, such as in designing letterheads, where you may want your company logo and address on one side and some other information on the other.

By default, LATEX typesets tabular environments inline to the surrounding text, so if you want your alignment displayed by itself, put it inside a positioning environment like center, flushright, or flushleft, or leave a blank line or \par before and after so it gets typeset separately.

There is much more to tabular setting: full details are in the manuals mentioned in the last paragraph in the Foreword. One final note to remind you of the automated crossreferencing features: because the example table is labelled, it can be referenced from anywhere in the document as Table 6.1 just by using \ref{ye2006exp}, regardless of how much the surrounding document or structure is moved or edited.

---

  Exercise 17. Create a tabulation

Create one of the following in your document:

• a formal Table with a caption showing the number of people in your class broken down by age and sex;

• an informal tabulation showing the price for three products;

• the logo (hint: section 6.7.2)

---

6.5.1 Making images

There are two types of image: bitmaps and vectors.

Bitmaps

Bitmap images are made of coloured dots, so if you enlarge them, they go jagged at the edges, and if you shrink them, they go blurry. Bitmaps are fine for photographs, where every dot is a different colour, and no-one will notice if you don't shrink or enlarge too much. Bitmaps for diagrams and drawings, however, are almost always the wrong choice, and often disastrously bad.

Vectors

Vector drawings are made from instructions (eg ‘draw this from here to here, using a line this thick’). They can be enlarged or shrunk as much as you like, and never lose accuracy, because they get redrawn automatically at any size. You can't do photographs as vectors, but it's the only acceptable method for drawings or diagrams.

Vector graphic packages are also better suited for saving your image directly in EPS or PDF format (both of which use vectors internally). All the major graphics-generating packages in all disciplines output vector formats: AutoCAD, ChemDraw, MathCAD, Maple, Mathematica, ArcInfo, and so on. EPS is the universally-accepted format for creating vector graphics for publication, with PDF a close second. Most of the major graphics (drawing) packages can also save as EPS, such as PhotoShop, PaintShop Pro, Adobe Illustrator, Corel Draw, and GIMP. There are also some free vector plotting and diagramming packages available like tkPaint and GNUplot which do the same. Never, ever (except in the direst necessity) save any diagram as a bitmap.

---

Figure 6.1: The diagram from Figure 6.1 shrunk and enlarged

 

---

Bitmap formats like JPG and PNG are ideal for photographs, as they are also able to compress the data substantially without too much loss of quality. However, compressed formats are bad for screenshots, if you are documenting computer tasks, because too much compression makes them blurry. The popular Graphics Interchange Format (GIF) is good for screenshots, but is not supported by TEX: use PNG instead, with the compression turned down to minimum. Avoid uncompressible formats like BMP as they produce enormous and unmanageable files. The Tagged Image File Format (TIFF), popular with graphic designers, should also be avoided because far too many companies have designed and implemented non-standard, conflicting, proprietary extensions to the format, making it virtually useless for transfer between different types of computers (except in faxes, where it's still used in a much stricter version).

---

  Exercise 18. Adding pictures

Add \usepackage{graphicx} to the preamble of your document, and copy or download an image you want to include. Make sure it is a JPG, PNG, or PDF image if you use pdfLATEX, or an EPS image if you use standard LATEX.

Add \includegraphics and the filename in curly braces (without the filetype), and process the document and preview or print it.

Make it into a figure following the example in section 6.4.

Be aware that some DVI previewers are not able to display all types of graphics, and some cannot display colour. For best results, use PDF or PostScript preview.

---

6.5.2 Graphics storage

I mentioned earlier that there was a way to tell LATEX where to look if you had stored images centrally for use in many different documents. The answer is in a command \graphicspath which you supply with an argument giving the name of an additional directory path you want searched when a file uses the \includegraphics command, for example:

\graphicspath{c:\mypict~1\camera}
\graphicspath{/var/lib/images}
\graphicspath{HardDisk:Documents:Reports:Pictures}
	

I've used the ‘safe’ (MS-DOS) form of the Windows My Pictures folder because it's A Bad Idea to use directory names containing spaces (see the panel ‘Picking suitable filenames’ in chapter 4). Using \graphicspath does make your file less portable, though, because file paths tend to be specific both to an operating system and to your computer, like the examples above.

6.6.1 Inline verbatim

To specify a word or phrase as verbatim text in typewriter type within a sentence, use the special command \verb, followed by your piece of text surrounded by any suitable character which does not occur in the text itself. This is a very rare exception to the rule that arguments go in curly braces. I often use the plus sign for this, for example to show a LATEX command, I type \verb+\includegraphics[width=3in]{myhouse}+ in order to display \includegraphics[width=3in]{myhouse}, but sometimes I use the grave accent (backtick or open-quote) or the vertical bar when the phrase already has a plus sign in it, like \verb|\(y=a+2x^2\)| when illustrating the LATEX equation \(y=a+x^2\).

This command has the advantage that it turns off all special characters (see section 2.5) except the one you use as the delimiter, so you can easily quote sequences of characters in any computer syntax without problems. However, LATEX will never break the argument of \verb at a line-end when formatting a paragraph, even if it contains spaces, so if it happens to be long, and falls towards the end of a line, it will stick out into the margin. See section 2.8.2 for more information on line-ends and hyphenation.

The url package avoids this by providing the command \url which works in the same way as \verb, with the argument enclosed in a pair of characters, but performs a hyphenless break at punctuation characters, as in http://www.ucc.ie:8080/cocoon/cc/
docs/siteowner.xml. It was designed for Web URIs,⁵ so it understands their syntax and will never break mid-way through an unpunctuated word, only at slashes and full points. Bear in mind, however, that spaces are forbidden in URIs, so using spaces in \url arguments will fail, as will using other non-URI-valid characters.

5. The original term Uniform Resource Locator (URL) is now strongly deprecated in the Web community in favour of the more accurate Uniform Resource Indicator (URI). For details see http://www.w3.org/Addressing/. Unfortunately the older term still persists, especially in LATEX and XML markup.

6.6.2 Display verbatim

For longer (multiline) chunks of fixed-format text, use the verbatim environment:

\begin{verbatim}
\documentclass[11pt,a4paper,oneside]{report}
\begin{document}

\title{Practical Typesetting}
\author{Peter Flynn\\Silmaril Consultants}
\date{December 2004}
\maketitle

\end{document}
\end{verbatim}
        

Like \verb, this turns off all special characters, so you can include anything at all in the verbatim text except the exact line \end{verbatim}

For more control over formatting, however, I recommend the use of the fancyvrb package, which provides a Verbatim environment (note the capital letter) which lets you draw a rule round the verbatim text, change the font size, and even have typographic effects inside the Verbatim environment. It can also be used in conjunction with the fancybox package (see section 6.7.3), and it can add reference line numbers (useful for chunks of data or programming), and it can even include entire external files.

---

  Exercise 19. Try some fixed-format text

Add your email address and home page URI using the \verb and \url commands. You'll need to \usepackage{url} for the latter.

If you know some programming, try a few lines enclosed in verbatim and Verbatim environments.

---

6.7.1 Boxes of text

Because of this ‘box’ model, LATEX can typeset any text into a box of any width wherever on the page you need it.

The simplest command for small amounts of text is \parbox. This command needs two arguments in curly braces: the first is the width you want the text set to, and the second is the text itself, for example:

\parbox{1in}{Please make sure you send in your 
             completed forms by January 1st 
             next year, or the penalty clause 
             2(a) will apply}
          

Please make sure you send in your completed forms by January 1st next year, or the penalty clause 2(a) will apply

The text is typeset to the required width, and the box is extended downwards for as long as is required to fit the text. Note that the baseline of a \parbox is set to the midpoint of the box; that is, if you include a \parbox in mid-sentence, the centre of the box will be lined up with the line of type currently being set. You can specify that it should be the top or bottom by adding an optional t or b in square brackets before the width. For example, \parbox[t]{1in}{...} will produce

Notice that when setting very narrow measures with type that is too large, the spacing may become uneven and there may be too much hyphenation. Either use \raggedright or reduce the type size, or (in extreme cases) reword the text or break each line by hand. It is rare for LATEX to need this: the example above was deliberately chosen to be obtuse as an illustration.

Where the contents is more extensive or more complicated, you can use the minipage environment.

Within this you can use virtually everything that occurs in normal text (e.g. lists, paragraphs, tabulations, etc.) with the exception of floats like tables and figures. The minipage environment has an argument just like \parbox does, and it means the same: the width you want the text set to.

Note that in minipages and \parboxes, the paragraph indentation (\parindent) is reset to zero. If you need to change it, set it inside the minipage or \parbox using the \setlength command (see section 3.6).

\begin{minipage}{3in}
Please make sure you send in your completed 
forms by January 1st next year, or the 
penalty clause 2(a) will apply.
\begin{itemize}
\item Incomplete forms will be returned to 
you unprocessed.
\item Forms must be accompanied by the 
correct fee.
\item There is no appeal. The adjudicators' 
decision is final.
\end{itemize}
\end{minipage}
          

Please make sure you send in your completed forms by January 1st next year, or the penalty clause 2(a) will apply. Incomplete forms will be returned to you unprocessed. Forms must be accompanied by the correct fee. There is no appeal. The adjudicators' decision is final.

There are two other ways of typesetting text to widths other than the normal text width: you can use a one-row, one-cell tabular environment with the p column type specification, or you can use the \vbox command, which is raw TEX, and outside the scope of this document.

6.7.2 Framed boxes

To put a frame round , use the \fbox command: \fbox{some text}. This works for a few words in mid-line, but the framed box and its contents won't break over the end of a line. To typeset multiline text in a box, put it in a \parbox, or use a minipage or tabular environment as described above, and enclose the whole thing in a \fbox.

\fbox{\begin{minipage}{3in}
This multiline text is more flexible than 
a tabular setting:
\begin{itemize}
\item it can contain any type of normal 
LATEX typesetting;
\item it can be any specified width;
\item it can even have its own 
footnotes\footnote{Like this}.
\end{itemize}
\end{minipage}}
          

This multiline text is more flexible than a tabular setting:

• it can contain any type of normal LATEX typesetting;

• it can be any specified width;

• it can even have its own footnotes.⁶

The spacing between text and box is controlled by the value of \fboxsep, and the thickness of the line by \fboxrule. The following values were used above:

\setlength{\fboxsep}{1em}
\setlength{\fboxrule}{2pt}
        

As we saw before, setting justified text in narrow measures will produce poor spacing: either use the \raggedright command, or change the font size, or add explicit extra hyphenation points.

Note the \begin{tabular} and \begin{minipage} commands still need the width specifying: in the case of the \begin{tabular} by the use of the p column type with its width specification, and in the case of \begin{minipage} by the second argument.

\fbox{\begin{tabular}{p{1in}}
Multiline text in a box typeset using 
\textsf{tabular}
\end{tabular}}
          

Multiline text in a box typeset using tabular

6. Like this.

6.7.3 Sidebars and panels

The fancybox package lets you extend the principle of \fbox with commands to surround text in square, oval (round-cornered), and drop-shadow boxes (e.g. \ovalbox, \shadowbox, etc.: see the documentation for details).

You can create panels of any size with these borders by using the minipage environment to typeset the text inside a special Sbox environment which fancybox defines. The minipage formats the text but the Sbox ‘captures’ it, allowing you to put the frame round it as it prints.

The printed version of this document uses this extensively and there is a useful example shown in section 9.5.

7.4.1 Normal cross-references

You label a place in your document by using the command \label followed by a short name you make up, in curly braces:² we've already seen this done for labelling Figures and Tables.

\section{New Research}
\label{newstuff}
        

You can then refer to this point from anywhere in the same document with the command \ref followed by the name you used, e.g.

In \S~\ref{newstuff} there is a list of recent 
projects.
	  

In § 7.4.1 there is a list of recent projects.

(The \S command produces a section sign (§) and the \P command produces a paragraph sign (¶).)

If the label is in normal text, the reference will provide the current chapter or section number or both (depending on the current document class).³ If the label was inside a Table or Figure, the reference provides the Table number or Figure number prefixed by the chapter number. A label in an enumerated list will provide a reference to the item number. If there is no apparent structure to this part of the document, the reference will be null. Labels must be unique (that is, each value must occur only once as a label within a single document), but you can have as many references to them as you like.

Note the use of the unbreakable space (~) between the \ref and the word before it. This prints a space but prevents the line ever breaking at that point, should it fall close to the end of a line.

The command \pageref followed by any of your label values will provide the page number where the label occurred, regardless of the document structure. This makes it possible to refer to something by page number as well as its \ref number, which is useful to readers in very long documents.

Unresolved references are printed as two question marks, and also cause a warning message at the end of the log file. There's never any harm in having \labels you don't refer to, but using \ref when you don't have a matching \label is an error.

2. This section is labelled ‘normalxref’, for example.
3. Thus I can refer here to \ref{normalxref} and get the value section 7.4.1.

7.4.2 Bibliographic references

The mechanism used for references to reading lists and bibliographies is almost identical to that used for normal cross-references. Although it is possible to type the details of each citation manually, there is a companion program to LATEX called BIBTEX, which manages bibliographic references automatically. This reduces the time needed to maintain and format them, and dramatically improves accuracy. Using BIBTEX means you only ever have to type the bibliographic details of a work once. You can then cite it in any document you write, and it will get formatted automatically to the style you specify.

7.4.2.3 BIBTEX format

The format for the BIBTEX file is specified in the BIBTEX documentation (see section 5.1.2 for how to find and print it). You create a file with a name ending in .bib, and add your entries, for example:

@book{fg,
   title        = {{An Innkeeper's Diary}},
   author       = {John Fothergill},
   edition      = {3rd},
   publisher    = {Penguin},
   year         = 1929,
   address      = {London}
}
          

There is a prescribed set of fields for each of a dozen or so types of document: book, article (in a journal), article (in a collection), chapter (in a book), thesis, report, paper (in a Proceedings), etc. Each entry identifies the document type after the ‘@’ sign, followed by the entry label that you make up, and then each field (in any order), using the format:

keyword = {value},
          

Most TEX-sensitive editors have a BIBTEX mode which understands these entries. Emacs automatically uses its bibtex-mode whenever you open a filename ending in .bib. When editing BIBTEX databases, the rules are simple:

• Omit the comma after the last field in the entry (only — eg after {London} in the example).

• Titles may have their case changed in some styles: to prevent this, enclose the title in double curly braces as in the example.

• Values which are purely numeric (e.g. years) may omit the curly braces.

• Fields can occur in any order but the format must otherwise be strictly observed.

• Fields which are not used do not have to be included (so if your editor automatically inserts them as blank or prefixed by OPT [optional], you can safely delete them as unused lines).

To help with this, there are several interfaces to creating and maintaining BIBTEX files, such as tkbibtex (see Figure 7.1), or pybliographic.

---

Figure 7.1: tkBIBTEX, one of several graphical interfaces to BIBTEX databases

---

4. The style shown in the example here provides formatting according to the specifications for Transactions of the IEEE (revised).

8.1.1 Spacing

We mentioned in section 7.3 and elsewhere the existence of the geometry package which lets you change margins. It also lets you set the text-area height and width and a lot of other layout settings: read the documentation for details (see section 5.1.2 for how to read package documentation).

\usepackage[left=2cm,top=1cm,bottom=2cm,right=3cm,
            nohead,nofoot]{geometry}
        

The spacing around the individual textual components (headings, paragraphs, lists, footnotes, etc.) can also be changed on a document-wide basis, as we saw with paragraph spacing and indentation in the text in section 3.6.

Changing the spacing of section headings for the whole document can be done with the sectsty package, designed to let you adjust section-head spacing without having to know about the internal LATEX coding, which is quite complex.

The spacing for lists can be adjusted with the mdwlist package. In both cases the user with highly specific requirements such as a publisher's Compositor's Specification should read the relevant sections in the The LATEX Companion or ask for expert help, as there are many internal settings which can also be changed to fine-tune your design, but which need some knowledge of LATEX's internals.

All the above are for automating changes so that they occur every time in a consistent manner. You can also make manual changes whenever you need:

Flexible vertical space

There are three commands \smallskip, \medskip, and \bigskip. These output flexible (dynamic, or ‘rubber’) space, approximately 3pt, 6pt, and 12pt high respectively, and they will automatically compress or expand a little, depending on the demands of the rest of the page (for example to allow one extra line to fit, or a heading to be moved to the next page without anyone except a typographer noticing the change). These commands can only be used after a paragraph break (a blank line or the command \par).

Fixed vertical space

For a fixed-height space which will not stretch or shrink, use the command \vspace followed by a length in curly braces, e.g. \vspace{18pt} (again, this has to be after a paragraph break). Bear in mind that extra space which ends up at a page-break when the document is formatted will get discarded entirely to make the bottom and top lines fall in the correct places. To force a vertical space to remain and be taken into account even after a page break (very rare), use the starred variant \vspace*, e.g. \vspace*{19pt}.

Double spacing

Double-spacing normal lines of text is usually a bad idea, as it looks very ugly. It is still unfortunately a requirement in some universities for thesis submission, a historical relic from the days of typewriters. Nowadays, 1⅓ or 1½ line spacing is considered acceptable, according to your font size. If your institution still thinks they should have double line spacing, they are probably wrong, and just don't understand that the world has moved on since the typewriter. Show them this paragraph and explain that they need to enter the 21st century and adapt to the features of computer typesetting. If they still insist, use the setspace package,which has commands for double line-spacing and one-and-a-half line spacing, but be prepared for some very ugly output (so warn your supervisor and extern).

The space between lines is defined by the value of the length variable \baselineskip multiplied by the value of the \baselinestretch command. In general, don't meddle with \baselineskip at all, and with \baselinestretch only if you know what you are doing. (Both can, however, safely be used as reference values in commands like \vspace{\baselineskip} to leave a whole line space.)

The value of \baselineskip changes with the font size (see section 8.2.4) but is conventionally set to 1.2 times the current nominal font size. This is a value derived from long experience: only change it if you understand what it means and what effect it will have.

Quite separately, there are some perfectly genuine and normal reasons for wanting wide line spacing, for example when typesetting a proof of a critical or variorum edition, where editors and contributors are going to want to add notes manually by writing between the lines, or where the text is going to be overprinted by something else like Braille, or in advertising or display text for special effects.

Horizontal space

There is a horizontal equivalent to the \vspace command: \hspace, which works in the same way, so I can force a 1″ space like thisin mid-paragraph. There are also some predefined (shorter) spaces available:

• \thinspace (1/6em), which we saw between single and double quotes in the last paragraph in section 2.6. It's also sometimes used between the full point after abbreviations and a following number, as in page references like p. 199, where a word space would look too big, and setting it solid would look too tight.

• \enspace (½em). There is no direct equivalent predefined in LATEX for mid and thick spaces as used by metal typesetters, although it would be possible to define them. The en as a unit is often used as the width of a single digit in some fonts, as a convenience so that tables of figures are easy to line up.

• \quad (1em).

• \qquad (2em).

Beyond this, all horizontal space within paragraphs is automatically flexible, as this is what LATEX uses to achieve justification. Never be tempted to try and change the spacing between letters unless you have some professional training in typography. Some systems use letterspacing (incorrectly called ‘tracking’) as an aid to justification and it is almost always wrong to do so (and looks it). While it is possible to change letterspacing (with the soul package), it should only be done by a typographer, and then only very rarely, as the settings are very subtle and beyond the scope of this book.