# Formatting information ## A beginner's introduction to typesetting with LA TEX ### Chapter 4 — Typesetting, viewing and printing ### Peter Flynn #### Silmaril Consultants Textual Therapy Division v. 3.6 (March 2005)
This edition of Formatting Information was prompted by the generous help I have received from TEX users too numerous to mention individually. Shortly after TUGboat published the November 2003 edition, I was reminded by a spate of email of the fragility of documentation for a system like LA TEX which is constantly under development. There have been revisions to packages; issues of new distributions, new tools, and new interfaces; new books and other new documents; corrections to my own errors; suggestions for rewording; and in one or two cases mild abuse for having omitted package X which the author felt to be indispensable to users. ¶ I am grateful as always to the people who sent me corrections and suggestions for improvement. Please keep them coming: only this way can this book reflect what people want to learn. The same limitation still applies, however: no mathematics, as there are already a dozen or more excellent books on the market — as well as other online documents — dealing with mathematical typesetting in TEX and LA TEX in finer and better detail than I am capable of. ¶ The structure remains the same, but I have revised and rephrased a lot of material, especially in the earlier chapters where a new user cannot be expected yet to have acquired any depth of knowledge. Many of the screenshots have been updated, and most of the examples and code fragments have been retested. ¶ As I was finishing this edition, I was asked to review an article for The PracTEX Journal, which grew out of the Practical TEX Conference in 2004. The author specifically took the writers of documentation to task for failing to explain things more clearly, and as I read more, I found myself agreeing, and resolving to clear up some specific problems areas as far as possible. It is very difficult for people who write technical documentation to remember how they struggled to learn what has now become a familiar system. So much of what we do is second nature, and a lot of it actually has nothing to do with the software, but more with the way in which we view and approach information, and the general level of knowledge of computing. If I have obscured something by making unreasonable assumptions about your knowledge, please let me know so that I can correct it. Peter Flynn is author of The HTML Handbook and Understanding SGML and XML Tools, and editor of The XML FAQ. | This document is Copyright © 1999–2005 by Silmaril Consultants under the terms of what is now the GNU Free Documentation License (copyleft). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled The GNU Free Documentation License. You are allowed to distribute, reproduce, and modify it without fee or further requirement for consent subject to the conditions in section D.5. The author has asserted his right to be identified as the author of this document. If you make useful modifications you are asked to inform the author so that the master copy can be updated. See the full text of the License in Appendix D.

CHAPTER
4
| # Typesetting, viewing and printing

We've now got far enough to typeset what you've entered. I'm assuming at this stage that you have typed some sample text in the format specified in the previous chapter, and you've saved it in a plain-text file with a filetype of `.tex` and a name of your own choosing.

> #### Exercise 8. Saving your file

> If you haven't already saved your file, do so now (some editors and interfaces let you typeset the document without saving it!).

> Pick a sensible filename in a sensible directory. Names should be short enough to display and search for, but descriptive enough to make sense. See the panel ‘Picking suitable filenames’ in this chapter for more details.

## 4.1 Typesetting

Typesetting your document is usually done by clicking on a button in a toolbar or an entry in a menu. Which one you click on depends on what output you want — there are two formats available:

- The standard (default) LA TEX program produces a device-independent (DVI) file which can be used with any TEX previewer or printer driver on any make or model of computer. There are dozens of these available: at least one of each (previewer and printer driver) should have been installed with your distribution of TEX.

- The pdfLA TEX program produces an Adobe Acrobat PDF file which can be used with any suitable previewer, such as GSview, PDFview, Xpdf, the Opera browser, or Adobe's own Acrobat Reader.

Depending on which one you choose, you may have to [re]configure your editor so that it runs the right program. They can all do all of them, but they don't always come pre-set with buttons or menus for every possible option, because they can't guess which one you want.

### 4.1.1 Standard LA TEX

