Formatting information

A beginner's introduction to typesetting with LATEX

Chapter 4 — Typesetting, viewing and printing

Peter Flynn

Silmaril Consultants
Textual Therapy Division


v. 3.6 (March 2005)

Contents

Introduction
Foreword
Preface
  1. Installing TEX and LATEX
  2. Using your editor to create documents
  3. Basic document structures
  4. Typesetting, viewing and printing
  5. CTAN, packages, and online help
  6. Other document structures
  7. Textual tools
  8. Fonts and layouts
  9. Programmability (macros)
  10. Compatibility with other systems
  1. Configuring TEX search paths
  2. TEX Users Group membership
  3. The ASCII character set
  4. GNU Free Documentation License
References
Index

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 LATEX 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 LATEX 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.

CHAPTER
4

 

Typesetting, viewing and printing

 

  1. Typesetting
  2. Errors and warnings
  3. Screen preview
  4. Printer output
ToC

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.


ToC4.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:

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.

ToC4.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 TEXTEX 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.

ToC4.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 StartProgramsMS-DOS or StartCommand 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.1Command-line usage

ToC4.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.

ToC4.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.

ToC4.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
  1. This only works if you're using an editor which LATEX 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 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.

    ToC4.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.

    ToC4.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.

    ToC4.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!

    ToC4.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!

    ToC4.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 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.

    ToC4.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 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.

    ToC4.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).

    ToC4.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 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).

    ToC4.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.

    ToC4.3.1 Previewing DVI output

    To see the typeset output, click on the dvi Preview toolbar icon or use the TeXTeX 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.1DVI 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.

    ToC4.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.

    ToC4.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 CtrlW  and reload the file with AltF  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.

    ToC4.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 TEXTEX 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.


    Previous Top Next