Top 20 recent searches
Chapter 4
Typesetting, viewing and printing
Picking suitable filenames
Never, ever use directories (folders) or file names which contain spaces. Although your operating system probably supports them, some don't, and they will only cause grief and tears with TEX.
Make filenames as short or as long as you wish, but
strictly avoid spaces. Stick to upper- and lower-case letters
without accents (A–Z and a–z), the digits
0–9, the hyphen (-), and the full
point or period (.), (similar to the
conventions for a Web URI): it will let you
refer to TEX files over the
Web more easily and make your files more portable.
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) LATEX 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 pdfLATEX program produces an Adobe Acrobat PDF file which can be used with any suitable previewer, such as Okular, Foxit, GSview, xpdf, kpdf, 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 Running LATEX
There are 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 (‘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 this section: it looks the same no matter what system you use). This is to let you see where (if!) there are any errors or problems. The log may appear in a subwindow or a new window, depending on your editor.1
Run LATEX on your file. According to which system you're using this will either be the LATEX toolbar icon or the → 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.
It is worth practising running LATEX from a command window even if you normally use a Graphical User Interface (GUI) (one with windows and a mouse), so that you understand what it does. See Figure 4.1 for an example.
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 →→ or → menu item.
When the command window appears, type
cdfollowed by the name of the folder where you saved your sample document, then press the Enter or Return key:cdDocumentslatexquickstartThen type
latexorpdflatexfollowed by the name you gave the sample document, and press the Enter or Return key.
- Some recent versions of Emacs hide the log if there were no errors, and display it only if something went wrong.
4.1.2 Standard LATEX and pdfLATEX
Your editor can be set up to run the original (‘standard’) LATEX and generate DVI files, or to run pdfLATEX and generate PDF files. Both produce identical output, and differ only in the graphics file formats they can handle (see section 6.5), and in some typographic advances like microjustification.
Apple Mac versions of LATEX come preset to produce
PDF files. Emacs
does not have a default menu configured for
pdfLATEX but if you have
already run standard LATEX on the file, you can type the
pdflatex command in the
*TeX-Shell* pane.
4.2 Errors and warnings
LATEX 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 LATEX 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.
Some editors show hotlinks in the LATEX log window where you can click on an error message and the cursor will jump to the line in your document where the error was spotted.
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:
| 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 |
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 — remember to check the list of special characters: many 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 hours as you get used to them.
4.2.3.1 Too many }'s
! Too many }'s. l.6 \date December 2004}
The reason LATEX 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 LATEX 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, LATEX 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 LATEX 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.8In 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 LATEX is still expecting more text for the
date! As
\maketitle creates new paragraphs on the
title page, this is detected and LATEX complains that
the
previous paragraph has ended but \date
is not yet finished.
4.2.3.4 Capacity exceeded
! TeX capacity exceeded, sorry [parameter stack size=5000].
This is rather more serious: it means TEX has completely run out of memory. This will happen if you try to push the system too far, like getting it to read lines which are quite excessively long, or macros which are too complex to fit in memory (or possibly just badly-written). I had it happen once with an author who had written a single paragraph over 37 pages long. I suggested this was perhaps a style that was unfair on his readers...
4.2.3.5 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 LATEX 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.6 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.7 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 LATEX 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 LATEX will have created a
DVI file with the same name as your
document but the filetype
.dvi. If you're using
pdfLATEX, 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 → menu item. A WYSIWYG preview window will appear with your typeset display (see Figure 4.1).
Bitmap preview fonts in DVI viewers
All modern distributions of LATEX use Type 1 Postscript fonts which scale themselves to the right size, but a few older fonts, especially specialist ones, still come in METAFONT format, and need to be recreated the first time they are used at a given size. The first time you display your DVI file using such fonts, there may be a short pause while the previewer creates the bitmaps used for screen previews of these fonts. As you continue to work with them and your system accumulates these font files, the pause for generating them will disappear. If you use pdfLATEX, this pause happens at the end of processing, rather than when you display the document.
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 distributions is used to generate
PostScript files directly from your
DVI output. These
.ps files can be viewed, printed, sent
to a platemaker or filmsetter, put online for
downloading, or converted to PDF or other formats.
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 quickstart.ps quickstart
in a command window (see the example ‘Running LATEX in a terminal or console
window’ in section 4.1.1 for how to use one)
and dvips will create
quickstart.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.
Acrobat Reader is poor at rendering Type 3 (bitmap) fonts. If you are using these (see the warning ‘Bitmap preview fonts in DVI viewers’ in section 4.3.1), 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 portable and domestic dot-matrix printers through normal office ink-jet and laser printers up to the biggest commercial phototypesetters, including a host of other devices in between (numerically-controlled stencil-cutters, knitting machines, and ink-jet cake-decorators, to name but a few).
On most modern systems, printing happens in the normal manner through your system's printer drivers: you just click on the Print icon in your preview. However, TEX's ancillary programs are capable of creating highly-optimised printfiles for almost any printer or typesetter, allowing you to send printout to printers that are not connected to your computer.
The rest of this section deals with how to print on older systems without a print management converter, where the procedure may vary 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 Adobe Acrobat Reader's ‘Shrink to fit’ option, as it will change the size of your document so all your measurements will be different. Turn it off.
- 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 → 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).
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 quickstart | 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 quickstart -o quickstart.hp copy /b quickstart.hp LPT1:
Read the documentation for the driver, as the options and defaults vary.