There are also two ways of running LA TEX: 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 LA TEX. Command lines are used in non-graphical systems and in automated processes where LA TEX is run unattended (so-called ‘batch’ or ‘scripted’ processing).

Whichever way you run LA TEX, it will process your file and display a log or record of what it's doing (see the example ‘Running LA TEX 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 LA TEX from the toolbar or menu

> Run LA TEX on your file. According to which system you're using this will either be the LA TEX 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 LA TEX 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 LA TEX. If there were no errors, your file is ready for displaying or printing.

### 4.1.2 Running LA TEX 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 LA TEX 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 pdfLA TEX

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

## 4.2 Errors and warnings

LA TEX describes what it's typesetting while it does it, and if it encounters something it doesn't understand or can't do, it will display a message saying what's wrong. It may also display warnings for less serious conditions.

Don't panic if you see error messages: it's very common for beginners to mistype or mis-spell commands, forget curly braces, type a forward slash instead of a backslash, or use a special character by mistake. Errors are easily spotted and easily corrected in your editor, and you can then run LA TEX again to check you have fixed everything. Some of the most common errors are described in section 4.2 with an explanation of how to fix them.

### 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 LA TEX 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 LA TEX finds an error like this, it displays the error message and pauses. You must type one of the following letters to continue:

Key | Meaning
--- | ---
`x` | Stop immediately and exit the program.
`q` | Carry on quietly as best you can and don't bother me with any more error messages.
`e` | Stop the program but re-position the text in my editor at the point where you found the error.a
`h` | Try to give me more help.
`i` | (followed by a correction) means input the correction in place of the error and carry on.b

1. This only works if you're using an editor which LA TEX can communicate with.
2. This is only a temporary fix to get the file processed. You still have to make that correction in the editor.

Some systems (Emacs is one example) run LA TEX 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 LA TEX 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, LA TEX takes the view that the author or editor should be able to contribute. While it is certainly possible to set LA TEX'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 LA TEX 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, LA TEX 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 LA TEX 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.2.3.1 Too many }'s

>     ! Too many }'s.
>     l.6 \date December 2004}

The reason LA TEX thinks there are too many `}`'s here is that the opening curly brace is missing after the `\date` control sequence and before the word `December`, so the closing curly brace is seen as one too many (which it is!).

In fact, there are other things which can follow the `\date` command apart from a date in curly braces, so LA TEX cannot possibly guess that you've missed out the opening curly brace — until it finds a closing one!

#### 4.2.3.2 Undefined control sequence

>     ! Undefined control sequence.
>     l.6 \dtae
>              {December 2004}

In this example, LA TEX is complaining that it has no such command (‘control sequence’) as `\dtae`. Obviously it's been mistyped, but only a human can detect that fact: all LA TEX knows is that `\dtae` is not a command it knows about — it's undefined.

Mistypings are the commonest source of error. If your editor has drop-down menus to insert common commands and environments, use them!

#### 4.2.3.3 Runaway argument

