]> Formatting information A beginner's introduction to typesetting with Peter Flynn Silmaril Consultants Textual Therapy Division March 2005 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 . You are allowed to distribute, reproduce, and modify it without fee or further requirement for consent subject to the conditions in . 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 . This edition of Formatting Information was prompted by the generous help I have received from 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 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 and 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 , which grew out of the Practical 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 and , and editor of . The text is written and maintained in DocBook with a customization layer for typographics. is used to generate (for the Web and plain-text versions) and (for and PostScript). The November 2003 edition was published in . This edition contains extensive revisions and simplifications to the text, and many corrections to the way in which the packages and their capabilities are presented. 3.6 March 2005 Since the publication of the November 2003 edition in , several new books on have been released, and this edition reflects some of the new material and approaches contained in them. See the Bibliography for details of these publications. The only technical change has been to use empty elements for the , , and other logos instead of the more usual entities so that the HTML version can use CSS to produce better logos. Thanks to whoever wrote the CSS for 4ht, which is where I found the styles. 3.5 July 2004 Modified DTD to add span element type to allow use of external entities for formatted , , and other logos in the HTML version. Changed entity declaration in the internal subset to enable this, and switched declarations and marked sections in the DTD. This now means it needs Saxon 7 or 8 to process, as Saxon 6 does not handle parameter entities values used as parameter entity declarations. 3.4 November 2003 Applied all Barbara Beeton's corrections (see separate emails) and rewrote a few formatting macros to allow the document to fit more easily into US Letter shape. It would be nice if it would also format for A5 so that it could become a paperback but that's another day's work. Started on writing the missing sections (Installing Type 1 Fonts and Going beyond , but these are not finished yet) and rewrote entirely the existing (non-) Type 1 font installation procedure in line with the new (unreleased) Gutta-Percha script. Added hidden meanings for Compact Disc Read-Only Memory, Digital Versatile Disk, International Business Machines. 3.3 August 2003 Fixed bug which wrongly lettered appendices. Fixed problem which called wrong font for examples of Times and Helvetica (thanks to William Adams). Updated numerous typos, added comments about pdftex option to color. Rewrote formatting for TUGboat. 3.2 March 2003 Finished rewrite. Revised and expanded almost everything. 3.1 August 2002 Recast in DocBook and reworded some sections. Started the big rewrite. Contents Introduction This book originally accompanied a 2-day course on using the typesetting system. It has been extensively revised and updated and can now be used for self-study or in the classroom. It is aimed at users of Linux, Macintosh, or Microsoft Windows but it can be used with systems on any platform, including other Unix workstations, mainframes, and even your Personal Digital Assistant.
Who needs this book? The audience for the original training course was assumed to be computer-literate and composed of professional, business, academic, technical, or administrative computer users. The readers of the book (you) are mostly assumed to be in a similar position, but may also come from many other backgrounds, including hobbyists, students, and just people interested in quality typesetting. You are expected to have one or more of the following or similar objectives: producing typesetter-quality formatting; formatting long, complex, highly-structured, repetitive, or automatically-generated documents; can easily be used for once-off or short and simple documents as well, but its real strengths lie in consistency and automation. saving time and effort by automating common tasks; achieving or maintaining your independence from specific makes or models of proprietary hardware, software, or file formats (portability); using Open Source software (free of restrictions, sometimes also free of charge).
Skills needed is a very easy system to learn, and requires no specialist knowledge, although literacy and some familiarity with the publishing process is useful. It is, however, assumed that you are completely fluent and familiar with using your computer before you start. Specifically, effective use of this document requires that you already know and understand the following very thoroughly: how to use a good plain-text editor (not a wordprocessor like OpenOffice, WordPerfect, or Microsoft Word, and not a toy like Microsoft Notepad); 2.1.3 where to find all 95 of the printable characters on your keyboard and what they mean, and how to type accents and symbols, if you use them; 3.2.1.2 how to create, open, save, close, rename, move, and delete files and folders (directories); 2.3 how to use a Web browser and/or File Transfer Protocol program to download and save files from the Internet; 7.3.1.6 how to uncompress and unwrap (unzip or detar) downloaded files. 2.3.7 If you don't know how to do these things yet, it's important to go and learn them first. Trying to become familiar with the fundamentals of using a computer at the same time as learning is not likely to be as effective as doing them in order. These are not specialist skills—they are all included in the European Computer Driving Licence and the relevant sections of the syllabus are noted in the margin above, so they are well within the capability of anyone who uses a computer.
Objectives of this book By the end of this book, you should be able to undertake the following tasks: use a plain-text editor to create and maintain your documents; add markup to identify your document structure and formatting requirements; typeset documents, correct simple formatting errors, and display or print the results; identify, install, and use additional packages (using for downloading where necessary); recognise the limitations of procedural markup systems and choose appropriate generic markup methods where appropriate.
Synopsis The original course covered the following topics as separate sessions, which are represented in the book as chapters: Where to get and how to install (te, fp, or prot from the Collection disks); Live Collection How to type documents: using an editor to create files (half a dozen editors for ); Basic structures (the Document Class Declaration and its layout options; the document environment with sections and paragraphs); Typesetting, viewing, and printing; The use of packages and to adapt formatting using standard tools; Other document structures (lists, tables, figures, images, and verbatim text); Textual tools (footnotes, marginal notes, cross-references, indexes and glossaries, and bibliographic citations); Typographic considerations (white-space and typefaces; inline markup and font changes; extra font installation and automation); Programmability and automation (macros and modifying 's behaviour); Conversion and compatibility with other systems (, Word, &etc;). A few changes have been made in the transition to printed and online form, but the basic structure is the same, and the document functions as a workbook for the course as well as a standalone self-teaching guide.
Where's the math? It is important to note that the document does not cover mathematical typesetting, complex tabular material, the design of large-scale macros and document classes, or the finer points of typography or typographic design, although it does refer to these topics in passing on a few occasions. mathematics There are several other guides, introductions, and get-started documents on the Web and on which cover these topics and more. Among the more popular are: , where all beginners should start; is a good beginner's tutorial; is a classic tutorial on Plain ; shows you how to do (almost) anything with graphics: side-by-side, rotated, &etc;; gets you started with the American Math Society's powerful packages; shows over 2,500 symbols available. This list was taken from the search page. There are also lots of books published about and : the most important of these for users of this document are listed in .
Availability of <LaTeX/> systems Because the program (the engine which actually does the typesetting) is separate from whichever editor you choose, -based systems are available in a variety of different modes using different interfaces, depending on how you want to use them.
Graphical interface The normal way to run is to use a toolbar button (icon), a menu item, or a keystroke in your editor. Click on it and your document gets saved and typeset. All the other features of systems (the typeset display, spellchecker, related programs like makeindex and ) are run the same way. This works both in a normal Graphical User Interface as well as in text-only interfaces. In the popular editors like Emacs, shell, nicCenter, WinShell, or WinEdt, a record of the typesetting process is shown in an adjoining window so that you can see the progress of pages being typeset, and any errors or warnings that may occur. Recent versions of some editors hide this display by default unless errors occur in the typesetting.
Command-line interface However, the graphical interface is useless if you want to run unattended, as part of an automated system, perhaps in a web server or e-commerce environment, where there is no direct connection between user and program. The underlying engine is in fact a Command-Line Interface program, that is, it is used as a console program which you run from a standard Unix or Mac terminal or shell window (or from an MS-DOS command window in Microsoft Windows systems). You type the command latex followed by the name of your document file (see in for an example). Commands like these let you run in an automated environment like a Common Gateway Interface script on a web server or a batch file on a document system. All the popular distributions for Unix and Windows, both free and commercial, include this interface as standard (te, fp, MiK, prot, PC-, True, &etc;).
Typeset displays usually displays your typeset results in a separate window, redisplayed automatically every time the document is reprocessed, because the typesetting is done separately from the editing. Some systems, however, can format the typesetting while you type, at the expense of some flexibility. Asynchronous typographic displays This method is called an asynchronous typographic display because the typeset window only updates after you have typed something and reprocessed it, not while you are still typing, as it would with a wordprocessor. Among other reasons, typesets whole paragraphs at a time, not line-by-line as lesser systems do, in order to get the hyphenation and justification (H&ers;J) right (see ). Synchronous typographic displays Some distributions of offer a synchronous typographic interface. In these, you type directly into the typographic display, as with a wordprocessor. Three popular examples are Textures, Scientific Word, and V (see table below). At least one free version (, see in ) offers a similar interface. With a synchronous display you get Instant Textual Gratification™, but your level of control is restricted to that of the you use, which cannot provide access to everything that can do. For complete control of the formatting you may still need access to your normal source (input) file in the same way as for asynchronous implementations. Near-synchronous displays There are several other methods available free for Unix and some other systems for close-to-synchronous updates of the typeset display (including Jonathan Fine 's Instant Preview and the daemon), and for embedding typographic fragments from the typeset display back into the editor window ( David Kastrup 's preview-latex package).
Commercial distributions Whatever method you choose, the Collection CD and are not the only source of software. The vendors listed in offer excellent commercial implementations of and , and if you are in a position where their enhanced support and additional features are of benefit, I urge you to support them. In most cases their companies, founders, and staff have been good friends of the and communities for many years. commercial implementations Popular commercial implementations of <TeX/> systems Product Platform Company URI PC MS-Windows Personal , Inc True MS-Windows True Textures Apple Mac Blue Sky Research Scientific Word MS-Windows Mackichan Software V MS-Windows, Linux, OS/2 MicroPress, Inc
Production note This document is written and maintained in , using a customized version of the DocBook . Conversions were made to and using scripts and Michael Kay 's Saxon processor. The complete source, with all ancillary files, is available online at but if you want to try processing it yourself you must install Java (from Sun, , or a number of others) and Saxon (from ), in addition to . This document is published under the terms and conditions of the Free Documentation License. Details are in .
Symbols and conventions The following typographic notations are used: Notation Meaning command Control sequences which perform an action, ⪚ newpage length Control sequences which store a dimension (measurement in units), ⪚ parskip counter Values used for counting (whole numbers, as opposed to measuring in units), ⪚ secnumdepth term Defining instance of a new term environment A formatting environment package A package (available from ) product Program or product name typewriter type Examples of source code (stuff you type) mybook or value Mnemonic examples of things you have to supply real-life values for x A key on your keyboard Ctrl x Two keys pressed together Esc q Two keys pressed one after another Submit On-screen button to click MenuItem Drop-down menu with items Examples of longer fragments of input are shown with a border round them. Where necessary, the formatted output is shown immediately beneath. Warnings are shown with a shaded background. Exercises are shown with a double border.
Foreword As noted in , this document accompanies a two-day introductory training course. It became obvious from repeated questions in class and afterwards, as well as from general queries on that many people do not read the s, do not use the web site, do not buy the books and manuals, do not use the newsgroups and mailing lists, and do not download the free documentation. Instead, they try to get by using the training technique known as sitting by Nelly, which involves looking over a colleague's shoulder in the office, lab, library, pub, or classroom, and absorbing all his or her bad habits. In the summer of 2001 I presented a short proposal on the marketing of to the annual conference of the Users Group held at the University of Delaware, and showed an example of a draft brochure designed to persuade newcomers to try for their typesetting requirements. As a result of questions and suggestions, it was obvious that it needed to include a pointer to some documentation, and I agreed to make available a revised form of this document, expanded to be used outside the classroom, and to include those topics on which I have had most questions from users over the years. It turned out to mean a significant reworking of a lot of the material. Some of it appears in almost every other manual and book on but it is essential to the beginner and therefore bears repetition. Some of it appears other forms elsewhere, and is included here because it needs explaining better. And some of it appears nowhere else but this document. I took the opportunity to revise the structure of the training course in parallel with the book (expanding it from its original one day to two days), and to include a more comprehensive index. It is by no means perfect (in both senses), and I would be grateful for comments and corrections to be sent to me at the address given under the credits. I had originally hoped that the version of the document would be processable by any freshly-installed default system, but the need to include font samples which go well beyond the default installation, and to use some packages which the new user is unlikely to have installed, means that this document itself is not really a simple piece of , however simply it may describe the process itself. However, as the careful reader will have already noticed, the master source of the document is not maintained in but in . A future task is therefore to compare the packages required with those installed by default, and flag portions of the document requiring additional features so that an abbreviated version can be generated which can be guaranteed to process even with a basic installation. If you are just starting with , at an early opportunity you should buy or borrow a copy of which is the original author's manual. More advanced users should get the or one of its successors. In the same series there are also the and the . Mathematical users might want to read . Preface Many people discover after years of struggling with wordprocessors and desktop publishing systems, and are amazed to find that has been around for over 25 years and they hadn't heard of it. It's not a conspiracy, just a well-kept secret known only to a few million people, as one anonymous user has put it. Perhaps a key to why it has remained so popular is that it removes the need to fiddle with the formatting while you write. Although playing around with fonts and formatting is attractive to the newcomer, it is completely counter-productive for the serious author or editor who wants to concentrate on writing—ask any journalist or professional writer. A few years ago a new user expressed concern on the newsgroup about learning to write in . Some excellent advice was posted in response to this query, which I reproduce with permission below [the bold text is my emphasis]:
No, the harder part might be writing, period. / is actually easy, once you relax and stop worrying about appearance as a be-all-and-end-all. Many people have become Word Processing Junkies and no longer write documents, they draw them, almost at the same level as a pre-literate 3-year old child might pretend to write a story, but is just creating a sequence of pictures with a pad of paper and box of Crayolas—this is perfectly normal and healthy in a 3-year old child who is being creative, but is of questionable usefulness for, say, a grad student writing a Master's or PhD thesis or a business person writing a white paper, &etc; For this reason, I strongly recommend not using any sort of fancy  crutch. Use a plain vanilla text editor and treat it like an old-fashioned typewriter. Don't waste time playing with your mouse. Note: I am not saying that you should have no concerns about the appearance of your document, just that you should write the document (completely) first and tweak the appearance later…not [spend time on] lots of random editing in the bulk of the document itself.
Learning to write well can be hard, but authors shouldn't have to make things even harder for themselves by using manually-driven systems which break their concentration every few seconds for some footling adjustment to the appearance, simply because the software is incapable of doing it right by itself. Don Knuth originally wrote to typeset mathematics for the second edition of his master-work , and it remains pretty much the only typesetting program to include fully-automated mathematical formatting done the way mathematicians want it. But he also published a booklet called which shows how important it is to think about what you write, and how the computer should be able to help, not hinder. And is much more than math: it's a programmable typesetting system which can be used for almost any formatting task, and has made it usable by almost anyone. Professor Knuth generously placed the entire system in the public domain, so for many years there was no publicity of the commercial kind which would have got noticed outside the technical field. Nowadays, however, there are many companies selling software or services, See, for example, the list of vendors on , and the list of consultants published by . dozens of publishers accepting documents for publication, and hundreds of thousands of users using for millions of documents. A guesstimate. With free software it's impossible to tell how many people are using it, but it's a lot. To count yourself as a or user, visit the Users Group's Counter web site (and get a nice certificate!). There is occasionally some confusion among newcomers between the two main programs, and : is a typesetting program, originally written by Prof Knuth at Stanford around 1978. It implements a macro-driven typesetters' programming language of some 300 basic operations and it has formed the core of many other desktop publishing systems. Although it is still possible to write in the raw language, you need to study it in depth, and you need to be able to write macros (subprograms) to perform even the simplest of repetitive tasks. is a user interface for , designed by Leslie Lamport at Digital Equipment Corporation in 1985 to automate all the common tasks of document preparation. It provides a simple way for authors and typesetters to use the power of without having to learn the underlying language. is the recommended system for all users except professional typographic programmers and computer scientists who want to study the internals of . Both and have been constantly updated since their inception. Knuth has now frozen development of the engine so that users and developers can have a virtually bug-free, rock-stable platform to work with. Knuth still fixes bugs, although the chances of finding a bug in these days approaches zero. Typographic programming development continues with the New Typesetting System, planned as a successor to . The 3 project has taken over development of , and the current version is , which is what we are concentrating on here. Details of all developments can be had from the at Debunking the mythology Naturally, over all the years, a few myths have grown up around , often propagated by people who should know better. So, just to clear up any potential misunderstandings… MYTH: has only got one font Most systems can use any OpenType, TrueType, Adobe (PostScript) Type1 or Type3, or &metafont; font. This is more than most other known typesetting system. 's default font is Computer Modern (based on Monotype Series 8: see ), not Times Roman, and some people get upset because it looks different to Times. Typefaces differ: that's what they're for—get used to it. MYTH: isn't Simply not true. and preview is better than any wordprocessor and most systems. What people mean is that 's typographic display is asynchronous with the edit window. This is only true for the default implementations. See for details of synchronous versions. MYTH: is obsolete Quite the opposite: it's under constant development, with new features being added almost weekly. Check the for messages about recent uploads to . It's arguably more up-to-date than most other systems: had the Euro (&EUR;) before anyone else, it had Inuktitut typesetting before the Inuit got their own province in Canada, and it still produces better mathematics than anything else. More mythology MYTH: is a Unix system People are also heard saying: is a Windows system, is a Mac system, &etc;, &etc; ad nauseam. systems run on almost every computer in use, from some of the biggest supercomputers down to handhelds (s like the Sharp Zaurus). That includes Windows and Linux PCs, Macs, and all other Unix systems. If you're using something doesn't run on, it must be either incredibly new, incredibly old, or unbelievably obscure. MYTH: is too difficult This has been heard from physicists who can split atoms; from mathematicians who can explain why π exists; from business people who can read a balance sheet; from historians who can grasp Byzantine politics; from librarians who can understand LoC and MARC; and from linguists who can decode Linear B. It's nonsense: most people grasp in 20 minutes or so. It's not rocket science (or if it is, I know any number of unemployed rocket scientists who will teach it to you). MYTH: is only for scientists and mathematicians Untrue. Although it grew up in the mathematical and computer science fields, two of its biggest growth areas are in the humanities and business, especially since the rise of brought new demands for automated web-based typesetting. Installing <TeX/> and <LaTeX/> te fp nicCenter MiK Linux Unix Microsoft Windows Mac OS X Apple Mac OS X This course is based on using one of the following distributions of on the 2004 Collection DVD or the 2003 Live CD: te for Linux and other Unix-like systems, including Mac OS X ( Thomas Esser ); prot for Microsoft Windows ( Thomas Feuerstack ), based on Christian Schenk's Mik; fp for Microsoft Windows ( Fabrice Popineau ) from the 2003 Live CD. Many other implementations of , such as Tom Kiffe 's CMac for the Apple Macintosh, can be downloaded from . is included with all modern distributions of . The Collection CD is issued annually on behalf of most of the local user groups around the world (see for addresses), and edited by Sebastian Rahtz , Karl Berry , Manfred Lotz , and the authors of the software mentioned above. These people give an enormous amount of their personal time and energy to building and distributing these systems, and they deserve the thanks and support of the user community for all they do. There are many other distributions of both free and commercial, as described in : they all process identically, but there are some differences in size, speed, packaging, and (in the case of commercial distributions) price, support, and extra software provided. One final thing before we start: publicly-maintained software like is updated faster than commercial software, so always check to see if there is a more recent version of the installation. See for more details. Editing and display When you install you will have the opportunity to decide which plain-text editor[s] you want to use to create and maintain your documents which preview programs you want to use to see your typesetting . This isn't much use to you if you're unfamiliar with editors and previewers, so have a look at the table below, and maybe flip ahead to for a moment, where there are descriptions and screenshots. The best bet is probably to install more than one—if you've got the disk space—or maybe all of them, because you can always delete the ones you don't like. Editors There is a wide range of editors available: probably no other piece of software causes more flame-wars in Internet and other discussions than your choice of editor. It's a highly personal choice, so feel free to pick the one you like. My personal biases are probably revealed below, so feel equally free to ignore them. Previewers For displaying your typesetting before printing, you will need a previewer. All systems come with a previewer for standard , but if you are intending to produce industry-standard PostScript or (Adobe Acrobat) files you will need a previewer for those formats. GSview displays both PostScript and files; xpdf and Adobe's own Acrobat Reader just display files. For brief details of some of the most popular editors used for , see . Additional downloads For licensing reasons, the GSview PostScript/PDF previewer, the Acrobat Reader PDF previewer, and the WinEdt editor could not be distributed on the 2003 CDs. In those cases you have to download and install them separately. GSview is available for all platforms from (on Unix and VMS systems it's also available as GhostView and gv: see ) Acrobat Reader (all platforms) can be downloaded from WinEdt (Microsoft Windows only) comes from Installation for Linux and Unix Make sure your system libraries and utilities are up to date. If you are using Red Hat Linux, use yum or up2date to download and install updates. For Debian and other distributions, use apt-get or similar. On Red Hat systems, remove any RPM version of te and associated utilities which may have been preinstalled, in order to avoid version conflicts. If you are installing Live to a new partition, and you have the opportunity to reformat the partition before use, use mkfs with a granularity as small as it will go (usually 1024 bytes). This avoids the partition running out of inodes because uses very large numbers of very small files. Plan the installation carefully if you are installing for multiple users (a shared machine): read for some comments on where to put additional files downloaded later, and see the FAQ on the same topic at Above all, Read The Fine Manual. The documentation is in live.html and live.pdf on the disk in the directory texlive2004/texmf-doc/doc/english/texlive-en/
<TeX/> Live installation manual
# cd /mnt/cdrom/texlive2004 # sh install-tl.sh The installer runs in a shell window, so it can be done even from headless systems (those with no X Window client), but it does need to be installed as root if you want to stick with the default directory locations or install it system-wide for multiple users. To install, just type the commands shown above. The options are mostly self-explanatory, and beginners should pick the recommended scheme and leave all other settings at their defaults. The character-driven interface lets you browse around the settings changing things and looking at options before you commit to installing anything.
The Unix installation program TeX Live installation procedure <================= ===> Note: Letters/digits in indicate menu items <=== ===> for commands or configurable options <=== Proposed platform: Intel x86 with GNU/Linux