>     Runaway argument?
>     {December 2004 \maketitle
>     ! Paragraph ended before \date was complete.
>     <to be read again>
>                        \par
>     l.8

In this error, the closing curly brace has been omitted from the date. It's the opposite of the error in section 4.2.3.1, and it results in `\maketitle` trying to format the title page while LA TEX is still expecting more text for the date! As `\maketitle` creates new paragraphs on the title page, this is detected and LA TEX complains that the previous paragraph has ended but `\date` is not yet finished.

#### 4.2.3.4 Underfull hbox

>     Underfull \hbox (badness 1394) in paragraph
>     at lines 28--30
>     [][]\LY1/brm/b/n/10 Bull, RJ: \LY1/brm/m/n/10
>     Ac-count-ing in Busi-
>     [94]

This is a warning that LA TEX cannot stretch the line wide enough to fit, without making the spacing bigger than its currently permitted maximum. The badness (0–10,000) indicates how severe this is (here you can probably ignore a badness of 1394). It says what lines of your file it was typesetting when it found this, and the number in square brackets is the number of the page onto which the offending line was printed.

The codes separated by slashes are the typeface and font style and size used in the line. Ignore them for the moment: details are in step 11 if you're curious.

#### 4.2.3.5 Overfull hbox

>     [101]
>     Overfull \hbox (9.11617pt too wide) in paragraph
>     at lines 860--861
>     []\LY1/brm/m/n/10 Windows, \LY1/brm/m/it/10 see
>     \LY1/brm/m/n/10 X Win-

And the opposite warning: this line is too long by a shade over 9pt. The chosen hyphenation point which minimises the error is shown at the end of the line (Win-). Line numbers and page numbers are given as before. In this case, 9pt is too much to ignore (over 3mm or more than 1/8″), and a manual correction needs making (such as a change to the hyphenation), or the flexibility settings need changing (outside the scope of this book).

#### 4.2.3.6 Missing package

>     ! LaTeX Error: File `paralisy.sty' not found.

>     Type X to quit or <RETURN> to proceed,
>     or enter new name. (Default extension: sty)

>     Enter file name:

When you use the `\usepackage` command to request LA TEX to use a certain package, it will look for a file with the specified name and the filetype `.sty`. In this case the user has mistyped the name of the paralist package, so it's easy to fix. However, if you get the name right, but the package is not installed on your machine, you will need to download and install it before continuing (see Chapter 5).

## 4.3 Screen preview

Once the file has been processed without errors (or even if there are still errors, but you want to see what it's doing with them), standard LA TEX will have created a DVI file with the same name as your document but the filetype `.dvi`. If you're using pdfLA TEX, a PDF file will have been created, and you can skip to section 4.3.3.

### 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 LA TEX 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 LA TEX, 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 LA TEX 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 LA TEX 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 LA TEX 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.

## 4.4 Printer output

TEX systems print on almost anything from the simplest dot-matrix printers to the biggest phototypesetters, including all the laser printers and a host of other devices in between. How you do it varies slightly according to how you do your typesetting and previewing:

> If you are using DVI

>   and you have a previewer which has a print function configured for your printer, you can use that. If not, create a PostScript file and use GSview instead.

> If you are using PDF

>   you can print directly from your PDF viewer. Be careful about using the ‘Fit to page’ options, as they will change the size of your document so all your measurements will be different.

> Non-PostScript printers

>   You can create a PostScript file with dvips (see section 4.3.2) and use GSview to print it (GSview can print PostScript files to almost any make or model of non-PostScript printer).

> If you have a real PostScript printer

>   or you are using a system with built-in PostScript printing support (such as Linux or Mac), you can create and send PostScript output directly from your editor to the printer without the need to open it in a previewer first. In Emacs, for example, this is what happens when you use the TEX→TEX Print menu item.

Both the dvips program and all the previewers that print tend to have facilities for printing selected pages, printing in reverse, scaling the page size, and printing only odd or even pages for two-sided work. If you are using PostScript there are programs for manipulating the output (pstops), for example to perform page imposition to get 4, 8, or 16 pages to a sheet for making booklets (psnup).

> #### Exercise 11. Print it!

> Show that you have understood the process of typesetting, previewing, and printing, by displaying your document and printing it.

If you need a non-PostScript/Ghostscript solution, install a separate TEX print driver for your printer. Some may be supplied with your TEX installation, and there are dozens more on CTAN. Their names all start with `dvi` and are followed by an abbreviation for the printer make or model like dvieps for Epson, dvihp for Hewlett-Packard, dvialw for Apple LaserWriters, etc.. Configure the driver to print directly to the print queue, or pipe it to the print queue manually. On Linux with an HP printer, for example, this would be

>     dvihp mydoc | lpr

Microsoft Windows has no easy way to bypass the print spool, but you can do it from an MS-DOS command window with (using a HP printer as an example):

>     dvihp mydoc -o mydoc.hp
>     copy /b mydoc.hp LPT1:

Read the documentation for the driver, as the options and defaults vary.