over-ride system detection and choose platform binary systems: 1 out of 10 Installation scheme (scheme_recommended) [customizing installation scheme: standard collections language collections] 20 out of 75, disk space required: 246857 kB directories: TEXDIR (The main TeX directory) : /usr/TeX TEXMFLOCAL (Directory for local styles etc): /usr/TeX/texmf-local VARTEXMF (Directory for local config) : /usr/TeX/texmf-var options: [ ] alternate directory for generated fonts () [ ] create symlinks in standard directories [ ] do not install macro/font doc tree [ ] do not install macro/font source tree do not install files, set up to run off CD or DVD start installation help, quit Enter command: ]]>

Collections (the C and L options) are groups of packages that you can include or exclude. It's best to leave this alone unless you know you need something specific. The only options I sometimes set are under O: the alternate directory for generated fonts may need to be on a different partition for performance reasons on a shared system; and I always select create symlinks in standard directories so that the system works immediately after the post-installation configuration (after installation, run texconfig to adjust your local settings.
Running the post-installation program <productname>texconfig</productname>
Note that the Linux/Unix installation does not install any editors: it is assumed you can do this yourself from your distribution's standard package system (most likely you will already be using Emacs or vi anyway). Installation for Apple Mac This is exactly the same interface as for the Linux/Unix installation. You need the bash shell (see the warning in the manual for users of older systems). There is a choice of graphical editors for the Mac: two are included on the DVD, Shop and IMac, but they need to be installed separately, after installing . Installation for Microsoft Windows
<TeX/> Collection 2004 DVD
Before you install , make sure you have enough disk space: the default installation takes about 350Mb on a modern filesystem. The installation assumes you have a fully updated version of Windows, so visit the Microsoft Web site first () and click on Windows Update. Select and install all the relevant updates for your operating system (Windows 95, 98, ME, 2000, NT, or XP). You should be doing this regularly anyway, to keep your system healthy. You may want to run ScanDisk and give your hard disks a full surface check. consists of a very large number of quite small files, so it's important that your disk is in good order. When you insert the distribution DVD or CD, it should start the setup program automatically. If you have auto-run turned off, open My Computer, double-click on the DVD or CD drive, and then double-click Autorun to start the setup program. Some builds of Windows seem to have a bug that stops Autorun starting the installation. In that case (for the Collection 2004 DVD) double-click Setup.exe instead, or (for the Collection 2003 CD) go to the tpm folder and double-click on TeXSetup.exe. pro<TeX/>t (<TeX/> Collection 2004) For prot from the Collection DVD, follow the instructions in the PDF documentation which opens automatically when you start the setup.
pro<TeX/>t 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 MIK either WinEdt (with or without some of its add-ons) or nicCenter GhostScript and GSview . You only need to install items to if you install WinEdt.
First document in <productname><TeX/>nicCenter</productname>
Install <productname>MIK<TeX/></productname> prot uses the MIK distribution as its core, a long-established and popular distribution for Windows. Install <productname>WinEdt</productname> This is optional: it's a good editor, especially for the heavy user of a MIK-based system. This is a free month's trial—after that it reminds you to cough up and register. Install the <productname>WinEdt</productname> 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. Install the <productname>WinEdt</productname> Graphics Interface Another optional add-on for WinEdt to provide drag-and-drop graphics insertion. Install the <productname>WinEdt</productname> Table Designer Last optional add-on for WinEdt, providing a new table editor. Install <productname><TeX/>nicCenter</productname> This is a free equivalent to WinEdt. The interface is slightly different (see ) but it is becoming very popular. Install <productname>GhostScript</productname> and <productname>GSview</productname> 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 prot is nicCenter. This is an Integrated Development Environment 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 . <TeX/> Live (<TeX/> Collection 2003) Once the installation program is running: <LaTeX/> Install itself from the TeXLive SoftwareInstall on Hard Disk menu. If you're new to , 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 Xem Support. Note this unfortunate choice of name is nothing to do with Eberhard Matthes ' MS-DOS implementation of called em—the Xem is short for Xemacs. 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. 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 () 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. GSView Ghostscript is installed automatically, but for GSView you need to go to , and download the most recent version. If you use GSView, please register your copy with Ghostgum, Pty. (). Please read the Live update pages at for details of any changes since the disks were released, and download and install any additional software required. 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 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 , 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. uses a very large number of very small files, so there is a lot of disk activity during an installation. As also recommended in , 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 web site ( 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 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 , 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. Using your editor <?LaTeX \newline{}?>to create documents documents are all plain-text files. Plain-text originally meant just the 95 printable characters of the American Standard Code for Information Interchange—see —but now more commonly includes both these and the relevant 8-bit characters from one (only) character set such as ISO-8859-1 (Western Latin–1) or ISO-8859-15 (Western Latin plus the Euro sign). These are international standards which work everywhere: you should avoid using manufacturers' proprietary character sets like Microsoft Windows–1252 or Apple Macintosh Roman–8, because they may make your documents unusable on some other systems. You can edit them with any editor, and transfer them to any other computer system running and they will format exactly the same. Because they are plain text they cannot corrupt your system, as they cannot be used for hiding or transporting virus infections as binary wordprocessor files can. Everything you can see is in the file and everything in the file is there for you to see: there is nothing hidden or secret and there are no manufacturers' proprietary gotchas like suddenly going out of date with a new version. Markup In a document, you type your text along with markup which identifies the important parts of your document by name, for example title, section, figure, &etc; does all the formatting for you automatically, using the markup to guide its internal rules and external stylesheets for typesetting. Markup This is a term from printing, and originally meant the notes on how to lay the document out, or the instructions which a proofreader might add during correction. It now also means instructions or descriptions added to a computer document to act as guidelines for identification or formatting. Markup has been around for ages. .h1 Interest Rates Runoff c.1970 \section{Interest Rates} 1984 Interest Rates...]]> 1985 Interest Rates]]> 1991 You do not need to format any of your text in your editor, because does it all by itself when it typesets. You can of course regularise or neaten its appearance in your editor for ease of editing (for example, keeping each item in a list on a separate line), but this is not required. You will often hear markup referred to as commands or sometimes control sequences (the proper nical term for them). For all practical purposes these terms all mean the same thing. This course assumes that users have one of shell, nicCenter, WinShell, or WinEdt (Windows only), or Emacs or (any platform) installed. These are discussed briefly in , and the menus and toolbars for running are explained in . Quick start for the impatient If you already know all this stuff about editors and plain-text files and running programs, and you know your system is already correctly installed (including your editor), you'd probably like to type something in and see do its job. If you don't, then skip forward to and read a bit more about first.
Sample document \documentclass[12pt]{article} \usepackage{palatino,url} \begin{document} \section*{My first document} This is a short example of a \LaTeX\ document I wrote on \today. It shows a few simple features of automated typesetting, including \begin{itemize} \item setting the default font size to 12pt; \item specifying `article' type for formatting; \item using the Palatino typeface; \item adding special formatting for URIs; \item formatting a heading in `section' style; \item using the \LaTeX\ logo; \item generating today's date; \item formatting a list of items; \item centering and italicizing; \item autonumbering the pages. \end{itemize} \subsection*{More information} This example was taken from `Formatting Information', which you can download from \url{http://www.ctan.org/tex-archive/info/beginlatex/} and use as a teach-yourself guide. \begin{center} \textit{Have a nice day!} \end{center} \end{document}
Up and running in a few minutes Install the software Make sure you have a properly-installed system and a copy of a suitable editor. Create a sample document Open your editor and type in the text exactly as shown in . Do not make any changes or miss anything out or add anything different at this stage. Save the document Save the document as demo.tex Run <LaTeX/> or <productname>pdf<LaTeX/></productname> Click on the or pdf toolbar icon or the File menu item; or type latex demo or pdflatex demo in a command window. Preview the typesetting Click on the DVI or PDFview toolbar icon or the View menu item; or type your previewer command in a terminal shell. (Note that there may be a pause the first time you use your viewer, while font files are created. previewers use their own font files specially created from the font outlines (TrueType, OpenType, PostScript, &metafont;, etc). The first time you use a font at a size not used before, there will be a second or two's pause while it gets created. The more you use , the less this happens. ) Print it Click on the Print toolbar icon within the viewer, or use the Print menu item, or type dvips -f demo | lpr (Unix/Linux). If you encounter any errors, it means you do need to study this chapter after all! Editors editors All the text of your documents can be typed into your document from a standard keyboard using any decent plain-text editor. However, it is more convenient to use an editor with special features to make using easier. Some of the most popular are shell WinShell, nic Center, and WinEdt (Windows only); and and Emacs (all platforms). <LyX/>
The <LyX/> document editor
The document editor (all platforms) is a special case, as it uses the What You See Is What You Mean model of synchronous typographic editing as opposed to What You See Is What You Get, and many users prefer this interface (but see the reservations in ). 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 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 files by default. It uses its own internal format, and it can export for use in other editors, but the exported files are not designed for human legibility, only for processing. In a co-operative environment this would be a serious drawback, but for the individual user this interface is an excellent tool. <TeX/>shell
The <TeX/>shell 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 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 viewer (there is no provision for , although as it is configurable, that could probably be edited into the menus). Download the .tar.gz file from in the support/TeXshell/ directory and unwrap it into somewhere like C:\Program Files\TeXshell\. Yes, I know I said don't use directory names with spaces in them—and so you shouldn't, for your documents—but Windows programs are usually safe enough in them. There is a tsconfig program in the same directory on , which is designed to help with reconfiguring shell. WinShell
The WinShell editor
This is another free Windows editor for beginners with . Despite its simplicity, it is capable of a considerable amount of document management and assistance with editing. As well as handling stand-alone 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 direct from the toolbar icons or with F-key shortcuts. Both standard and pdf are supported, as well as creation and previewing of PostScript and 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 in the systems/win32/winshell/ directory and double-click it to start the setup. <TeX/>nicCenter
The <TeX/>nicCenter editor
nicCenter 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 , 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 in the systems/win32/TeXnicCenter/ directory and double-click it to start the setup. WinEdt
The <productname>WinEdt</productname> editor
WinEdt is a highly configurable plain-text editor for Windows. It comes with a host of special functions and shortcuts for and , based on the Mik distribution. It is supplied on the Collection 2004 DVD and the prot CD. You can also download it from —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 , and it provides syntactic coloring of 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 generation from 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 fp which came with the 2003 Collection, some editing of the menus is required (explained in the local installation document) because the default setup is for Mik/prot. GNU Emacs
Emacs editing <LaTeX/>
Emacs is a product of the Project. GNU's Not Unix is a project to make a computing environment completely free of restrictions. Versions are available for all makes and models of computer, and it has a -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 and —and it provides a few games as well. Emacs knows about and how to process it, so it comes with a menu full of operations to click on. If you are editing complex documents with mathematics, there is a mode (AUC) which has even more functionality. 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 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. 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. <LaTeX/> commands commands all begin with a backslash (\) Do not confuse the backslash with the forward slash (/). They are two different characters. The forward slash is used on the Web and on Unix systems to separate directory names and filenames. The backslash is used in Microsoft Windows (only) for the same purpose, and in to begin a command. and are usually made up of lowercase letters only, for example: \tableofcontents The tableofcontents command is an instruction to to insert the Table of Contents at this point. You would usually use this in a book or report (or perhaps a very long article) somewhere close to the beginning. You don't have to do anything else. Provided that you have used the sectioning commands described in , all the formatting and numbering for the Table of Contents is completely automated. 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, will try to read it as a command called \tableofcontentsThanks. There's no such command, of course, so will complain at you by displaying an error message (see ). \tableofcontentsThanks to Aunt Mabel for all her help with this book. 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. Commands with arguments Many 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 braces curly braces 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. White-space in <LaTeX/> white-space In documents, all multiple spaces, newlines (linebreaks), and TAB characters are treated as if they were a single space or newline during typesetting. 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. will take care of the formatting. Special characters special characters There are ten keyboard characters which have special meaning to , and cannot be used on their own except for the following purposes: Key Meaning If you need?> the actual character?> itself, type: Character \ The command character textbackslash \ $ Math typesetting delimiter $ $ % The comment character % % ⁁ Math superscript character ⁁ ⁁ &ers; Tabular column separator &ers; &ers; &uline; Math subscript character &uline; \texttt{\_} ˜ Non-breaking space ˜ ˜ &hash; Macro parameter symbol &hash; &hash; { Argument start delimiter { $\{$ } Argument end delimiter } $\}$ These characters were deliberately chosen, either because they are rare in normal text, or (in the case of $, &hash;, &ers;, and %) they already had an established special meaning on computers as metacharacters (characters standing as symbols for something else) by the time was written, and it would have been misleading to choose others. Using the special characters We have already seen () 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 uses for the dollar-sign on its own, if you want to print $35.99 you type \$35.99 % The comment character makes 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 2 . If you need the circumflex accent on a letter like ê, just type the letter or use the symbolic notation \^e. &ers; The ampersand is used in tables to separate columns (see ). If you want to print AT&ers;T you need to type AT\&T. &uline; The underscore lets you type \(r_2\) for r 2 . If you want to underline text (extremely rare in typesetting) see . ˜ 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 &hash; 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 &EUR; needs the marvosym package and is done with the EUR command. 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. Quotation marks quotation marks Do not use the unidirectional typewriter keyboard " key for quotation marks. Correct typographic quotes are got with the ` key and the ' key, doubled if you want double quotes: He said, ``I'm just going out.'' He said, “I'm just going out.” This ensures you get real left-hand and right-hand (opening and closing) quotes (usually shaped like tiny 66 and 99 or as symmetrically-balanced strokes). If you are using Emacs as your editor, the " key is specially programmed in -mode to think for itself and produce correct `` and '' characters (so this is one occasion when you can use the " key). If you are reading this in a browser, or if you have reprocessed the file using different fonts, it may not show you real quotes (some old browser fonts are defective) and the thinspace below may be too wide. Download the typeset () version of this document to see the real effect. When typing one quotation inside another, there is a special command thinspace which provides just enough separation between double and single quotes (a normal space is too much and could allow an unwanted linebreak): He said, `Her answer was ``never''\thinspace'. He said, ‘Her answer was “never” ’. Accents accents For accented letters in western European languages ISO 8859-1 (Latin–1, Western European) to 8859-15 (includes the Euro). or other Latin-alphabet character sets just use the accented keys on your keyboard—if you have the right ones. You must also tell what character repertoire (input encoding) you are using. You specify this by using the inputenc packageWe haven't covered the use of packages yet. Don't worry, see if you're curious. in your preamble with the relevant option. For example, to tell you will be typing ISO Latin–1 accented characters, use: \usepackage[latin1]{inputenc} If you have a real Unicode editor, which lets you insert any letter or symbol from any language on the planet (for example, mixed European, Asian, and other languages), use utf8 instead of latin1. The encoding definitions that are available on your system are in /texmf/tex/latex/base (all files ending in .def). If you don't have accented letters This is for users whose keyboards do not have native accent characters on them. See your Operating System manual for full details. Here are two common examples: Under Linux systems the letter é is usually got with AltGr ; e. Refer to the xkeycaps utility for a table of key codes and combinations (get it from ). Under Microsoft Windows the letter é is got with Ctrl ' e or by holding down the Alt key and typing 0130 on the numeric keypad (not the top row of shifted numerals). Refer to the charmap utility for a table of key codes and combinations (find it in the C:\Windows folder). If you don't have accented letter keys on your keyboard, you'll need to use your operating system's standard keyboard Ctrl or Alt key combinations to generate the characters (see ). If you cannot generate accented characters from your keyboard at all, or if you need additional accents or symbols which are not in any of the keyboard tables, you can use the symbolic notation in . In fact, this can be used to put any accent over any letter: if you particularly want a >ilde; you can have one with the command ˜g (and Welsh users can get ŵ with ⁁w). If you use this symbolic method only, you do not need to use the inputenc package. Before the days of keyboards and screens with their own real accented characters, the symbolic notation was the only way to get accents, so you may come across a lot of older documents (and users!) using this method all the time: it does have the advantage in portability that the file remains plain , which will work on all machines everywhere, regardless of their internal encoding, and even with very old installations. Remember not everyone is lucky enough to be able to install new software: many users on corporate and academic networks still have to use old versions of because their system administrators are too busy to install new ones. Built-in <LaTeX/> accents Accent Example Characters to type Acute (fada) é \'e Grave è \`e Circumflex ê \^e Umlaut or diæresis ë \"e Tilde ñ \~n Macron ō \=o Bar-under ⦵⦵