summaryrefslogtreecommitdiff
path: root/info/beginlatex/src/beginlatex.xml
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /info/beginlatex/src/beginlatex.xml
Initial commit
Diffstat (limited to 'info/beginlatex/src/beginlatex.xml')
-rw-r--r--info/beginlatex/src/beginlatex.xml13330
1 files changed, 13330 insertions, 0 deletions
diff --git a/info/beginlatex/src/beginlatex.xml b/info/beginlatex/src/beginlatex.xml
new file mode 100644
index 0000000000..5032e7bf7f
--- /dev/null
+++ b/info/beginlatex/src/beginlatex.xml
@@ -0,0 +1,13330 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE book PUBLIC
+ "+//Silmaril//DTD DocBook 4.2 Adapted for Typographic Systems//EN//XML"
+ "typebook.dtd" [
+<!ENTITY % target "latex">
+]>
+
+<?PSGML NOFILL programlisting ?>
+
+<!-- REMINDER of some [ab]uses of DocBook in this document type:
+
+ <command> is for LaTeX control sequences, typed with no backslash
+ <literal> is for the same where you don't want them indexed
+ <methodname> is used for packages
+ <modespec> is used for environments
+ <example> is used for exercises
+ <releaseinfo> in biblioentries is used for URIs
+ type= in <ulink> is used for mail/news methods (with
+ colon)
+ <informaltable colsep="..."> is used for the top row strut
+ separator
+ <caution> is abused to hold text needing a \parbox in LaTeX
+
+ <acronym id="..."> is a defining instance
+ <acronym ref="..."> is a reference to it
+
+ See the DTD modification layer for details of other changes.
+
+ Remember, because of vagaries in the way XSLT handles character
+ entity references, only use &amp; inside <literal>. In normal
+ text, use the homebrew &ampers; instead.
+
+-->
+
+<book id="null">
+ <bookinfo>
+ <title>Formatting information</title>
+ <subtitle>A beginner&apos;s introduction to typesetting with
+ <LaTeX/></subtitle>
+ <author>
+ <firstname>Peter</firstname>
+ <surname>Flynn</surname>
+ <affiliation>
+ <orgname>Silmaril Consultants</orgname>
+ <orgdiv>Textual Therapy Division</orgdiv>
+ </affiliation>
+ </author>
+ <edition>March 2005</edition>
+ <legalnotice>
+ <para>This document is Copyright &copy; 1999&ndash;2005 by
+ Silmaril Consultants under the terms of what is now the GNU
+ Free Documentation License (copyleft).</para>
+ <para>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 <citetitle
+ ref="gnufdl"></citetitle>.</para>
+ <para>You are allowed to distribute, reproduce, and modify it
+ without fee or further requirement for consent subject to the
+ conditions in <xref linkend="gfdl-4"/>. 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 <xref linkend="gfdl"/>.
+ </para>
+ </legalnotice>
+ <othercredit>
+ <contrib>This edition of <citetitle ref="null">Formatting
+ Information</citetitle> 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.</contrib>
+ <contrib>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&mdash;as well as other online
+ documents&mdash;dealing with mathematical typesetting in
+ <TeX/> and <LaTeX/> in finer and better detail than I am
+ capable of.</contrib>
+ <contrib>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.</contrib>
+ <contrib>As I was finishing this edition, I was asked to review
+ an article for <citetitle ref="practex"></citetitle>, 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
+ <emphasis>your</emphasis> knowledge, please let me know so
+ that I can correct&nbsp;it.</contrib>
+ <authorblurb>
+ <para>Peter Flynn is author of <citetitle show="none"
+ ref="htmlbook"></citetitle> and <citetitle show="none"
+ ref="sgmltools"></citetitle>, and editor of <citetitle
+ ref="xmlfaq" show="none"></citetitle>.</para>
+ </authorblurb>
+ </othercredit>
+ <releaseinfo>The text is written and
+ maintained in DocBook with a customization layer for
+ typographics. <acronym ref="XSLT"></acronym> is used to generate
+ <acronym ref="HTML"></acronym> (for the Web and plain-text
+ versions) and <LaTeX/> (for <acronym ref="PDF"></acronym> and
+ <trademark>PostScript</trademark>). The November 2003 edition
+ was published in <citetitle ref="tugboat"
+ show="title"></citetitle>. 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.</releaseinfo>
+ <revhistory>
+ <revision>
+ <revnumber>3.6</revnumber>
+ <date YYYY-MM-DD="2005-03-31">March 2005</date>
+ <revremark>Since the publication of the November 2003 edition
+ in <citetitle ref="tugboat" show="title"></citetitle>,
+ several new books on <LaTeX/> 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 <TeX/>, <LaTeX/>, 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 <TeX/>4ht, which is where I found the
+ styles.</revremark>
+ </revision>
+ <revision>
+ <revnumber>3.5</revnumber>
+ <date YYYY-MM-DD="2004-07-29">July 2004</date>
+ <revremark>Modified DTD to add span element type to allow use
+ of external entities for formatted <TeX/>, <LaTeX/>, 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.</revremark>
+ </revision>
+ <revision>
+ <revnumber>3.4</revnumber>
+ <date YYYY-MM-DD="2003-11-09">November 2003</date>
+ <revremark>Applied all Barbara Beeton&apos;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&apos;s another day&apos;s work.
+ Started on writing the missing sections (Installing Type 1
+ <acronym ref="CM"></acronym> Fonts and Going beyond <LaTeX/>,
+ but these are not finished yet) and rewrote entirely the
+ existing (non-<acronym ref="CM"></acronym>) Type 1 font
+ installation procedure in line with the new (unreleased)
+ Gutta-Percha script. Added hidden meanings for <acronym
+ id="CD-ROM">Compact Disc Read-Only Memory</acronym>,
+ <acronym id="DVD">Digital Versatile Disk</acronym>, <acronym
+ id="IBM">International Business Machines</acronym>.</revremark>
+ </revision>
+ <revision>
+ <revnumber>3.3</revnumber>
+ <date YYYY-MM-DD="2003-08-20">August 2003</date>
+ <revremark>Fixed <acronym ref="XSLT"></acronym> 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.</revremark>
+ </revision>
+ <revision>
+ <revnumber>3.2</revnumber>
+ <date YYYY-MM-DD="2003-03-05">March 2003</date>
+ <revremark>Finished rewrite. Revised and expanded almost
+ everything.</revremark>
+ </revision>
+ <revision>
+ <revnumber>3.1</revnumber>
+ <date YYYY-MM-DD="2002-08-28">August 2002</date>
+ <revremark>Recast in DocBook and reworded some sections.
+ Started the big rewrite.</revremark>
+ </revision>
+ </revhistory>
+ </bookinfo>
+ <toc>
+ <title>Contents</title>
+ </toc>
+ <preface id="intro">
+ <title>Introduction</title>
+ <para>This book originally accompanied a 2-day course on using the
+ <LaTeX/> 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 <LaTeX/> systems on any platform,
+ including other Unix workstations, mainframes, and even your
+ <acronym id="PDA">Personal Digital Assistant</acronym>.</para>
+ <section>
+ <title>Who needs this book?</title>
+ <para>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:</para>
+ <itemizedlist>
+ <listitem>
+ <para>producing typesetter-quality formatting;</para>
+ </listitem>
+ <listitem>
+ <para>formatting long, complex, highly-structured,
+ repetitive, or automatically-generated
+ documents;<footnote>
+ <para><LaTeX/> can easily be used for once-off or short
+ and simple documents as well, but its real strengths
+ lie in consistency and automation.</para>
+ </footnote></para>
+ </listitem>
+ <listitem>
+ <para>saving time and effort by automating common
+ tasks;</para>
+ </listitem>
+ <listitem>
+ <para>achieving or maintaining your independence from
+ specific makes or models of proprietary hardware,
+ software, or file formats (portability);</para>
+ </listitem>
+ <listitem>
+ <para>using Open Source software (free of restrictions,
+ sometimes also free of charge).</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Skills needed</title>
+ <para><LaTeX/> 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:</para>
+ <itemizedlist>
+ <listitem>
+ <para>how to use a good plain-text
+ editor (<emphasis>not</emphasis> a wordprocessor like
+ <productname>OpenOffice</productname>,
+ <productname>WordPerfect</productname>, or Microsoft
+ <productname>Word</productname>, and
+ <emphasis>not</emphasis> a toy like Microsoft
+ <productname>Notepad</productname>);<note>
+ <para>2.1.3</para>
+ </note></para>
+ </listitem>
+ <listitem>
+ <para>where to find all 95 of the printable <acronym
+ ref="ASCII"></acronym> characters on your keyboard and
+ what they mean, and how to type accents and symbols, if
+ you use them;<note>
+ <para>3.2.1.2</para>
+ </note></para>
+ </listitem>
+ <listitem>
+ <para>how to create, open, save,
+ close, rename, move, and delete files and folders
+ (directories);<note>
+ <para>2.3</para>
+ </note></para>
+ </listitem>
+ <listitem>
+ <para>how to use a Web browser and/or <acronym id="FTP">File
+ Transfer Protocol</acronym> program to
+ download and save files from the Internet;<note>
+ <para>7.3.1.6</para>
+ </note></para>
+ </listitem>
+ <listitem>
+ <para>how to uncompress and unwrap (unzip or detar)
+ downloaded files.<note>
+ <para>2.3.7</para>
+ </note></para>
+ </listitem>
+ </itemizedlist>
+ <para>If you don&apos;t know how to do
+ these things yet, it&apos;s important to go and learn them
+ first. Trying to become familiar with the fundamentals of
+ using a computer <emphasis>at the same time</emphasis> as
+ learning <LaTeX/> is not likely to be as effective as doing
+ them in order.</para>
+ <para>These are not specialist
+ skills&mdash;they are all included in the <acronym id="ECDL"
+ vendor="http://www.ecdl.com/">European Computer Driving
+ Licence</acronym> and the relevant sections of the <acronym
+ ref="ECDL"></acronym> syllabus are noted in the margin
+ above, so they are well within the capability of anyone who
+ uses a computer.</para>
+ </section>
+ <section>
+ <title>Objectives of this book</title>
+ <para>By the end of this book, you should be able to undertake
+ the following tasks:</para>
+ <itemizedlist>
+ <listitem>
+ <para>use a plain-text editor to create and maintain your
+ documents;</para>
+ </listitem>
+ <listitem>
+ <para>add <LaTeX/> markup to identify
+ your document structure and formatting
+ requirements;</para>
+ </listitem>
+ <listitem>
+ <para>typeset <LaTeX/> documents, correct simple formatting
+ errors, and display or print the results;</para>
+ </listitem>
+ <listitem>
+ <para>identify, install, and use additional packages (using
+ <acronym ref="CTAN"></acronym> for downloading where
+ necessary);</para>
+ </listitem>
+ <listitem>
+ <para>recognise the limitations of procedural markup systems
+ and choose appropriate generic markup methods where
+ appropriate.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Synopsis</title>
+ <para>The original course covered the following topics as
+ separate sessions, which are represented in the book as
+ chapters:</para>
+ <orderedlist>
+ <listitem>
+ <para>Where to get and how to install
+ <LaTeX/> (<productname>te<TeX/></productname>,
+ <productname>fp<TeX/></productname>, or
+ <productname>pro<TeX/>t</productname> from the
+ <TeX/> Collection disks);<indexterm>
+ <primary sortas="texlive"><TeX/> Live</primary>
+ </indexterm><indexterm>
+ <primary sortas="texcollection"><TeX/>
+ Collection</primary>
+ </indexterm></para>
+ </listitem>
+ <listitem>
+ <para>How to type <LaTeX/> documents:
+ using an editor to create files
+ (half a dozen editors for <LaTeX/>);</para>
+<!-- more on the Mac editor! -->
+ </listitem>
+ <listitem>
+ <para>Basic structures (the Document Class Declaration and
+ its layout options; the document environment with sections
+ and paragraphs);</para>
+ </listitem>
+ <listitem>
+ <para>Typesetting, viewing, and printing;</para>
+ </listitem>
+ <listitem>
+ <para>The use of packages and <acronym ref="CTAN"></acronym>
+ to adapt formatting using standard tools;</para>
+ </listitem>
+ <listitem>
+ <para>Other document structures (lists, tables, figures,
+ images, and verbatim text);</para>
+ </listitem>
+ <listitem>
+ <para>Textual tools (footnotes, marginal notes,
+ cross-references, indexes and glossaries, and
+ bibliographic citations);</para>
+ </listitem>
+ <listitem>
+ <para>Typographic considerations (white-space and typefaces;
+ inline markup and font changes; extra font installation
+ and automation);</para>
+ </listitem>
+ <listitem>
+ <para>Programmability and automation (macros and modifying
+ <LaTeX/>&apos;s behaviour);</para>
+ </listitem>
+ <listitem>
+ <para>Conversion and compatibility with other systems
+ (<acronym ref="XML"></acronym>,
+ <productname>Word</productname>, &etc;).</para>
+ </listitem>
+ </orderedlist>
+ <para>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.</para>
+ </section>
+ <section>
+ <title>Where&apos;s the math?</title>
+ <para>It is important to note that
+ the document <emphasis>does not cover</emphasis> 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.</para>
+ <indexterm>
+ <primary>mathematics</primary>
+ </indexterm>
+ <para>There are several other guides, introductions, and
+ <wordasword>get-started</wordasword> documents on the Web and
+ on <acronym ref="CTAN"></acronym> which cover these topics and
+ more. Among the more popular are:</para>
+ <itemizedlist>
+ <listitem>
+ <para><citetitle ref="begin"></citetitle>, where all
+ beginners should start;</para>
+ </listitem>
+ <listitem>
+ <para><citetitle ref="lshort"></citetitle> is a good
+ beginner&apos;s tutorial;</para>
+ </listitem>
+ <listitem>
+ <para><citetitle ref="gentle"></citetitle> is a classic
+ tutorial on Plain <TeX/>;</para>
+ </listitem>
+ <listitem>
+ <para><citetitle ref="imported"></citetitle> shows you how
+ to do (almost) anything with graphics: side-by-side,
+ rotated, &etc;;</para>
+ </listitem>
+ <listitem>
+ <para><citetitle ref="mathguide"></citetitle> gets you
+ started with the American Math Society&apos;s powerful
+ packages;</para>
+ </listitem>
+ <listitem>
+ <para><citetitle ref="symbol-list"></citetitle> shows over
+ 2,500 symbols available.</para>
+ </listitem>
+ </itemizedlist>
+ <para>This list was taken from the
+ <acronym ref="CTAN"></acronym> search page. There are also
+ lots of books published about <TeX/> and <LaTeX/>: the most
+ important of these for users of this document are listed in
+ <xref linkend="docs"/>.</para>
+ </section>
+ <section id="availability">
+ <title>Availability of <LaTeX/> systems</title>
+ <para>Because the <TeX/> program (the
+ <wordasword>engine</wordasword> which actually does the
+ typesetting) is separate from whichever editor you choose,
+ <TeX/>-based systems are available in a variety of different
+ modes using different interfaces, depending on how you want to
+ use them.</para>
+ <section id="gui">
+ <title>Graphical interface</title>
+ <para>The normal way to run <LaTeX/> 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 <LaTeX/> systems (the
+ typeset display, spellchecker, related programs like
+ <productname>makeindex</productname> and <BibTeX/>) are run
+ the same way. This works both in a normal <acronym
+ id="GUI">Graphical User Interface</acronym> as well as in
+ text-only interfaces.</para>
+ <para>In the popular <LaTeX/> editors like
+ <productname>Emacs</productname>,
+ <productname><TeX/>shell</productname>,
+ <productname><TeX/>nicCenter</productname>,
+ <productname>WinShell</productname>, or
+ <productname>WinEdt</productname>, 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.<footnote>
+ <para>Recent versions of some editors hide this display by
+ default unless errors occur in the typesetting.</para>
+ </footnote></para>
+ </section>
+ <section id="cli">
+ <title>Command-line interface</title>
+ <para>However, the graphical interface
+ is useless if you want to run <LaTeX/> 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 <TeX/> engine is in fact
+ a <acronym id="CLI">Command-Line Interface</acronym> program,
+ that is, it is used as a
+ <wordasword>console</wordasword> 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
+ <literal>latex</literal> followed by the name of your
+ document file (see <xref linkend="clidemo"/> in <xref
+ linkend="cmdwin"/> for an example).</para>
+ <para>Commands like these let you run <LaTeX/> in an automated
+ environment like a
+ <acronym id="CGI">Common Gateway Interface</acronym> 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<TeX/>, fp<TeX/>, MiK<TeX/>, pro<TeX/>t,
+ PC-<TeX/>, True<TeX/>,
+ &etc;).</para>
+ </section>
+ <section id="displays">
+ <title>Typeset displays</title>
+ <para><LaTeX/> 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.</para>
+ <variablelist>
+ <varlistentry id="async">
+ <term>Asynchronous typographic displays</term>
+ <listitem>
+ <para>This method is called an <firstterm
+ id="asynchronous">asynchronous typographic
+ display</firstterm> because the typeset window only
+ updates <emphasis>after</emphasis> you have typed
+ something and reprocessed it, not
+ <emphasis>while</emphasis> you are still typing, as it
+ would with a wordprocessor.<footnote>
+ <para>Among other reasons, <TeX/> typesets whole
+ paragraphs at a time, not line-by-line as lesser
+ systems do, in order to get the hyphenation and
+ justification (H&ampers;J) right (see <xref
+ linkend="handj"/>).
+ </para>
+ </footnote></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="sync">
+ <term>Synchronous typographic displays</term>
+ <listitem>
+ <para id="synchro">Some distributions of <LaTeX/>
+ offer a <firstterm id="synchronous">synchronous
+ typographic interface</firstterm>. In these, you type
+ directly into the typographic display, as with a
+ wordprocessor. Three popular examples are
+ <productname>Textures</productname>,
+ <productname>Scientific Word</productname>, and
+ <productname>V<TeX/></productname> (see table below).
+ At least one free version (<LyX/>, see <xref
+ linkend="lyxwin"/> in <xref linkend="editors"/>)
+ offers a similar interface.</para>
+ <para>With a synchronous display
+ you get Instant Textual Gratification&trade;, but your
+ level of control is restricted to that of the <acronym
+ ref="GUI"></acronym> you use, which cannot provide
+ access to everything that <LaTeX/> 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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Near-synchronous displays</term>
+ <listitem>
+ <para>There are several other
+ methods available free for Unix and some other systems
+ for close-to-synchronous updates of the typeset
+ display (including <personname id="jf">
+ <firstname>Jonathan</firstname>
+ <surname>Fine</surname>
+ </personname>&apos;s <productname>Instant
+ Preview</productname> and the <TeX/> daemon), and
+ for embedding typographic fragments from the typeset
+ display back into the editor window (<personname id="dk">
+ <firstname>David</firstname>
+ <surname>Kastrup</surname>
+ </personname>&apos;s <methodname>preview-latex</methodname>
+ package).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section id="commercial">
+ <title>Commercial distributions</title>
+ <para>Whatever method you choose, the
+ <TeX/> Collection CD and <acronym ref="CTAN"></acronym> are
+ not the only source of software. The vendors listed in <xref
+ linkend="vendors"/> offer excellent commercial
+ implementations of <TeX/> and <LaTeX/>,
+ 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 <TeX/> and <LaTeX/>
+ communities for many years.<indexterm>
+ <primary>commercial implementations</primary>
+ </indexterm></para>
+ <table id="vendors">
+ <title>Popular commercial implementations of <TeX/> systems</title>
+ <tgroup cols="4">
+ <colspec colwidth=".65in" colsep="flush"/>
+ <colspec colwidth="1in"/>
+ <colspec colwidth=".9in" align="left"/>
+ <colspec colsep="flush" align="left"/>
+ <thead>
+ <row>
+ <entry>Product</entry>
+ <entry>Platform</entry>
+ <entry>Company</entry>
+ <entry>URI</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>PC<TeX/></entry>
+ <entry>MS-Windows</entry>
+ <entry>Personal <TeX/>, Inc</entry>
+ <entry><ulink url="www.pctex.com/"></ulink></entry>
+ </row>
+ <row>
+ <entry>True<TeX/></entry>
+ <entry>MS-Windows</entry>
+ <entry>True <TeX/></entry>
+ <entry><ulink url="truetex.com/"></ulink></entry>
+ </row>
+ <row>
+ <entry>Textures</entry>
+ <entry>Apple Mac</entry>
+ <entry>Blue Sky Research</entry>
+ <entry><ulink url="www.bluesky.com/"></ulink></entry>
+ </row>
+ <row>
+ <entry>Scientific Word</entry>
+ <entry>MS-Windows</entry>
+ <entry>Mackichan Software</entry>
+ <entry><ulink
+ url="www.mackichan.com/"></ulink></entry>
+ </row>
+ <row>
+ <entry>V<TeX/></entry>
+ <entry>MS-Windows, Linux, OS/2</entry>
+ <entry>MicroPress, Inc</entry>
+ <entry><ulink
+ url="www.micropress-inc.com/"></ulink></entry>
+ </row>
+<!--
+ <row>
+ <entry>Y&ampers;Y<TeX/></entry>
+ <entry>MS-Windows</entry>
+ <entry>Y&ampers;Y Software</entry>
+ <entry><ulink url="www.yandy.com/"></ulink></entry>
+ </row>
+-->
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ </section>
+ <section id="prodnote">
+ <title>Production note</title>
+ <para>This document is written and maintained in <acronym
+ ref="XML"></acronym>, using a customized version of the
+ <productname>DocBook</productname>&nbsp;<acronym
+ ref="DTD"></acronym>. Conversions were made to <acronym
+ ref="HTML"></acronym> and <LaTeX/> using <acronym
+ ref="XSLT"></acronym> scripts and <personname id="mk">
+ <firstname>Michael</firstname>
+ <surname>Kay</surname>
+ </personname>&apos;s <productname>Saxon</productname>
+ processor.</para>
+ <para>The complete source, with all ancillary files, is
+ available online at <ulink
+ url="http://www.ctan.org/tex-archive/info/beginlatex/src/"></ulink>
+ but if you want to try processing it yourself you must install
+ <productname>Java</productname> (from Sun, <acronym
+ condition="noid" ref="IBM"></acronym>, or a number of
+ others) and <productname>Saxon</productname> (from <ulink
+ url="http://saxon.sourceforge.net/"></ulink>), in addition
+ to <LaTeX/>.</para>
+ <para>This document is published under the terms and conditions
+ of the <acronym ref="GNU"></acronym> Free Documentation
+ License. Details are in <xref
+ linkend="gfdl"/>.</para>
+ </section>
+<?LaTeX \clearpage?>
+ <section id="symbols">
+ <title>Symbols and conventions</title>
+ <para>The following typographic notations are used:</para>
+ <informaltable id="symboltable">
+ <tgroup cols="2">
+ <colspec colsep="flush" align="left"/>
+ <colspec colsep="flush" align="justify" colwidth="3.5in"/>
+ <thead>
+ <row>
+ <entry>Notation</entry>
+ <entry>Meaning</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><command>command</command></entry>
+ <entry>Control sequences which perform an
+ action, &eg; <command>newpage</command></entry>
+ </row>
+ <row>
+ <entry><varname
+ role="dimension">length</varname></entry>
+ <entry>Control sequences which store a dimension
+ (measurement in units), &eg; <varname
+ role="dimension">parskip</varname></entry>
+ </row>
+ <row>
+ <entry><varname role="counter">counter</varname></entry>
+ <entry>Values used for counting (whole numbers, as
+ opposed to measuring in units), &eg; <varname
+ role="counter">secnumdepth</varname></entry>
+ </row>
+ <row>
+ <entry><firstterm id="term">term</firstterm></entry>
+ <entry>Defining instance of a
+ new term</entry>
+ </row>
+ <row>
+ <entry><modespec>environment</modespec></entry>
+ <entry>A <LaTeX/> formatting environment</entry>
+ </row>
+ <row>
+ <entry><methodname>package</methodname></entry>
+ <entry>A <LaTeX/> package (available from <acronym
+ ref="CTAN"></acronym>)</entry>
+ </row>
+ <row>
+ <entry><productname>product</productname></entry>
+ <entry>Program or product name</entry>
+ </row>
+ <row>
+ <entry><literal>typewriter type</literal></entry>
+ <entry>Examples of source code (stuff you
+ type)</entry>
+ </row>
+ <row>
+ <entry><format fontdefault="tt"
+ lining="under">mybook</format> or <format
+ fontshape="sl"
+ fontdefault="tt">value</format></entry>
+ <entry>Mnemonic examples of
+ things you have to supply real-life values for</entry>
+ </row>
+ <row>
+ <entry><keycap>x</keycap></entry>
+ <entry>A key on your keyboard</entry>
+ </row>
+ <row>
+ <entry><keycombo>
+ <keycap>Ctrl</keycap>
+ <keycap>x</keycap>
+ </keycombo></entry>
+ <entry>Two keys pressed together</entry>
+ </row>
+ <row>
+ <entry>
+ <keycap>Esc</keycap>&thinsp;<keycap>q</keycap>
+ </entry>
+ <entry>Two keys pressed one after another</entry>
+ </row>
+ <row>
+ <entry><guiicon>Submit</guiicon></entry>
+ <entry>On-screen button to click</entry>
+ </row>
+ <row>
+ <entry><guimenu>Menu</guimenu><guimenuitem>Item</guimenuitem></entry>
+ <entry>Drop-down menu with items</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>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.</para>
+ </section>
+ </preface>
+ <preface id="foreword">
+ <title>Foreword</title>
+ <para>As noted in <xref linkend="intro"/>,
+ 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 <ulink
+ url="comp.text.tex" type="news:"></ulink> that many people do
+ not read the <acronym ref="FAQ"></acronym>s, do not use the
+ <acronym ref="TUG"></acronym> 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 <wordasword>sitting by
+ Nelly</wordasword>, which involves looking over a
+ colleague&apos;s shoulder in the office, lab, library, pub, or
+ classroom, and absorbing all his or her bad habits.</para>
+ <para>In the summer of 2001 I presented a short proposal on the
+ marketing of <LaTeX/> to the annual conference of the <TeX/> Users
+ Group held at the University of Delaware, and showed an example
+ of a <ulink
+ url="http://www.silmaril.ie/documents/latex-brochure/leaflet.pdf">draft
+ brochure</ulink> designed to persuade newcomers to try <LaTeX/>
+ 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.</para>
+ <para>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 <LaTeX/> 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.</para>
+ <para>I had originally hoped that the <LaTeX/> version of the
+ document would be processable by any freshly-installed default
+ <LaTeX/> 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 <LaTeX/>,
+ however simply it may describe the process itself.</para>
+ <para>However, as the careful reader will have already noticed,
+ the master source of the document is not maintained in <LaTeX/>
+ but in <acronym ref="XML"></acronym>. 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 <LaTeX/>
+ installation.</para>
+ <para id="docs">If you are just starting with <LaTeX/>, at an early
+ opportunity you should buy or borrow a copy of <citetitle
+ ref="latexbook"></citetitle> which is the original
+ author&apos;s manual. More advanced users should get the
+ <citetitle ref="companion"></citetitle> or one of its
+ successors. In the same series there are also the <citetitle
+ ref="graphicscomp"></citetitle> and the <citetitle
+ ref="webcomp"></citetitle>. Mathematical users might want to
+ read <citetitle ref="mathguide"></citetitle>.</para>
+ </preface>
+ <preface id="preface">
+ <title>Preface</title>
+ <para>Many people discover <LaTeX/> after
+ years of struggling with wordprocessors and desktop publishing
+ systems, and are amazed to find that <TeX/> has been around for
+ over 25 years and they hadn&apos;t heard of it. It&apos;s not a
+ conspiracy, just <quote>a well-kept secret known only to a few
+ million people</quote>, as one anonymous user has put
+ it.</para>
+ <para>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 <emphasis>writing</emphasis>&mdash;ask any
+ journalist or professional writer.</para>
+ <para>A few years ago a new <LaTeX/> user expressed concern on
+ the <ulink url="comp.text.tex"></ulink> newsgroup about
+ <quote>learning to write in <LaTeX/></quote>. <ulink
+ url="news:comp.text.tex/MPG.18d82140d65ddc5898968c@news.earthlink.net">Some
+ excellent advice</ulink> was posted in response to this query,
+ which I reproduce with permission below [the bold text is my
+ emphasis]:</para>
+ <blockquote condition="news" citedoc="heller">
+ <para>No, the harder part might be <emphasis>writing</emphasis>,
+ period. <TeX/>/<LaTeX/> is actually easy, once you relax and
+ stop worrying about appearance as a be-all-and-end-all. Many
+ people have become <wordasword>Word Processing
+ Junkies</wordasword> and <emphasis role="high">no longer
+ <wordasword>write</wordasword> documents, they
+ <wordasword>draw</wordasword> them</emphasis>, almost at the
+ same level as a pre-literate 3-year old child might pretend to
+ <wordasword>write</wordasword> a story, but is just creating a
+ sequence of pictures with a pad of paper and box of
+ <productname>Crayola</productname>s&mdash;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&apos;s or PhD thesis or a business
+ person writing a white paper, &etc; For this reason,
+ <emphasis>I</emphasis> strongly recommend
+ <emphasis>not</emphasis> using any sort of fancy <acronym
+ ref="GUI"></acronym>&nbsp;<wordasword>crutch</wordasword>.
+ Use a plain vanilla text editor and treat it like an
+ old-fashioned typewriter. Don&apos;t waste time playing with
+ your mouse.</para>
+ <para>Note: I am <emphasis>not</emphasis> saying that you should
+ have no concerns about the appearance of your document, just
+ that you should <emphasis>write</emphasis> the document
+ (completely) first and tweak the appearance
+ later&hellip;<emphasis>not</emphasis> [spend time on] lots of
+ random editing in the bulk of the document itself.</para>
+ </blockquote>
+ <para>Learning to write well can be hard, but authors shouldn&apos;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.</para>
+ <para id="mathtex"><personname id="knuth">
+ <firstname>Don</firstname>
+ <surname>Knuth</surname>
+ </personname> originally wrote <TeX/> to typeset mathematics for
+ the second edition of his master-work <citetitle
+ ref="aocs"></citetitle>, 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 <citetitle
+ ref="mathwrite"></citetitle> which shows how
+ important it is to think about what you write, and how the
+ computer should be able to help, not hinder.</para>
+ <para>And <TeX/> is much more than math:
+ it&apos;s a programmable typesetting system which can be used
+ for almost any formatting task, and <LaTeX/> 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 <TeX/> noticed outside the
+ technical field.</para>
+ <para>Nowadays, however, there are many companies
+ selling <TeX/> software or services,<footnote>
+ <para>See, for example, the list of <TeX/> vendors on <xref
+ linkend="vendors" role="page"/>, and the list of consultants
+ published by <acronym ref="TUG"></acronym>.</para>
+ </footnote> dozens
+ of publishers accepting <LaTeX/> documents for
+ publication, and hundreds of thousands of users using <LaTeX/>
+ for millions of documents.<footnote>
+ <para>A guesstimate. With free software it&apos;s impossible
+ to tell how many people are using it, but it&apos;s a
+ <emphasis>lot</emphasis>.</para>
+ </footnote></para>
+ <para>To count yourself as a <TeX/> or <LaTeX/> user, visit the
+ <TeX/> Users Group&apos;s
+ <wordasword><TeX/> Counter</wordasword> web site
+ (and get a nice certificate!).</para>
+ <para>There is occasionally some confusion among newcomers between
+ the two main programs, <TeX/> and <LaTeX/>:</para>
+ <itemizedlist>
+ <listitem>
+ <para><TeX/> is a typesetting program, originally written by
+ Prof Knuth at Stanford around 1978. It implements a
+ macro-driven typesetters&apos; programming language of some
+ 300 basic operations and it has formed the core of many
+ other <acronym id="DTP">desktop publishing</acronym>
+ systems. Although it is still possible to write in the raw
+ <TeX/> 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.</para>
+ </listitem>
+ <listitem>
+ <para><LaTeX/> is a user interface for <TeX/>, designed by
+ <personname id="lamport">
+ <firstname>Leslie</firstname>
+ <surname> Lamport</surname>
+ </personname> at <acronym id="DEC">Digital Equipment
+ Corporation</acronym> 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 <TeX/> without
+ having to learn the underlying language. <LaTeX/> is the
+ recommended system for all users except professional
+ typographic programmers and computer scientists who want to
+ study the internals of <TeX/>.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Both <TeX/> and <LaTeX/> have been
+ constantly updated since their inception. Knuth has now frozen
+ development of the <TeX/> engine so that users and developers
+ can have a virtually bug-free, rock-stable platform to work
+ with.<footnote>
+ <para>Knuth still fixes bugs, although the chances of finding
+ a bug in <TeX/> these days approaches zero.</para>
+ </footnote> Typographic programming development continues with
+ the <acronym id="NTS">New Typesetting System</acronym>, planned
+ as a successor to <TeX/>. The <LaTeX/>3 project has taken over
+ development of <LaTeX/>, and the current version is
+ <LaTeXe/>, which is what we are concentrating on here. Details
+ of all developments can be had from the <acronym
+ ref="TUG"></acronym> at <ulink
+ url="http://www.tug.org"></ulink></para>
+ <sidebar id="myths">
+ <title>Debunking the mythology</title>
+ <para>Naturally, over all the years, a few myths have grown up
+ around <LaTeX/>, often propagated by people who should know
+ better. So, just to clear up any potential
+ misunderstandings&hellip;</para>
+ <variablelist>
+ <varlistentry>
+ <term>MYTH: <quote><LaTeX/> has only got one
+ font</quote></term>
+ <listitem>
+ <para>Most <LaTeX/> systems can use any OpenType,
+ TrueType, Adobe (<trademark>PostScript</trademark>)
+ Type1 or Type3, or &metafont; font. This is more than
+ most other known typesetting system.
+ <LaTeX/>&apos;s default font is Computer Modern (based
+ on Monotype Series&nbsp;8: see
+ <xref linkend="fontable-mf"/>), not Times Roman, and some
+ people get upset because it <quote>looks
+ different</quote> to Times. Typefaces differ:
+ that&apos;s what they&apos;re for&mdash;get used to it.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MYTH: <quote><LaTeX/> isn&apos;t <acronym
+ ref="WYSIWYG"></acronym></quote></term>
+ <listitem>
+ <para>Simply not true. <acronym ref="DVI"></acronym>
+ and <acronym ref="PDF"></acronym> preview is better
+ <acronym ref="WYSIWYG"></acronym> than any wordprocessor
+ and most <acronym ref="DTP"></acronym> systems. What
+ people mean is that <LaTeX/>&apos;s typographic display
+ is asynchronous with the edit window. This is only true
+ for the default <acronym ref="CLI"></acronym>
+ implementations. See <xref
+ linkend="synchro"/> for details of synchronous
+ versions.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MYTH: <quote><LaTeX/> is obsolete</quote></term>
+ <listitem>
+ <para>Quite the opposite: it&apos;s under constant
+ development, with new features being added almost
+ weekly. Check the <ulink url="comp.text.tex"
+ type="news:"></ulink> for messages about recent
+ uploads to <acronym ref="CTAN"></acronym>. It&apos;s
+ arguably more up-to-date than most other systems:
+ <LaTeX/> 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.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sidebar>
+ <sidebar id="myths2">
+ <title>More mythology</title>
+ <variablelist>
+ <varlistentry>
+ <term>MYTH: <quote><LaTeX/> is a Unix system</quote></term>
+ <listitem>
+ <para>People are also heard saying:
+ <quote><LaTeX/> is a Windows system</quote>,
+ <quote><LaTeX/> is a Mac system</quote>, &etc;,
+ &etc;&nbsp;<foreignphrase>ad nauseam</foreignphrase>.
+ <TeX/> systems run on almost every computer in use, from
+ some of the biggest supercomputers down to handhelds
+ (<acronym ref="PDA"></acronym>s like the Sharp
+ <productname>Zaurus</productname>). That includes
+ Windows and Linux PCs, Macs, and all other Unix systems.
+ If you&apos;re using something <TeX/> doesn&apos;t run
+ on, it must be either incredibly new, incredibly old, or
+ unbelievably obscure.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MYTH: <quote><LaTeX/> is <wordasword>too
+ difficult</wordasword></quote></term>
+ <listitem>
+ <para>This has been heard from
+ physicists who can split atoms; from mathematicians who
+ can explain why <inlineequation>
+ <m:csymbol>&pi;</m:csymbol>
+ </inlineequation> 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
+ <quote>B</quote>. It&apos;s nonsense: most people grasp
+ <LaTeX/> in 20 minutes or so. It&apos;s not rocket
+ science (or if it is, I know any number of unemployed
+ rocket scientists who will teach it to you).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MYTH: <quote><LaTeX/> is <wordasword>only for
+ scientists and
+ mathematicians</wordasword></quote></term>
+ <listitem>
+ <para>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 <acronym
+ ref="XML"></acronym> brought new demands for automated
+ web-based typesetting.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sidebar>
+ </preface>
+ <chapter id="get">
+ <title>Installing <TeX/> and <LaTeX/></title>
+ <indexterm>
+ <primary sortas="tetex">te<TeX/></primary>
+ </indexterm>
+ <indexterm>
+ <primary sortas="fptex">fp<TeX/></primary>
+ </indexterm>
+ <indexterm>
+ <primary sortas="texniccenter"><TeX/>nicCenter</primary>
+ </indexterm>
+ <indexterm>
+ <primary sortas="miktex">MiK<TeX/></primary>
+ </indexterm>
+ <indexterm>
+ <primary>Linux</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Unix</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Microsoft Windows</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Mac OS X</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Apple Mac</primary>
+ </indexterm>
+ <indexterm>
+ <primary>OS X</primary>
+ </indexterm>
+ <para>This course is based on using one of
+ the following distributions of <TeX/> on the 2004 <TeX/>
+ Collection DVD or the 2003 <TeX/> Live CD:</para>
+ <variablelist>
+ <varlistentry>
+ <term>te<TeX/></term>
+ <listitem>
+ <para>for Linux and other Unix-like systems, including Mac
+ OS&thinsp;X (<personname id="esser">
+ <firstname>Thomas</firstname>
+ <surname>Esser</surname>
+ </personname>);</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pro<TeX/>t</term>
+ <listitem>
+ <para>for Microsoft Windows (<personname id="tf">
+ <firstname>Thomas</firstname>
+ <surname>Feuerstack</surname>
+ </personname>), based on <personname id="cs">
+ <firstname>Christian</firstname>
+ <surname>Schenk</surname></personname>&apos;s
+ Mik<TeX/>;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>fp<TeX/></term>
+ <listitem>
+ <para>for Microsoft Windows (<personname id="popineau">
+ <firstname>Fabrice</firstname>
+ <surname> Popineau</surname>
+ </personname>) from the 2003 <TeX/> Live CD.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>Many other implementations of <TeX/>,
+ such as <personname id="tk">
+ <firstname>Tom</firstname>
+ <surname>Kiffe</surname>
+ </personname>&apos;s CMac<TeX/> for the Apple Macintosh, can be
+ downloaded from <acronym ref="CTAN"></acronym>. <LaTeX/> is
+ included with all modern distributions of <TeX/>.</para>
+ <para>The <TeX/> Collection CD is issued
+ annually on behalf of most of the local <TeX/> user groups
+ around the world (see <ulink
+ url="http://www.tug.org/lugs.html"></ulink> for addresses),
+ and edited by <personname id="sr">
+ <firstname>Sebastian</firstname>
+ <surname>Rahtz</surname>
+ </personname>, <personname id="kb">
+ <firstname>Karl</firstname>
+ <surname>Berry</surname>
+ </personname>, <personname id="ml">
+ <firstname>Manfred</firstname>
+ <surname>Lotz</surname>
+ </personname>, 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.</para>
+ <para>There are many other distributions of <LaTeX/> both free and
+ commercial, as described in <xref
+ linkend="intro"/>: they all process <LaTeX/> identically, but
+ there are some differences in size, speed, packaging, and (in
+ the case of commercial distributions) price, support, and extra
+ software provided.</para>
+ <para>One final thing before we start: publicly-maintained
+ software like <TeX/> is updated faster than commercial software,
+ so <emphasis>always check to see if there is a more recent
+ version of the installation</emphasis>. See <xref
+ linkend="latest"/> for more details.</para>
+ <sect1 id="editdis">
+ <title>Editing and display</title>
+ <para>When you install <LaTeX/> you will
+ have the opportunity to decide <orderedlist>
+ <listitem>
+ <para>which plain-text editor[s] you want to use to create
+ and maintain your documents</para>
+ </listitem>
+ <listitem>
+ <para>which preview programs you want to use to see your
+ typesetting</para>
+ </listitem>
+ </orderedlist>. This isn&apos;t much use to you if you&apos;re
+ unfamiliar with editors and previewers, so have a look at the
+ table below, and maybe flip ahead to <xref
+ linkend="editors"/> for a moment, where there are
+ descriptions and screenshots.</para>
+ <para>The best bet is probably to install more than one&mdash;if
+ you&apos;ve got the disk space&mdash;or maybe all of them, because
+ you can always delete the ones you don&apos;t like.</para>
+ <variablelist>
+ <varlistentry>
+ <term>Editors</term>
+ <listitem>
+ <para>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&apos;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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Previewers</term>
+ <listitem>
+ <para>For displaying your
+ typesetting before printing, you will need a previewer.
+ All systems come with a <acronym ref="DVI"></acronym>
+ previewer for standard <LaTeX/>,
+ but if you are intending to produce industry-standard
+ <trademark>PostScript</trademark> or <acronym
+ ref="PDF"></acronym> (Adobe Acrobat) files you will
+ need a previewer for those formats.
+ <productname>GSview</productname> displays both
+ <trademark>PostScript</trademark> and <acronym
+ ref="PDF"></acronym> files;
+ <productname>xpdf</productname> and Adobe&apos;s own
+ <productname>Acrobat Reader</productname> just display
+ <acronym ref="PDF"></acronym> files.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>For brief details of some of the most popular editors used
+ for <LaTeX/>, see <xref linkend="editors"/>.</para>
+<!--
+ <informaltable id="editchoice">
+ <tgroup cols="2">
+ <colspec colsep="flush" align="left"/>
+ <colspec colwidth="3.75in" colsep="flush" align="justify"/>
+ <thead>
+ <row>
+ <entry>Editor</entry>
+ <entry>Comments</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><productname>Emacs</productname></entry>
+ <entry>Large and powerful. Needs learning (a life-skill
+ like <LaTeX/>) but well worth the effort.
+ Multi-platform, it opens and edits anything and
+ everything, with special features for <LaTeX/> &etc;,
+ and good productivity tools for writers. Open
+ Source.</entry>
+ </row>
+ <row>
+ <entry><productname>WinShell</productname></entry>
+ <entry>Simple but effective beginner&apos;s tool for
+ MS-Windows. Runs <LaTeX/> &etc;&nbsp;with toolbar
+ buttons. Very easy to use, small footprint.
+ Free.</entry>
+ </row>
+ <row>
+ <entry><productname><TeX/>nicCenter</productname></entry>
+ <entry>Integrated development environment for <LaTeX/>
+ with extensive toolbar and documentation support.
+ Free, MS-Windows only.</entry>
+ </row>
+ <row>
+ <entry><productname>WinEdt</productname></entry>
+ <entry>Comprehensive editor aimed at heavy <LaTeX/>
+ usage, with toolbar, productivity features, and good
+ support. Configurable for almost any distribution of
+ <TeX/> (with some effort). Free trial, licensable
+ after 1&nbsp;month, MS-Windows only.</entry>
+ </row>
+ <row>
+ <entry><productname>PFE</productname></entry>
+ <entry>Popular general-purpose editor for MS-Windows: no
+ special <LaTeX/> features but a very configurable
+ launcher and command-line controller. Free but no
+ longer developed.</entry>
+ </row>
+ <row>
+ <entry><productname>BBedit</productname></entry>
+ <entry>Plain-text editor for Apple Macs, heavily used
+ for text applications. <TeX/> distributions for the
+ Mac come with their own editor, but this is a popular
+ and useful tool. 30-day demo.</entry>
+ </row>
+ <row>
+ <entry><productname>vi</productname></entry>
+ <entry>Standard editor on Unix systems. Dual-mode editor
+ (separate text-entry and command modes), now showing
+ its age. Adored by devotees, detested by others, just
+ like
+ <productname>Emacs</productname>&nbsp;&smiley;.&nbsp;
+ Free.</entry>
+ </row>
+ <row>
+ <entry><productname>tkcEditor</productname></entry>
+ <entry>Multipurpose text editor for handheld computers
+ from TheKompany.com. Good editing features and
+ syntactic coloration of text. &dollar;14.95 for
+ Zaurus systems.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+-->
+ <warning id="pdfurl">
+ <title>Additional downloads</title>
+ <para>For licensing reasons, the
+ <productname>GSview</productname> PostScript/PDF previewer,
+ the <productname>Acrobat Reader</productname> PDF previewer,
+ and the <productname>WinEdt</productname> editor could not
+ be distributed on the 2003 CDs. In those cases you have to
+ download and install them separately.</para>
+ <itemizedlist>
+ <listitem>
+ <para><productname>GSview</productname> is available for
+ all platforms from <ulink
+ url="http://www.ghostscript.com/gsview/index.htm"></ulink>
+ (on Unix and VMS systems it&apos;s also available as
+ <productname>GhostView</productname> and
+ <productname>gv</productname>: see <ulink
+ url="http://www.cs.wisc.edu/~ghost/"></ulink>)</para>
+ </listitem>
+ <listitem>
+ <para><productname>Acrobat Reader</productname> (all
+ platforms) can be downloaded from <ulink
+ url="http://www.adobe.com/products/acrobat/readstep2.html"></ulink></para>
+ </listitem>
+ <listitem>
+ <para><productname>WinEdt</productname> (Microsoft Windows
+ only) comes from <ulink
+ url="http://www.winedt.com"></ulink></para>
+ </listitem>
+ </itemizedlist>
+ </warning>
+ </sect1>
+ <sect1 id="lininst">
+ <title>Installation for Linux and Unix</title>
+ <para>Make sure your system libraries and utilities are up to
+ date. If you are using Red Hat Linux, use
+ <productname>yum</productname> or
+ <productname>up2date</productname> to download and install
+ updates. For Debian and other distributions, use
+ <productname>apt-get</productname> or similar. On Red Hat
+ systems, remove any RPM version of te<TeX/> and associated
+ utilities which may have been
+ preinstalled, in order to avoid version conflicts.</para>
+ <para>If you are installing <TeX/> Live to a new partition, and
+ you have the opportunity to reformat the partition before use,
+ use <productname>mkfs</productname> with a granularity as
+ small as it will go (usually 1024 bytes). This avoids the
+ partition running out of inodes because <TeX/> uses very large
+ numbers of very small files.</para>
+ <para>Plan the installation carefully if you are installing for
+ multiple users (a shared machine): read <xref
+ linkend="pkginst"/> for some comments on where to put additional
+ files downloaded later, and see the FAQ on the same topic at
+ <ulink
+ url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=wherefiles"></ulink></para>
+ <para>Above all, <acronym id="RTFM">Read The Fine
+ Manual</acronym>. The documentation is in
+ <filename>live.html</filename> and
+ <filename>live.pdf</filename> on the disk in the directory
+ <filename>texlive2004/texmf-doc/doc/english/texlive-en/</filename></para>
+ <figure>
+ <title><TeX/> Live installation manual</title>
+ <graphic fileref="tlcdoc" format="EPS" width="75%"/>
+ </figure>
+ <programlisting remap="commandchars=\\\{\}">
+# cd /<userinput>mnt/cdrom</userinput>/texlive2004
+# sh install-tl.sh
+ </programlisting>
+ <para>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.</para>
+ <para>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.</para>
+ <figure>
+ <title>The Unix installation program</title>
+ <programlisting width="scriptsize"><![CDATA[
+==================> TeX Live installation procedure <=================
+
+===> Note: Letters/digits in <angle brackets> indicate menu items <===
+===> for commands or configurable options <===
+
+ Proposed platform: Intel x86 with GNU/Linux
+ <P> over-ride system detection and choose platform
+ <B> binary systems: 1 out of 10
+ <S> Installation scheme (scheme_recommended)
+ [customizing installation scheme:
+ <C> standard collections <L> language collections]
+ 20 out of 75, disk space required: 246857 kB
+ <D> 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
+ <O> 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
+ <R> do not install files, set up to run off CD or DVD
+ <I> start installation
+ <H> help, <Q> quit
+
+Enter command:
+ ]]></programlisting>
+ </figure>
+ <para><quote>Collections</quote> (the <varname>C</varname> and
+ <varname>L</varname> options) are groups of <LaTeX/> packages
+ that you can include or exclude. It&apos;s best to leave this
+ alone unless you know you need something specific. The only
+ options I sometimes set are under <varname>O</varname>: the
+ <quote>alternate directory for generated fonts</quote> may
+ need to be on a different partition for performance reasons on
+ a shared system; and I always select <quote>create symlinks in
+ standard directories</quote> so that the system works
+ immediately after the post-installation configuration (after
+ installation, run <productname>texconfig</productname> to
+ adjust your local settings.</para>
+ <figure>
+ <title>Running the post-installation program
+ <productname>texconfig</productname></title>
+ <graphic fileref="texconfig" format="EPS" width="75%"/>
+ </figure>
+ <para>Note that the Linux/Unix installation does not install any
+ editors: it is assumed you can do this yourself from your
+ distribution&apos;s standard package system (most likely
+ you will already be using <productname>Emacs</productname> or
+ <productname>vi</productname> anyway).</para>
+ </sect1>
+ <sect1 id="macinst">
+ <title>Installation for Apple Mac</title>
+ <para>This is exactly the same interface as for the Linux/Unix
+ installation. You need the <productname>bash</productname>
+ shell (see the warning in the manual for users of older systems).</para>
+ <para>There is a choice of graphical editors for the Mac: two
+ are included on the DVD, <productname><TeX/>Shop</productname>
+ and <productname>I<TeX/>Mac</productname>, but they need to be
+ installed separately, after installing <TeX/>.</para>
+ </sect1>
+ <sect1 id="wininst">
+ <title>Installation for Microsoft Windows</title>
+ <figure>
+ <title><TeX/> Collection 2004 DVD</title>
+ <graphic fileref="tcdvddir" width="75%"/>
+ </figure>
+ <para>Before you install <TeX/>, 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 (<ulink
+ url="http://www.microsoft.com/"></ulink>) and click on
+ <productname>Windows Update</productname>. 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 <productname>ScanDisk</productname> and give your hard
+ disks a full surface check. <TeX/> consists of a very large
+ number of quite small files, so it&apos;s important that your
+ disk is in good order.</para>
+<!--
+ <para>Newcomers should note that the
+ downloadable <productname>WinEdt</productname> comes
+ preconfigured for MiK<TeX/>) and needs some careful
+ reconfiguration to work with the 2003 <TeX/> Live
+ installation. I recommend that beginners
+ use <productname>WinShell</productname> to start with and
+ graduate to <productname>Emacs</productname> or
+ <productname><TeX/>nicCenter</productname> when they become
+ more expert. Many other people will doubtless tell you
+ different&hellip;</para>
+-->
+ <para>When you insert the distribution
+ DVD or CD, it should start the setup program automatically. If
+ you have auto-run turned off, open <productname>My
+ Computer</productname>, double-click on the DVD or CD drive,
+ and then double-click <productname>Autorun</productname> to
+ start the setup program.<footnote>
+ <para>Some builds of Windows seem to have a bug that stops
+ <productname>Autorun</productname> starting the
+ installation. In that case (for the <TeX/> Collection 2004
+ DVD) double-click <filename>Setup.exe</filename> instead,
+ or (for the <TeX/>
+ Collection 2003 CD) go to the <filename>tpm</filename>
+ folder and double-click on
+ <filename>TeXSetup.exe</filename>.</para>
+ </footnote></para>
+ <sect2>
+ <title>pro<TeX/>t (<TeX/> Collection 2004)</title>
+ <para>For pro<TeX/>t from the <TeX/>
+ Collection DVD, follow the instructions in the PDF
+ documentation which opens automatically when you start
+ the setup.</para>
+ <figure>
+ <title>pro<TeX/>t comes with its own installation
+ guide</title>
+ <graphic fileref="tcptpdf" width="50%"/>
+ </figure>
+ <para>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 <orderedlist>
+ <listitem>
+ <para><productname>MIK<TeX/></productname></para>
+ </listitem>
+ <listitem>
+ <para><emphasis
+ role="high">either</emphasis>&nbsp;<productname>WinEdt</productname>
+ (with or without some of its add-ons) <emphasis
+ role="high">or</emphasis>&nbsp;<productname><TeX/>nicCenter</productname></para>
+ </listitem>
+ <listitem>
+ <para><productname>GhostScript</productname> and
+ <productname>GSview</productname></para>
+ </listitem>
+ </orderedlist>.</para>
+ <warning>
+ <para>You only need to install items <xref linkend="nldi"/>
+ to <xref linkend="td"/> if you install
+ <productname>WinEdt</productname>.</para>
+ </warning>
+ <figure floatstyle="b" id="tcpt1">
+ <title>First document in
+ <productname><TeX/>nicCenter</productname></title>
+ <graphic fileref="tcptfirstdoc" width="75%"/>
+ </figure>
+ <procedure>
+ <step>
+ <title>Install <productname>MIK<TeX/></productname></title>
+ <para><productname>pro<TeX/>t</productname> uses the
+ <productname>MIK<TeX/></productname> distribution as its
+ core, a long-established and popular distribution for
+ Windows.</para>
+ </step>
+ <step>
+ <title>Install <productname>WinEdt</productname></title>
+ <para>This is optional: it&apos;s a good editor,
+ especially for the heavy user of a
+ <productname>MIK<TeX/></productname>-based system. This is
+ a free month&apos;s trial&mdash;after that it reminds you to cough
+ up and register.</para>
+ </step>
+ <step id="nldi">
+ <title>Install the <productname>WinEdt</productname> New <LaTeX/> Document Interface</title>
+ <para>Optional again, and only applicable if you installed
+ <productname>WinEdt</productname> anyway. It lets you
+ save commonly-used document settings for use in other
+ documents of the same type.</para>
+ </step>
+ <step>
+ <title>Install the <productname>WinEdt</productname>
+ Graphics Interface</title>
+ <para>Another optional add-on for
+ <productname>WinEdt</productname> to provide drag-and-drop
+ graphics insertion.</para>
+ </step>
+ <step id="td">
+ <title>Install the <productname>WinEdt</productname> Table
+ Designer</title>
+ <para>Last optional add-on for
+ <productname>WinEdt</productname>, providing a new table editor.</para>
+ </step>
+ <step>
+ <title>Install <productname><TeX/>nicCenter</productname></title>
+ <para>This is a free equivalent to
+ <productname>WinEdt</productname>. The interface is
+ slightly different (see <xref linkend="tcpt1"/>) but it
+ is becoming very popular.</para>
+ </step>
+ <step>
+ <title>Install <productname>GhostScript</productname> and
+ <productname>GSview</productname></title>
+ <para>These are essential for viewing the PostScript and
+ PDF output, especially if you don&apos;t have any other PDF
+ viewer installed.</para>
+ </step>
+ </procedure>
+ <para>You get a choice of editors,
+ but the one which features in
+ <productname>pro<TeX/>t</productname> is
+ <productname><TeX/>nicCenter</productname>. This is an
+ <acronym id="IDE">Integrated Development
+ Environment</acronym> which lets you manage all the files
+ related to each document. In many cases, of course, you&apos;ll
+ only have one (the text itself) but if you are working with
+ anything beyond simple articles, you&apos;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&apos;s a
+ single-file article, as I did for the example in <xref
+ linkend="tcpt1"/>.</para>
+ </sect2>
+ <sect2>
+ <title><TeX/> Live (<TeX/> Collection 2003)</title>
+ <procedure>
+ <title>Once the installation program is running:</title>
+ <step>
+ <title><LaTeX/></title>
+ <para>Install <LaTeX/> itself from the
+ <guimenu>TeXLive Software</guimenu><guimenuitem>Install on
+ Hard Disk</guimenuitem> menu. If you&apos;re new to
+ <LaTeX/>, pick Quick Install on the following screen. This
+ gives you everything you need to get started, and
+ doesn&apos;t ask any questions, it just installs it all
+ straight away.</para>
+ <para>If you&apos;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.</para>
+ <para>If you want to use <productname>Emacs</productname>
+ as your editor, click the option for Xem<TeX/>
+ Support.<footnote>
+ <para>Note this unfortunate choice of name is nothing
+ to do with <personname id="em">
+ <firstname>Eberhard</firstname>
+ <surname>Matthes</surname>
+ </personname>&apos; MS-DOS implementation of <TeX/>
+ called em<TeX/>&mdash;the <quote>Xem</quote> is
+ short for <productname>Xemacs</productname>.</para>
+ </footnote></para>
+ </step>
+ <step>
+ <title>Emacs</title>
+ <para>After installation, right-click and drag
+ <filename>Xemacs.exe</filename> from the
+ <filename>C:\Program Files\TeXLive\bin\win32</filename>
+ folder out onto your desktop and let go, then pick
+ <quote>Create Shortcut</quote>. This places
+ <productname>Emacs</productname> on your desktop for
+ easy access.</para>
+ </step>
+ <step>
+ <title>WinShell and WinEdt</title>
+ <para>If you want to install
+ <productname>WinShell</productname>, run the installer
+ program in the <filename>support/winshell</filename>
+ directory. For <productname>WinEdt</productname> you
+ must go to their Web site (<ulink
+ url="http://www.winedt.com/"></ulink>) for a
+ downloadable version.</para>
+ <para>You don&apos;t have to install just one editor: if
+ you&apos;ve got the space, install them all so you can
+ try them out. You can always uninstall the ones you
+ don&apos;t want afterwards.</para>
+ </step>
+ <step>
+ <title>GSView</title>
+ <para>Ghostscript is installed automatically, but for
+ <productname>GSView</productname> you need to go to
+ <ulink
+ url="http://www.cs.wisc.edu/~ghost/gsview/"></ulink>,
+ and download the most recent version.</para>
+ <para>If you use <productname>GSView</productname>, please
+ register your copy with Ghostgum, Pty.&nbsp;(<ulink
+ url="http://www.ghostgum.com.au/"></ulink>).</para>
+ </step>
+ </procedure>
+ <warning>
+ <para>Please read the <TeX/> Live update pages at <ulink
+ url="http://www.tug.org/texlive/bugs.html"></ulink> for
+ details of any changes since the disks were released, and
+ download and install any additional software
+ required.</para>
+ </warning>
+ </sect2>
+ <sect2>
+ <title>Installation problems</title>
+ <para>It&apos;s always annoying when a program that&apos;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&apos;ve installed <TeX/> hundreds of times and very
+ rarely had any difficulties, but these are a few of the
+ occasions when I did.</para>
+ <variablelist>
+ <varlistentry>
+ <term>Bad hard disks</term>
+ <listitem>
+ <para>As recommended in <xref linkend="wininst"/>, 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&apos;s been in heavy use. <TeX/> uses a very
+ large number of very small files, so there is a lot of
+ disk activity during an installation. As also
+ recommended in <xref linkend="lininst"/>, if you have
+ the chance to reformat the hard disk, pick the
+ smallest granularity (cluster size) possible.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Registry errors</term>
+ <listitem>
+ <para>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&apos;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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="latest">
+ <term>Use the latest versions</term>
+ <listitem>
+ <para>Before installing, check the <acronym
+ ref="CTAN"></acronym> web site (<ulink
+ url="http://www.ctan.org/"></ulink> for any updated
+ copy of the installation program. This is called
+ <filename>install-tl.sh</filename> for Linux and Mac
+ systems, and <filename>Setup.exe</filename> for
+ Microsoft Windows (on the <TeX/> Collection 2003 CD it
+ was called <filename>TeXSetup.exe</filename>). Just
+ occasionally a bug slips through onto the production
+ CD or DVD, and although it&apos;s always fixed and notified
+ on <ulink url="comp.text.tex" type="news:"></ulink>,
+ that&apos;s a high-volume newsgroup and even the sharpest
+ eyes may miss an announcement.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Stick to the defaults</term>
+ <listitem>
+ <para>Unless you&apos;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&apos;re that way for a purpose,
+ especially when it comes to avoiding directories will
+ spaces in their names, like the notorious
+ <literal>C:\Program Files</literal>. 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
+ <literal>My Cute Stuff</literal>, but please
+ don&apos;t: you&apos;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.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+ </sect1>
+ </chapter>
+ <chapter id="plaintext">
+ <title>Using your editor <?LaTeX \newline{}?>to create documents</title>
+ <para><LaTeX/> documents are all <firstterm
+ id="plain-text">plain-text</firstterm> files.<footnote>
+ <para><wordasword>Plain-text</wordasword>
+ originally meant just the 95 printable characters of the
+ <acronym id="ASCII">American Standard Code for Information
+ Interchange</acronym>&mdash;see <xref
+ linkend="asciicodes"/>&mdash;but now more commonly includes
+ both these <emphasis>and</emphasis> the relevant 8-bit
+ characters from <emphasis>one</emphasis> (only) character
+ set such as ISO-8859-1 (Western Latin&ndash;1) or
+ ISO-8859-15 (Western Latin plus the Euro sign). These are
+ international standards which work everywhere: you should
+ avoid using manufacturers&apos; proprietary character sets
+ like Microsoft Windows&ndash;1252 or Apple Macintosh
+ Roman&ndash;8, because they may make your documents unusable
+ on some other systems.</para>
+ </footnote> You can edit them with any editor, and transfer
+ them to any other computer system running <LaTeX/> 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&apos; proprietary
+ <wordasword>gotchas</wordasword> like suddenly going out of date
+ with a new version.</para>
+ <sect1 id="mark-up">
+ <title>Markup</title>
+ <para>In a <LaTeX/> document, you type your text along with
+ <firstterm id="markup">markup</firstterm> which identifies the
+ important parts of your document by name, for example
+ <quote>title</quote>, <quote>section</quote>,
+ <quote>figure</quote>, &etc; <LaTeX/> does all the formatting
+ for you automatically, using the markup to guide its internal
+ rules and external stylesheets for typesetting.</para>
+ <sidebar>
+ <title>Markup</title>
+ <para>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
+ <emphasis>ages</emphasis>.</para>
+ <informaltable rowsep="4pt">
+ <tgroup cols="3">
+ <colspec colsep="flush" align="left"/>
+ <colspec colname="b" colwidth=".75in" align="left"/>
+ <colspec align="right" colsep="flush"/>
+ <tbody>
+ <row>
+ <entry><graphic fileref="55-1L-part"
+ width="2in"/></entry>
+ <entry spanname="2"><citetitle show="title"
+ ref="tain"></citetitle></entry>
+ </row>
+ <row>
+ <entry><graphic fileref="23-part"
+ width="2in"/></entry>
+ <entry spanname="2"><citetitle show="title"
+ ref="varmints"></citetitle></entry>
+ </row>
+ <row>
+ <entry><literal>.h1 Interest Rates</literal></entry>
+ <entry>Runoff</entry>
+ <entry><foreignphrase>c.</foreignphrase>1970</entry>
+ </row>
+ <row>
+ <entry><literal>\section{Interest
+ Rates}</literal></entry>
+ <entry><LaTeX/></entry>
+ <entry>1984</entry>
+ </row>
+ <row>
+ <entry><literal><![CDATA[<sec><ttl>Interest
+ Rates</ttl>...]]></literal></entry>
+ <entry><acronym ref="SGML"></acronym></entry>
+ <entry>1985</entry>
+ </row>
+ <row>
+ <entry><literal><![CDATA[<H1>Interest
+ Rates</H1>]]></literal></entry>
+ <entry><acronym ref="HTML"></acronym></entry>
+ <entry>1991</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sidebar>
+ <para>You do not need to format any of your text <emphasis>in
+ your editor</emphasis>, because <LaTeX/> does it
+ all by itself when it typesets. You can of course regularise
+ or neaten its appearance <emphasis>in your editor</emphasis>
+ for ease of editing (for example, keeping each item in a list
+ on a separate line), but this is not required.</para>
+ <para>You will often hear <LaTeX/> markup referred to as
+ <quote>commands</quote> or sometimes <quote>control
+ sequences</quote> (the proper <TeX/>nical term for them).
+ For
+ all practical purposes these terms all mean the same
+ thing.</para>
+ <para>This course assumes that users have one of
+ <productname><TeX/>shell</productname>,
+ <productname><TeX/>nicCenter</productname>,
+ <productname>WinShell</productname>, or
+ <productname>WinEdt</productname> (Windows only), or
+ <productname>Emacs</productname> or <LyX/> (any platform)
+ installed. These are discussed briefly in <xref
+ linkend="editors"/>, and the menus and toolbars for running
+ <LaTeX/> are explained in <xref
+ linkend="process"/>.</para>
+ </sect1>
+ <sect1 id="quickstart">
+ <title>Quick start for the impatient</title>
+ <para>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&apos;d probably like to type something in and see <LaTeX/>
+ do its job. If you don&apos;t, then skip forward to <xref
+ linkend="commands"/> and read a bit more about <LaTeX/>
+ first.</para>
+ <figure id="sampledoc">
+ <title>Sample document</title>
+ <programlisting width="footnotesize">
+\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}
+ </programlisting>
+ </figure>
+ <procedure>
+ <title>Up and running in a few minutes</title>
+ <step>
+ <title>Install the software</title>
+ <para>Make sure you have a
+ properly-installed <LaTeX/> system and a copy of a
+ suitable editor.</para>
+ </step>
+ <step id="demodoc">
+ <title>Create a sample document</title>
+ <para>Open your editor and type in
+ the text <emphasis>exactly</emphasis> as shown in <xref
+ linkend="sampledoc"/>. Do <emphasis>not</emphasis> make any
+ changes or miss anything out or add anything different at
+ this stage.</para>
+ </step>
+ <step>
+ <title>Save the document</title>
+ <para>Save the document as
+ <filename>demo.tex</filename></para>
+ </step>
+ <step>
+ <title>Run <LaTeX/> or <productname>pdf<LaTeX/></productname></title>
+ <para>Click on the <guiicon><LaTeX/></guiicon> or
+ <guiicon>pdf<LaTeX/></guiicon> toolbar icon or the
+ <guimenu><TeX/></guimenu><guimenuitem><TeX/>
+ File</guimenuitem> menu item; or type <literal>latex
+ demo</literal> or <literal>pdflatex demo</literal> in a
+ command window.</para>
+ </step>
+ <step>
+ <title>Preview the typesetting</title>
+ <para>Click on the <guiicon>DVI</guiicon> or
+ <guiicon>PDFview</guiicon> toolbar icon or the
+ <guimenu><TeX/></guimenu><guimenuitem><TeX/>
+ View</guimenuitem> menu item; or type your previewer
+ command in a terminal shell.</para>
+ <para>(Note that there may be a pause the first time you use
+ your <acronym ref="DVI"></acronym> viewer, while <acronym
+ ref="WYSIWYG"></acronym> font files are
+ created.<footnote>
+ <para><acronym ref="DVI"></acronym> 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&apos;s pause
+ while it gets created. The more you use <LaTeX/>, the
+ less this
+ happens.</para>
+ </footnote>)</para>
+ </step>
+ <step>
+ <title>Print it</title>
+ <para>Click on the <guiicon>Print</guiicon> toolbar icon
+ within the viewer, or use the
+ <guimenu><TeX/></guimenu><guimenuitem><TeX/> Print</guimenuitem>
+ menu item, or type
+ <literal>dvips -f demo | lpr</literal>
+ (Unix/Linux).</para>
+ </step>
+ </procedure>
+ <para>If you encounter any errors, it means you
+ <emphasis>do</emphasis> need to study this chapter after
+ all!</para>
+ </sect1>
+ <sect1 id="editors">
+ <title>Editors</title>
+ <indexterm><primary>editors</primary></indexterm>
+ <para>All the text of your documents can be typed into your
+ <LaTeX/> 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 <LaTeX/> easier.
+ Some of the most popular are
+ <productname><TeX/>shell</productname>
+ <productname>WinShell</productname>, <productname><TeX/>nic
+ Center</productname>, and <productname>WinEdt</productname>
+ (Windows only); and <productname><LyX/></productname> and
+ <productname>Emacs</productname> (all platforms).</para>
+ <sect2>
+ <title><LyX/></title>
+ <figure id="lyxwin">
+ <title>The <LyX/> document editor</title>
+ <graphic fileref="lyx" width="75%"/>
+ </figure>
+ <para>The <LyX/> document editor (all platforms) is a special
+ case, as it uses the <acronym id="WYSIWYM">What You See Is
+ What You Mean</acronym> model of synchronous typographic
+ editing as opposed to <acronym id="WYSIWYG">What You See Is
+ What You Get</acronym>, and many users prefer this
+ interface (but see the reservations in <xref
+ linkend="sync"/>).</para>
+ <para><LyX/> makes a strong case for using synchronous
+ typographical editing: it is possible to create even quite
+ large and complex documents without seeing a backslash very
+ often, although with math or complex macros there is
+ probably no way to avoid having to do some manual insertion
+ of
+ <LaTeX/> code.</para>
+ <para>The free availability on multiple platforms makes this a
+ clear answer to the myth of <quote>having to edit like a
+ programmer</quote>, and as it is an Open Source project,
+ there is constant improvement, both to the facilities and to
+ the interface.</para>
+ <para>Probably the only real reservation is that it does not
+ save native <LaTeX/> files by default. It uses its own
+ internal format, and it can export <LaTeX/> for use in other
+ editors, but the exported files are not designed for human
+ legibility, only for <LaTeX/> processing. In a co-operative
+ environment this would be a serious drawback, but for the
+ individual user this interface is an excellent tool.</para>
+ </sect2>
+ <sect2 id="texshell">
+ <title><TeX/>shell</title>
+ <figure id="texshellwin">
+ <title>The <TeX/>shell editor</title>
+ <graphic fileref="texshell" width="75%"/>
+ </figure>
+ <para>This is one of the simplest of all the plaintext Windows
+ editors, but it has most of the tools needed to begin with.
+ Sectioning, lists, and graphics can be inserted from the
+ menus, and there are buttons for running <LaTeX/> on the
+ open document and for previewing the typeset
+ document.</para>
+ <para>The syntactic highlighting distinguishes between
+ commands and your text, and it comes with options for
+ spellchecking (you need to install
+ <productname>ispell</productname>), and for adding math,
+ Greek (math), and some symbol characters from a pickchart.
+ The typeset display is done using your installed <acronym
+ ref="DVI"></acronym> viewer (there is no provision for
+ <acronym ref="PDF"></acronym>, although as it is
+ configurable, that could probably be edited into the
+ menus).</para>
+ <para>Download the <filename>.tar.gz</filename> file from <acronym
+ ref="CTAN"></acronym> in the
+ <filename>support/TeXshell/</filename> directory and unwrap
+ it into somewhere like <filename>C:\Program
+ Files\TeXshell\</filename>.<footnote>
+ <para>Yes, I know I said don't use directory names with
+ spaces in them&mdash;and so you shouldn&apos;t, for your
+ <LaTeX/> documents&mdash;but Windows programs are usually safe
+ enough in them.</para>
+ </footnote> There is a <productname>tsconfig</productname>
+ program in the same directory on <acronym
+ ref="CTAN"></acronym>, which is designed to help with
+ reconfiguring <TeX/>shell.</para>
+ </sect2>
+ <sect2 id="winshell">
+ <title>WinShell</title>
+ <figure id="winshellwin">
+ <title>The WinShell editor</title>
+ <graphic fileref="winshell" width="75%"/>
+ </figure>
+ <para>This is another free Windows editor for beginners with
+ <LaTeX/>. Despite its simplicity, it is capable of a
+ considerable amount of document management and assistance
+ with editing. As well as handling stand-alone <LaTeX/>
+ files, you can create a <quote>Project</quote> for larger
+ documents, which helps you keep track of additional files
+ like separate chapters, illustrations, diagrams, indexes,
+ &etc;</para>
+ <para>You run <LaTeX/> direct from the toolbar icons or with
+ F-key shortcuts. Both standard <LaTeX/> and
+ <productname>pdf<LaTeX/></productname> are supported, as well
+ as creation and previewing of
+ <trademark>PostScript</trademark> and <acronym
+ ref="PDF"></acronym> output. There are additional toolbars
+ for math characters, and there is a <quote>Table
+ Wizard</quote> for handling tables. The syntax
+ highlighting distinguishes between commands (in blue) and
+ delimiters (in red), leaving your text in black.</para>
+ <para>Download the
+ <filename>WinShell<userinput>nn</userinput>.exe</filename>
+ program (self-contained setup: the
+ <userinput>nn</userinput> changes with the version) from
+ <acronym ref="CTAN"></acronym> in the
+ <filename>systems/win32/winshell/</filename> directory and
+ double-click it to start the setup.</para>
+ </sect2>
+ <sect2 id="texniccenter">
+ <title><TeX/>nicCenter</title>
+ <figure id="texniccenterwin">
+ <title>The <TeX/>nicCenter editor</title>
+ <graphic fileref="texniccenter" width="75%"/>
+ </figure>
+ <para><productname><TeX/>nicCenter</productname> is a powerful
+ Windows editor suitable both for the beginner and the more advanced
+ user. Its <quote>Project</quote> environment keeps track of
+ multiple files, and the processing function (the bit which
+ actually runs <LaTeX/>, here called
+ <quote>Build</quote>) 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.</para>
+ <para>It&apos;s a much more wordprocessor-like control
+ interface, with configurable toolbars and button-controls
+ for lists, math, tables, and previewing options.</para>
+ <para>Download the
+ <filename>TXCSetup<userinput>xxx</userinput>.exe</filename>
+ program (self-contained setup: the
+ <userinput>xxx</userinput> bit changes with the version)
+ from <acronym ref="CTAN"></acronym> in the
+ <filename>systems/win32/TeXnicCenter/</filename> directory
+ and double-click it to start the setup.</para>
+ </sect2>
+ <sect2 id="winedt">
+ <title>WinEdt</title>
+ <figure id="winedtpic">
+ <title>The <productname>WinEdt</productname> editor</title>
+ <graphic fileref="winedt" width="75%"/>
+ </figure>
+ <para><productname>WinEdt</productname> is a highly
+ configurable plain-text editor for Windows. It comes with a
+ host of special functions and shortcuts for
+ <TeX/> and <LaTeX/>, based on the Mik<TeX/> distribution. It
+ is supplied on the <TeX/> Collection 2004 DVD and the
+ <productname>pro<TeX/>t</productname> CD. You can also
+ download it from <ulink
+ url="http://www.winedt.com"></ulink>&mdash;in either case
+ there&apos;s a 1-month free trial, then it reminds you to
+ buy it.</para>
+ <para><productname>WinEdt</productname> uses a built-in
+ toolbar of configurable buttons, preset for use with
+ <LaTeX/>, and it provides syntactic coloring of
+ <LaTeX/> commands. Both the positioning and effect of the
+ buttons can be changed, using an editable file of icons and
+ a configuration panel. This flexibility lets you bind a
+ program and arguments (equivalent to a typed command) to a
+ particular icon.</para>
+ <para>There are default buttons on the toolbar for one-click
+ typesetting, previewing, and
+ <trademark>PostScript</trademark> or <acronym
+ ref="PDF"></acronym> generation from <LaTeX/> documents,
+ and it manages multi-file document projects like most of the
+ other editors. <productname>Winedt</productname> is also
+ used by many people for normal plaintext file-editing tasks,
+ in preference to more limited programs like
+ <productname>Notepad</productname>. If you're using the
+ fp<TeX/> which came with the 2003 <TeX/>
+ Collection, some editing of the menus is required (explained
+ in the local installation document) because the default
+ setup is for
+ Mik<TeX/>/pro<TeX/>t.</para>
+ </sect2>
+ <sect2>
+ <title>GNU Emacs</title>
+ <figure>
+ <title>Emacs editing <LaTeX/></title>
+ <graphic fileref="emacs" width="75%"/>
+ </figure>
+ <para><productname>Emacs</productname> is a product of the
+ <acronym ref="GNU"></acronym> Project.<footnote>
+ <para><quote><acronym id="GNU">GNU&apos;s Not
+ Unix</acronym></quote> is a project to make a
+ computing environment completely free of
+ restrictions.</para>
+ </footnote> Versions are available for all makes and models
+ of computer, and it has a <LaTeX/>-mode which provides
+ syntactic colouring (<wordasword>fontification</wordasword>
+ in <productname>Emacs</productname>-speak) and mouseclick
+ processing from a menu or toolbar.</para>
+ <para><productname>Emacs</productname>
+ is a very large and powerful editor, with
+ <wordasword>modes</wordasword> (plug-ins) to handle almost
+ everything you do on a computer. Many users run
+ <productname>Emacs</productname> once on logging in, and
+ never leave it for the rest of the day&mdash;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&mdash;including <acronym ref="XML"></acronym> and
+ <LaTeX/>&mdash;and it provides a few games as well.</para>
+ <para><productname>Emacs</productname>
+ knows about <LaTeX/> and how to process it, so it comes with
+ a menu full of <LaTeX/> operations to click on. If you are
+ editing complex documents with mathematics, there is a mode
+ (<productname>AUC<TeX/></productname>) which has even more
+ functionality. <LaTeX/> support is well-developed, and there
+ is a hierarchy of newsgroups for
+ <productname>Emacs</productname> support.</para>
+ <para>Because <productname>Emacs</productname> runs on
+ Microsoft Windows, Macs, Linux, and most other platforms,
+ many <LaTeX/> users who have multiple machines (and those
+ who have multiple users to support) prefer it to other
+ editors because it provides the same environment regardless
+ of which platform they are using.</para>
+ <para>It&apos;s sometimes criticised for a steep learning
+ curve, but in fact it&apos;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.</para>
+ </sect2>
+ <sect2>
+ <title>Mac editors</title>
+ <para>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.</para>
+ </sect2>
+ </sect1>
+ <sect1 id="commands">
+ <title><LaTeX/> commands</title>
+ <para id="bsol"><LaTeX/> commands all begin with a
+ <firstterm id="backslash">backslash</firstterm>
+ (<literal>\</literal>)<footnote>
+ <para>Do not confuse the backslash
+ with the forward slash (<literal>/</literal>). 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 <LaTeX/> to begin a
+ command.</para>
+ </footnote> and are usually made up of lowercase
+ letters only, for example:</para>
+ <programlisting>
+\tableofcontents
+ </programlisting>
+ <para>The
+ <command>tableofcontents</command> command is an instruction
+ to <LaTeX/> 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&apos;t have
+ to do anything else. Provided that you have used the
+ sectioning commands described in <xref linkend="sections"/>,
+ all the formatting and numbering for the Table of Contents is
+ completely automated.</para>
+ <sect2 id="simplecmd">
+ <title>Simple commands</title>
+ <para id="swallow">Simple one-word commands like
+ <command>tableofcontents</command> must be separated from
+ any following text with <firstterm
+ id="wsp">white-space</firstterm>. This means a
+ normal space, or a newline [linebreak] or a TAB character.
+ For example either of these two forms will work:</para>
+ <programlisting>
+\tableofcontents Thanks to Aunt Mabel for all her help
+with this book.
+ </programlisting>
+ <programlisting>
+\tableofcontents
+Thanks to Aunt Mabel for all her help with this book.
+ </programlisting>
+ <para>If you forget the white-space, as in the following
+ example, <LaTeX/> will try to read it as a command
+ called <literal>\tableofcontentsThanks</literal>. There&apos;s no
+ such command, of course, so <LaTeX/> will complain at you by
+ displaying an error message (see <xref linkend="undefcs"/>).</para>
+ <programlisting>
+\tableofcontentsThanks to Aunt Mabel for all her help
+with this book.
+ </programlisting>
+ <para><LaTeX/> swallows any white-space which follows a command
+ ending in a letter. It does this automatically, so you
+ don&apos;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.</para>
+ </sect2>
+ <sect2 id="cmdargs">
+ <title>Commands with arguments</title>
+ <para>Many <LaTeX/> commands are followed by one or more
+ <firstterm id="arguments">arguments</firstterm>, a term from
+ the field of Computer Science, meaning information to be acted
+ upon. Here are two examples:</para>
+ <programlisting>
+\chapter{Poetic Form}
+\label{pform}
+ </programlisting>
+ <para>Such arguments always go in
+ <literal>{</literal><firstterm id="curly">curly
+ braces</firstterm><literal>}</literal> like
+ those<indexterm>
+ <primary>braces</primary>
+ <see>curly braces</see>
+ </indexterm> shown above. Be careful not to confuse the
+ curly braces on your keyboard with round parentheses
+ <literal>(&nbsp;)</literal>, square brackets
+ <literal>[&nbsp;]</literal>, or angle brackets
+ <literal><![CDATA[<]]>&nbsp;></literal>. They are all
+ different and they do different things.</para>
+ <para>With commands that take arguments you do
+ <emphasis>not</emphasis> 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&apos;s harder to edit:
+ normally you&apos;d leave a blank line between the chapter title or
+ label and the start of the first paragraph).</para>
+ <programlisting>
+\chapter{Poetic Form}\label{pform}The shape of poetry
+when written or printed distinguishes it from prose.
+ </programlisting>
+ </sect2>
+ <sect2 id="white-space">
+ <title>White-space in <LaTeX/></title>
+ <indexterm>
+ <primary>white-space</primary>
+ </indexterm>
+ <para>In <LaTeX/> documents, all <emphasis>multiple</emphasis>
+ spaces, newlines (linebreaks), and TAB characters are
+ treated as if they were a <emphasis>single</emphasis> space
+ or newline during typesetting. <LaTeX/> does its own spacing
+ and alignment using the instructions you give it, so you
+ have extremely precise control. You are therefore free to
+ use extra white-space in your editor for optical ease and
+ convenience when editing.</para>
+ <para>
+ The following is therefore exactly equivalent to the example
+ in the preceding section:</para>
+ <programlisting>
+\chapter {Poetic
+ Form}\label
+ {pform}
+
+The shape of poetry when written or printed
+distinguishes it from prose.
+ </programlisting>
+ <para>That is, it will get typeset exactly the same. In
+ general, just leave a blank line between paragraphs and a
+ single space between words and sentences. <LaTeX/> will take
+ care of the formatting.</para>
+ </sect2>
+ </sect1>
+ <sect1 id="specials">
+ <title>Special characters</title>
+ <indexterm>
+ <primary>special characters</primary>
+ </indexterm>
+ <para>There are ten keyboard characters which have special
+ meaning to <LaTeX/>, and cannot be used on their own except for
+ the following purposes:</para>
+ <informaltable colsep="1mm">
+ <tgroup cols="4">
+ <colspec align="center"/>
+ <colspec align="left"/>
+ <colspec align="center"/>
+ <colspec align="center"/>
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Meaning</entry>
+ <entry colwidth="1.5in"><emphasis>If you need<?html
+ <br>?> the actual character<?html <br>?> itself,
+ type:</emphasis></entry>
+ <entry>Character</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><keycap>&bsol;</keycap></entry>
+ <entry>The command character</entry>
+ <entry><command>textbackslash</command></entry>
+ <entry>&bsol;</entry>
+ </row>
+ <row>
+ <entry><keycap>&dollar;</keycap></entry>
+ <entry>Math typesetting delimiter</entry>
+ <entry><command>&dollar;</command></entry>
+ <entry>&dollar;</entry>
+ </row>
+ <row>
+ <entry><keycap>&percnt;</keycap></entry>
+ <entry>The comment character</entry>
+ <entry><command>&percnt;</command></entry>
+ <entry>&percnt;</entry>
+ </row>
+ <row>
+ <entry><keycap>&caret;</keycap></entry>
+ <entry>Math superscript character</entry>
+ <entry><command>&caret;</command></entry>
+ <entry>&caret;</entry>
+ </row>
+ <row>
+ <entry><keycap>&ampers;</keycap></entry>
+ <entry>Tabular column separator</entry>
+ <entry><command>&ampers;</command></entry>
+ <entry>&ampers;</entry>
+ </row>
+ <row>
+ <entry><keycap>&uline;</keycap></entry>
+ <entry>Math subscript character</entry>
+ <entry><command>&uline;</command></entry>
+ <entry><literallayout role="_">\texttt{\_}</literallayout></entry>
+ </row>
+ <row>
+ <entry><keycap>&tilde;</keycap></entry>
+ <entry>Non-breaking space</entry>
+ <entry><command>&tilde;</command></entry>
+ <entry>&tilde;</entry>
+ </row>
+ <row>
+ <entry><keycap>&hash;</keycap></entry>
+ <entry>Macro parameter symbol</entry>
+ <entry><command>&hash;</command></entry>
+ <entry>&hash;</entry>
+ </row>
+ <row>
+ <entry><keycap>&lbrace;</keycap></entry>
+ <entry>Argument start delimiter</entry>
+ <entry><command
+ userlevel="math">&lbrace;</command></entry>
+ <entry><literallayout role="{">$\{$</literallayout></entry>
+ </row>
+ <row>
+ <entry><keycap>&rbrace;</keycap></entry>
+ <entry>Argument end delimiter</entry>
+ <entry><command
+ userlevel="math">&rbrace;</command></entry>
+ <entry><literallayout role="}">$\}$</literallayout></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>These characters were deliberately chosen, either because
+ they are rare in normal text, or (in the case of &dollar;,
+ &hash;, &ampers;, and &percnt;) they already had an
+ established special meaning on computers as <firstterm
+ id="metacharacters">metacharacters</firstterm> (characters
+ standing as symbols for something else) by the time <TeX/> was
+ written, and it would have been misleading to choose
+ others.</para>
+ <sect2>
+ <title>Using the special characters</title>
+ <para>We have already seen (<xref linkend="bsol"/>) how
+ to use the backslash to start a command, and curly braces to
+ delimit an argument. The remaining special
+ characters are:</para>
+ <variablelist>
+ <varlistentry>
+ <term><keycap>&dollar;</keycap></term>
+ <listitem>
+ <para>Because of the special mathematical meaning
+ <LaTeX/> uses for the dollar-sign on its own, if you
+ want to print &dollar;35.99 you type
+ <literal>\$35.99</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><keycap>&percnt;</keycap></term>
+ <listitem>
+ <para id="comment">The <firstterm
+ id="commentchar">comment character</firstterm> makes
+ <LaTeX/> ignore the remainder of the line in your
+ document, so you can see it in your editor, but it
+ will never get typeset. For example <literal
+role="line">Today's price per kilo is £22.70 % get Mike to update this</literal>
+ <?LaTeX \\?>If you want to print 45&percnt; you need
+ to type <literal>45\%</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><keycap>&caret;</keycap></term>
+ <listitem>
+ <para>The caret sign lets you type
+ <literal>\(E=mc^2\)</literal> to get <inlineequation>
+ <m:mtext>E=mc</m:mtext>
+ <m:msup>
+ <m:mtext>2</m:mtext>
+ </m:msup>
+ </inlineequation>. If you need the circumflex accent
+ on a letter like ê, just type the letter or use the
+ symbolic notation <literal>\^e</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><keycap>&ampers;</keycap></term>
+ <listitem>
+ <para>The ampersand is used in tables to separate
+ columns (see <xref linkend="tables"/>). If you want to
+ print AT&ampers;T you need to type
+ <literal>AT\&amp;T</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><keycap>&uline;</keycap></term>
+ <listitem>
+ <para>The underscore lets you type
+ <literal>\(r_2\)</literal> for <inlineequation>
+ <m:mtext>r</m:mtext>
+ <m:msub>
+ <m:mtext>2</m:mtext>
+ </m:msub>
+ </inlineequation>. If you want to underline text
+ (extremely rare in typesetting) see <xref
+ linkend="uline"/>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="tilde">
+ <term><keycap>&tilde;</keycap></term>
+ <listitem>
+ <para>The tilde prints as a space, but prevents a
+ linebreak ever occurring at that point. It&apos;s often
+ used between a person&apos;s initials and their surname, eg
+ <literal>Prof D.E.~Knuth</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><keycap>&hash;</keycap></term>
+ <listitem>
+ <para>If you want a
+ <firstterm id="hash">hash mark</firstterm> (the
+ <firstterm id="octothorpe">octothorpe</firstterm> or
+ American number or <quote>pound</quote> [weight] sign)
+ you type <literal>\#</literal>. For a pound
+ (sterling)<indexterm><primary
+ sortas="pound">£</primary></indexterm>
+ sign &pound;, now nearly obsolete except in the UK and
+ some of its former dependencies, use your
+ <keycap>£</keycap> key or type
+ <command>textsterling</command>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>While we&apos;re on the subject of money, an unusual but
+ interesting serif-font Euro<indexterm>
+ <primary sortas="euro">&euro;</primary>
+ </indexterm> sign <format fontdefault="rm">&euro;</format>
+ is got with the <command>texteuro</command> command from the
+ <methodname>textcomp</methodname> package. The standard
+ sans-serif <format fontdefault="sf">&EUR;</format> needs the
+ <methodname>marvosym</methodname> package and is done with
+ the <command>EUR</command> command.<footnote>
+ <para>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.</para>
+ </footnote></para>
+ </sect2>
+ </sect1>
+ <sect1 id="quotes">
+ <title>Quotation marks</title>
+ <indexterm>
+ <primary>quotation marks</primary>
+ </indexterm>
+ <para>Do <emphasis>not</emphasis> use the unidirectional
+ typewriter keyboard <keycap remap="tt">&quot;</keycap> key for quotation
+ marks. Correct typographic quotes are got with the <keycap
+ remap="tt">&grave;</keycap> key and the <keycap
+ remap="tt">'</keycap> key, doubled if you want double
+ quotes:</para>
+ <informalexample>
+ <programlisting condition="pcr">
+He said, ``I'm just going out.''
+ </programlisting>
+ <para><format fontencoding="OT1" fontfamily="cmr">He said,
+ &ldquo;I&apos;m just going out.&rdquo;</format></para>
+ </informalexample>
+ <para>This ensures you get real left-hand
+ and right-hand (opening and closing) quotes (usually shaped
+ like tiny
+ <superscript>66</superscript>&nbsp;and&nbsp;<superscript>99</superscript>
+ or as symmetrically-balanced strokes). If you are using
+ <productname>Emacs</productname> as your editor, the
+ <keycap>&quot;</keycap> key is specially programmed in
+ <LaTeX/>-mode to think for itself and produce correct <format
+ fontdefault="tt">&grave;&grave;</format> and
+ <literal>''</literal> characters (so this is one occasion when
+ you <emphasis>can</emphasis> use the <keycap>&quot;</keycap>
+ key).</para>
+ <warning>
+ <para>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 <command>thinspace</command>
+ below may be too wide. Download the typeset (<acronym
+ ref="PDF"></acronym>) version of this document to see the
+ real effect.</para>
+ </warning>
+ <para id="thinspace">When typing one quotation inside another,
+ there is a special command <command>thinspace</command> which
+ provides just enough separation between double and single
+ quotes (a normal space is too much and could allow an unwanted
+ linebreak):</para>
+ <informalexample>
+ <programlisting condition="pcr">
+He said, `Her answer was ``never''\thinspace'.
+ </programlisting>
+ <para>He said, &lsquo;Her answer was
+ &ldquo;never&rdquo;&thinsp;&rsquo;.</para>
+ </informalexample>
+ </sect1>
+ <sect1 id="accents">
+ <title>Accents</title>
+ <indexterm>
+ <primary>accents</primary>
+ </indexterm>
+ <para>For accented letters in western
+ European languages<footnote>
+ <para>ISO 8859-1 (Latin&ndash;1, Western European) to
+ 8859-15 (includes the Euro).</para>
+ </footnote> or other Latin-alphabet character sets just use
+ the accented keys on your keyboard&mdash;if you have the right
+ ones. You must also tell <LaTeX/> what character repertoire
+ (<wordasword>input encoding</wordasword>) you are using. You
+ specify this by using the <methodname>inputenc</methodname>
+ package<footnote><para>We haven&apos;t covered the use of
+ packages yet. Don&apos;t worry, see <xref linkend="packages"/>
+ if you&apos;re curious.</para></footnote> in your preamble
+ with the relevant option. For example, to tell <LaTeX/> you
+ will be typing ISO Latin&ndash;1 accented characters,
+ use:</para>
+ <programlisting>
+\usepackage[latin1]{inputenc}
+ </programlisting>
+ <para>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
+ <literal>utf8</literal> instead of <literal>latin1</literal>.
+ The encoding definitions that are available on your system are
+ in <filename>/texmf/tex/latex/base</filename> (all files
+ ending in <filename>.def</filename>).</para>
+ <sidebar id="keystrokes">
+ <title>If you don&apos;t have accented letters</title>
+ <para>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:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Under Linux systems the letter
+ é is usually got with
+ <keycombo>
+ <keycap>AltGr</keycap>
+ <keycap>;</keycap>
+ </keycombo><keycap>e</keycap>. Refer to the
+ <productname>xkeycaps</productname> utility for a table
+ of key codes and combinations (get it from <ulink
+ url="http://www.jwz.org/xkeycaps/"></ulink>).</para>
+ </listitem>
+ <listitem>
+ <para>Under Microsoft Windows the letter é is got with
+ <keycombo>
+ <keycap>Ctrl</keycap>
+ <keycap remap="tt">'</keycap>
+ </keycombo><keycap>e</keycap> or by holding down the
+ <keycap>Alt</keycap> key and typing
+ <keycap>0</keycap><keycap>1</keycap><keycap>3</keycap><keycap>0</keycap>
+ on the numeric keypad (<emphasis>not</emphasis> the top
+ row of shifted numerals). Refer to the
+ <productname>charmap</productname> utility for a table
+ of key codes and combinations (find it in the
+ <filename>C:\Windows</filename> folder).</para>
+ </listitem>
+ </itemizedlist>
+ </sidebar>
+ <para>If you don&apos;t have accented letter keys on your
+ keyboard, you&apos;ll need to use your operating system&apos;s
+ standard keyboard <keycap>Ctrl</keycap> or
+ <keycap>Alt</keycap> key combinations to generate the
+ characters (see <xref linkend="keystrokes"/>).</para>
+ <para>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 <xref linkend="accentcodes"/>. In fact,
+ this can be used to put any accent over any letter: if you
+ particularly want a &gtilde; you can have one with the command
+ <command>&tilde;</command><literal>g</literal> (and Welsh
+ users can get &wcirc; with
+ <command>&caret;</command><literal>w</literal>).</para>
+ <para>If you use this symbolic method only, you do not need to
+ use the <methodname>inputenc</methodname> package. Before the
+ days of keyboards and screens with their own real accented
+ characters, the symbolic notation was the
+ <emphasis>only</emphasis> 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 <LaTeX/> file remains plain <acronym
+ ref="ASCII"></acronym>, which will work on all machines
+ everywhere, regardless of their internal encoding, and even
+ with very old <TeX/> installations.<footnote>
+ <para>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 <TeX/> because
+ their system administrators are too busy to
+ install new ones.</para>
+ </footnote></para>
+ <table id="accentcodes">
+ <title>Built-in <LaTeX/> accents</title>
+ <tgroup cols="3">
+ <colspec align="left"/>
+ <colspec align="center"/>
+ <colspec align="center"/>
+ <thead>
+ <row>
+ <entry>Accent</entry>
+ <entry>Example</entry>
+ <entry>Characters to type</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Acute (fada)</entry>
+ <entry>é</entry>
+ <entry><literal>\'e</literal></entry>
+ </row>
+ <row>
+ <entry>Grave</entry>
+ <entry>è</entry>
+ <entry><literal>\`e</literal></entry>
+ </row>
+ <row>
+ <entry>Circumflex</entry>
+ <entry>ê</entry>
+ <entry><literal>\^e</literal></entry>
+ </row>
+ <row>
+ <entry>Umlaut or diæresis</entry>
+ <entry>ë</entry>
+ <entry><literal>\"e</literal></entry>
+ </row>
+ <row>
+ <entry>Tilde</entry>
+ <entry>&ntilde;</entry>
+ <entry><literal>\~n</literal></entry>
+ </row>
+ <row>
+ <entry>Macron</entry>
+ <entry>&omacr;</entry>
+ <entry><literal>\=o</literal></entry>
+ </row>
+ <row>
+ <entry>Bar-under</entry>
+ <entry><format lining="under"
+ condition="HTML">&ohbar;</format><format
+ condition="LaTeX">&ohbar;</format></entry>
+ <entry><literal>\b o</literal></entry>
+ </row>
+ <row>
+ <entry>Dot-over (sé&inodot;&mdot;&inodot;ú)</entry>
+ <entry><format image="mdot"
+ condition="HTML">&mdot;</format><format
+ condition="LaTeX">&mdot;</format></entry>
+ <entry><literal>\.m</literal></entry>
+ </row>
+ <row>
+ <entry>Dot-under</entry>
+ <entry><format image="sdot"
+ condition="HTML">&sdot;</format><format
+ condition="LaTeX">&sdot;</format></entry>
+ <entry><literal>\d s</literal></entry>
+ </row>
+ <row>
+ <entry>Breve</entry>
+ <entry>&ubreve;</entry>
+ <entry><literal>\u u</literal></entry>
+ </row>
+ <row>
+ <entry>Há&ccaron;ek (caron)</entry>
+ <entry>&ucaron;</entry>
+ <entry><literal>\v u</literal></entry>
+ </row>
+ <row>
+ <entry>Long umlaut</entry>
+ <entry>&olong;</entry>
+ <entry><literal>\H o</literal></entry>
+ </row>
+ <row>
+ <entry>Tie-after</entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ condition="LaTeX">&ootie;</format><format
+ image="ootie" condition="HTML">&ootie;</format></entry>
+ <entry><literal>\t oo</literal></entry>
+ </row>
+ <row>
+ <entry>Cedilla</entry>
+ <entry>&ccedil;</entry>
+ <entry><literal>\c c</literal></entry>
+ </row>
+ <row>
+ <entry>O-E ligature</entry>
+ <entry>&oelig;, &OElig;</entry>
+ <entry><literal>\oe</literal>,
+ <literal>\OE</literal></entry>
+ </row>
+ <row>
+ <entry>A-E ligature</entry>
+ <entry>&aelig;, &AElig;</entry>
+ <entry><literal>\ae</literal>,
+ <literal>\AE</literal></entry>
+ </row>
+ <row>
+ <entry>A-ring</entry>
+ <entry>&aring;, &Aring;</entry>
+ <entry><literal>\aa</literal>,
+ <literal>\AA</literal></entry>
+ </row>
+ <row>
+ <entry>O-slash</entry>
+ <entry>&oslash;, &Oslash;</entry>
+ <entry><literal>\o</literal>,
+ <literal>\O</literal></entry>
+ </row>
+ <row>
+ <entry>Soft-l</entry>
+ <entry><format fontencoding="T1"
+ fontfamily="cmr">&lstrok;, &Lstrok;</format></entry>
+ <entry><literal>\l</literal>,
+ <literal>\L</literal></entry>
+ </row>
+ <row>
+ <entry>Ess-zet (scharfes-S)</entry>
+ <entry>&szlig;</entry>
+ <entry><literal>\ss</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>Irish and Turkish dotless-&inodot; is done with the
+ special command <command>i</command>, so an &iacute;-fada
+ (which is normally typed with <keycap>&iacute;</keycap>)
+ requires <literal>\'\i</literal> if you need to type it in
+ the long format, followed by a backslash-space or dummy pair of
+ curly braces if it comes at the end of a word and there is no
+ punctuation, because of the rule that <LaTeX/> control
+ sequences which end in a letter (see <xref
+ linkend="swallow"/>) always absorb any following space. So
+ what you might see as <citetitle ref="null">Rí
+ Tea&mdot;ra&cdot;</citetitle> has to be <literal>R\'\i\
+ Tea\.mra\.c</literal> when typed in full (there are not
+ usually any keyboard keys for the dotless-&inodot; or the
+ lenited characters). A similar rule applies to dotless-<format
+ fontencoding="OT1"
+ fontfamily="cmr">&jnodot;</format> and to uppercase
+ <literallayout role="Í">\'I</literallayout>.</para>
+ </sect1>
+ <sect1 id="handj">
+ <title>Dimensions, hyphenation, justification, and breaking</title>
+ <indexterm><primary>dimensions</primary></indexterm>
+ <indexterm><primary>hyphenation</primary></indexterm>
+ <indexterm><primary>justification</primary></indexterm>
+ <indexterm><primary sortas="hj">H&ampers;J</primary>
+ <see>hyphenation, justification</see>
+ </indexterm>
+ <para><LaTeX/>&apos;s internal measurement system is
+ extraordinarily accurate. The underlying <TeX/> engine
+ conducts all its business in units smaller than the wavelength
+ of visible light, so if you ask for 15mm space, that&apos;s
+ what you&apos;ll get&mdash;within the limitations of your
+ screen or printer, of course. Most screens cannot show
+ dimensions of less than
+ <inlineequation>
+ <m:mfrac>
+ <m:mover>
+ <m:mn>1</m:mn>
+ </m:mover>
+ <m:munder>
+ <m:mn>96</m:mn>
+ </m:munder>
+ </m:mfrac>
+ </inlineequation>&inch; without resorting to magnification
+ or scaling; and on printers, even at 600dpi, fine oblique
+ lines or curves can still sometimes be seen to stagger the
+ dots.</para>
+ <para>At the same time, many dimensions in <LaTeX/>&apos;s
+ preprogrammed formatting are specially set up to be flexible:
+ so much space, plus or minus certain limits to allow the
+ system to make its own adjustments to accommodate variations
+ like overlong lines, unevenly-sized images, and non-uniform
+ spacing around headings.</para>
+ <para><TeX/> uses a very sophisticated
+ justification algorithm to achieve a smooth, even texture to
+ normal paragraph text. The programming for this has been
+ borrowed by a large number of other DTP systems, and users of
+ these are often quite unaware that they are in fact using a
+ significant part of <TeX/> in their work.
+ Occasionally, however, you will need to hand-correct an
+ unusual word-break or line-break, and there are facilities for
+ doing this on individual occasions as well as throughout a
+ document.</para>
+ <sect2 id="dimensions">
+ <title>Specifying size units</title>
+ <indexterm>
+ <primary>dimension</primary>
+ </indexterm>
+ <indexterm>
+ <primary>units</primary>
+ </indexterm>
+ <para>Most people in printing and publishing habitually use
+ points and picas and ems. Some designers use cm and mm. Many
+ English-language speakers still use inches. You can specify
+ lengths in <LaTeX/> in any of these units, plus some others
+ (see <xref linkend="units"/>).</para>
+ <indexterm><primary>pt (points)</primary></indexterm>
+ <indexterm><primary>points</primary></indexterm>
+ <indexterm><primary>pc (picas)</primary></indexterm>
+ <indexterm><primary>picas</primary></indexterm>
+ <indexterm><primary>bp (big points)</primary></indexterm>
+ <indexterm><primary>sp (scaled points)</primary></indexterm>
+ <indexterm><primary>dd (Didot points)</primary></indexterm>
+ <indexterm><primary>cc (Ciceros)</primary></indexterm>
+ <indexterm><primary>em (relative
+ measure)</primary></indexterm>
+ <indexterm><primary>ex (relative
+ measure)</primary></indexterm>
+ <indexterm><primary>mm (millimeters)</primary></indexterm>
+ <indexterm><primary>cm (centimeters)</primary></indexterm>
+ <indexterm><primary>in (inches)</primary></indexterm>
+ <table id="units">
+ <title>Units in <LaTeX/></title>
+ <tgroup cols="2">
+ <colspec colsep="flush" align="left"/>
+ <colspec colwidth="4in" align="justify"
+ role="\pbs{\raggedright}"/>
+ <thead>
+ <row>
+ <entry>Unit</entry>
+ <entry>Size</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row role="heading">
+ <entry></entry>
+ <entry>Printers&apos; fixed measures</entry>
+ </row>
+ <row>
+ <entry>pt</entry>
+ <entry>Anglo-American standard points (72.27 to the
+ inch)</entry>
+ </row>
+ <row>
+ <entry>pc</entry>
+ <entry>pica ems (12pt)</entry>
+ </row>
+ <row>
+ <entry>bp</entry>
+ <entry>Adobe <wordasword>big</wordasword> points (72
+ to the inch)</entry>
+ </row>
+ <row>
+ <entry>sp</entry>
+ <entry><TeX/>&nbsp;<wordasword>scaled</wordasword> points
+ (65,536 to the pt)</entry>
+ </row>
+ <row>
+ <entry>dd</entry>
+ <entry>Didot (European standard) points (67.54 to the
+ inch)</entry>
+ </row>
+ <row>
+ <entry>cc</entry>
+ <entry>Ciceros (European pica ems, 12dd)</entry>
+ </row>
+ <row role="heading">
+ <entry></entry>
+ <entry>Printers&apos; relative measures</entry>
+ </row>
+ <row>
+ <entry>em</entry>
+ <entry>ems of the current point size (historically the
+ width of a letter <wordasword>M</wordasword> but see
+ below)</entry>
+ </row>
+ <row>
+ <entry>ex</entry>
+ <entry>x-height of the current font (height of letter
+ <wordasword>x</wordasword>)</entry>
+ </row>
+ <row role="heading">
+ <entry></entry>
+ <entry>Other measures</entry>
+ </row>
+ <row>
+ <entry>cm</entry>
+ <entry>centimeters (2.54 to the inch)</entry>
+ </row>
+ <row>
+ <entry>mm</entry>
+ <entry>millimeters (25.4 to the inch)</entry>
+ </row>
+ <row>
+ <entry>in</entry>
+ <entry>inches</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>The em can cause beginners some puzzlement because
+ it&apos;s based on the <wordasword>point size</wordasword>
+ of the type, which is itself misleading. The point size
+ refers to the depth of the metal body on which foundry type
+ was cast in the days of metal typesetting,
+ <emphasis>not</emphasis> the printed height of the letters
+ themselves. Thus the letter-size of 10pt type in one face
+ can be radically different from 10pt type in another (look
+ at <xref linkend="fontable-adobe"/>, where all the examples are
+ 10pt). An em is the height of the type-body in a specific size,
+ so 1em of 10pt type is 10pt and 1em of 24pt type is
+ 24pt.</para>
+<!-- HW InPrint P.O. Box 385, Devonport, Tasmania 7310 Australia -->
+ <para>Another name for a 1em space is a
+ <wordasword>quad</wordasword>, and <LaTeX/> has a command
+ <command>quad</command> for leaving exactly that much
+ horizontal space. <!--To make the point, <xref
+ linkend="emsize"/> shows two capital Ms of 72pt and 36pt
+ type in different faces, surrounded by a box exactly 1em of
+ those sizes wide.--> A special name is given to the 12pt em, a
+ <wordasword>pica</wordasword> em, as it has become a fixed
+ measure in its own right.</para>
+<!--
+ <table id="emsize">
+ <title>Different sizes of type boxed at 1em</title>
+ <tgroup cols="2">
+ <colspec align="right"/>
+ <colspec align="left"/>
+ <thead>
+ <row>
+ <entry>Times New Roman 72pt</entry>
+ <entry>Adobe Helvetica 36pt</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literallayout role="">\vrule height80pt
+ width0pt</literallayout><format fontencoding="OT1"
+ fontfamily="ptm" fontsize="72" frame="yes"
+ struts="both">M</format></entry>
+ <entry><format fontencoding="T1" fontfamily="phv"
+ fontsize="36" frame="yes"
+ struts="both">M</format></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+-->
+ <para>If you are working with other DTP users, watch out for
+ those who think that Adobe points (bp) are the only ones.
+ The difference is only .27pt per inch, but in 10&inch; of
+ text (a full page of A4) that&apos;s 2.7pt, which is nearly
+ 1mm, enough to be clearly visible if you&apos;re trying to
+ align one sample with another.</para>
+ </sect2>
+ <sect2 id="hyph">
+ <title>Hyphenation</title>
+ <para><LaTeX/> hyphenates automatically according to the
+ language you use (see <xref linkend="langs"/>). To specify
+ different breakpoints for an individual word, you can insert
+ soft-hyphens<indexterm>
+ <primary>hyphens</primary><secondary>soft</secondary>
+ </indexterm> (discretionary hyphens, done with
+ <command>-</command>) wherever you need them, for
+ example:</para>
+ <!-- Náhuatl for smoking mountain -->
+ <programlisting>
+When in Mexico, we visited Popoca\-tépetl by helicopter.
+ </programlisting>
+ <para>To specify hyphenation points for all occurrences of a
+ word, use the <command>hyphenation</command> command in your
+ preamble (see <xref linkend="preamble"/>) with one or more
+ words in its argument, separated by spaces. This will even
+ let you break <wordasword>helico-<?html <br>?><?LaTeX
+ \linebreak ?>pter</wordasword> correctly. In this command
+ you use normal hyphens, not soft-hyphens.<indexterm>
+ <primary>hyphens</primary>
+ <secondary>discretionary</secondary>
+ </indexterm></para>
+ <programlisting>
+\hyphenation{helico-pter Popoca-tépetl
+im-mer-sion}
+ </programlisting>
+ <para>If you have frequent hyphenation problems with long,
+ unusual, or technical words, ask an expert about changing
+ the value of <varname role="dimension">spaceskip</varname>,
+ which controls the flexibility of the space between words.
+ This is not something you would normally want to do, as it
+ can change the appearance of your document quite
+ significantly.</para>
+ <para>If you are using a lot of unbreakable text (see next
+ section and also <xref linkend="inlineverb"/>) it may also
+ cause justification problems. One possible solution to this
+ is shown in <xref linkend="macargs"/>.</para>
+ </sect2>
+ <sect2>
+ <title>Unbreakable text</title>
+ <para>To force <LaTeX/> to treat a word as unbreakable, use
+ the <command>mbox</command> command:
+ <literal>\mbox{pneumonoultramicroscopicsilicovolcanoconiosis}</literal>.
+ <?html <br>?>This may have undesirable results, however, if
+ you change margins or the width of the text:
+ <exceptionname>pneumonoultramicroscopicsilicovolcanoconiosis</exceptionname>&hellip;</para>
+ <para>To tie two words together with an unbreakable
+ space<indexterm>
+ <primary>hard space</primary>
+ </indexterm><indexterm>
+ <primary>white-space</primary>
+ <secondary>hard</secondary>
+ </indexterm> (hard space), use a tilde (<literal>~</literal>)
+ instead of the space (see <xref linkend="tilde"/>). This
+ will print as a normal space but
+ <LaTeX/> will never break the line at that point. You should
+ make this standard typing practice for things like
+ people&apos;s initials followed by their surname, as in
+ Prof. D.&nbsp;E.&nbsp;Knuth:
+ <literal>Prof.\ D.~E.~Knuth</literal>.</para>
+ <warning>
+ <para>Note that a full point after a lowercase letter is
+ treated as the end of a sentence, and creates more space
+ before the next word. Here, after
+ <wordasword>Prof.</wordasword>, it&apos;s
+ <emphasis>not</emphasis> the end of a sentence, and the
+ backslash-space forces <LaTeX/> to insert just an ordinary
+ word-space because it&apos;s OK to break the line after
+ <wordasword>Prof.</wordasword>, whereas it would look
+ wrong to have initials separated with Prof.&nbsp;D.<?html
+ <br>?>E.&nbsp;Knuth broken over a line-end.</para>
+ </warning>
+ </sect2>
+ <sect2>
+ <title>Dashes</title>
+ <para>For a long dash&mdash;what printers call an
+ <wordasword>em rule</wordasword> like this&mdash;use three
+ hyphens typed together, <literal>like~--- this</literal>,
+ and bind them to the preceding word with a tilde to avoid
+ the line being broken before the dash. It&apos;s also common
+ to see the dash printed without spaces&mrule;like that: the
+ difference is purely æsthetic. <emphasis>Never</emphasis>
+ use a single hyphen for this purpose.</para>
+ <para>Between digits like page ranges (35&ndash;47), it is
+ normal to use the short dash (what printers call an en-rule)
+ which you get by typing two hyphens together, as in
+ <literal>35--47</literal>. If you want a minus sign, use math
+ mode (<xref linkend="math"/>).</para>
+ </sect2>
+ <sect2>
+ <title>Justification</title>
+ <para>The default mode for typesetting is justified (two
+ parallel margins, with word-spacing adjusted automatically
+ for the best optical fit). In justifying, <LaTeX/> will never
+ add space between letters, only between words. There is a
+ special package called <methodname>so</methodname>
+ (<wordasword>space-out</wordasword>) if you need special
+ effects like letter-spacing, but these are best left to the
+ expert.</para>
+ <para remap="\raggedright">There are two commands
+ <command>raggedright</command> and
+ <command>raggedleft</command> which set ragged-right (ranged
+ left) and ragged-left (ranged right). Use them inside a
+ group (see <xref linkend="grouping"/>) to confine their
+ action to a part of your text.</para>
+ <para remap="\raggedleft">These modes also exist as
+ <wordasword>environments</wordasword> (see <xref
+ linkend="environments"/>) called
+ <modespec>raggedright</modespec> and
+ <modespec>raggedleft</modespec> which are more convenient
+ when applying this formatting to a whole paragraph or more,
+ like this one.</para>
+ <programlisting>
+\begin{raggedleft}
+These modes also exist as environments called raggedright
+and raggedleft which is more convenient when applying this
+formatting to a whole paragraph or more, like this one.
+\end{raggedleft}
+ </programlisting>
+ <para>Ragged setting turns off hyphenation. There is a package
+ <methodname>ragged2e</methodname> which retains hyphenation
+ in ragged setting, useful when you have a lot of long
+ words.</para>
+ </sect2>
+ <sect2 id="langs">
+ <title>Languages</title>
+ <para><LaTeX/> can typeset in the native manner for several
+ dozen languages. This affects hyphenation, word-spacing,
+ indentation, and the names of the parts of documents used as
+ headings (&eg;&nbsp;Table of Contents).</para>
+ <para>Most distributions of <LaTeX/> come with US English and
+ one or more other languages installed by default, but it is
+ easy to add the <methodname>babel</methodname> package and
+ specify any of the supported languages or variants, for
+ example:</para>
+ <programlisting>
+\usepackage[frenchb]{babel}
+...
+\selectlanguage{frenchb}
+ </programlisting>
+ <para>Changing the language with
+ <methodname>babel</methodname> automatically changes the
+ names of the structural units and identifiers like
+ <wordasword>Abstract</wordasword>,
+ <wordasword>Index</wordasword>, &etc;&nbsp;to their
+ translated version. For example, using French as above,
+ chapters will start with
+ <wordasword><foreignphrase>Chapitre</foreignphrase></wordasword>.<footnote>
+ <para>Note that the <methodname>babel</methodname> package
+ also sets the hyphenation patterns <emphasis>provided
+ your version of <LaTeX/> has them
+ precompiled</emphasis> (see the start of your log
+ files for a list). For other languages you need to set
+ the hyphenation separately (outside the scope of this
+ book).</para>
+ </footnote>
+</para>
+ </sect2>
+ </sect1>
+ <sect1 id="math">
+ <title>Mathematics</title>
+ <indexterm><primary>mathematics</primary></indexterm>
+ <para>As explained in <xref linkend="mathtex"/>, <TeX/> was
+ originally written to automate the typesetting of books
+ containing mathematics. The careful reader will already have
+ noticed that mathematics is handled differently from normal
+ text, which is why it has to be typeset specially. This
+ document does not cover mathematical typesetting, which is
+ explained in detail in many other books and Web pages, so all
+ we will cover here is the existence of the math mode commands,
+ and some characters which have special meaning, so they
+ don&apos;t trip you up elsewhere.</para>
+ <para>In addition to the 10 special characters listed in <xref
+ linkend="specials"/>, there are three more characters which
+ only have any meaning inside mathematics mode:<indexterm>
+ <primary>math characters</primary>
+ </indexterm></para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec align="center"/>
+ <colspec align="left"/>
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Meaning</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><keycap>&vbar;</keycap></entry>
+ <entry>Vertical bar</entry>
+ </row>
+ <row>
+ <entry><keycap remap="tt"><![CDATA[<]]></keycap></entry>
+ <entry>Less-than</entry>
+ </row>
+ <row>
+ <entry><keycap remap="tt">></keycap></entry>
+ <entry>Greater-than</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>If you type any of these in normal text (ie outside math
+ mode), you will get very weird things happening and lots of
+ error messages. If you need to print these characters, you
+ <emphasis>must</emphasis> type them using math mode, or use
+ their symbolic names from the <modespec>textcomp</modespec>
+ package (<command>textbrokenbar</command>,
+ <command>textlangle</command>, and
+ <command>textrangle</command>).</para>
+ <para>The hyphen also has an extra meaning in math mode: it
+ typesets as a minus sign, so if you want to write about
+ negative numbers you need to type the number in math mode so
+ the minus sign and the spacing come out right.</para>
+ <para>To use math mode within a paragraph, enclose your math
+ expression in <command>(</command> and <command>)</command>
+ commands. You can get the much-quoted equation
+ <inlineequation>
+ <m:mtext>E=mc</m:mtext>
+ <m:msup>
+ <m:mtext>2</m:mtext>
+ </m:msup>
+ </inlineequation> by typing
+ <literal>\(E=mc^2\)</literal>, and to get a temperature like
+ <informalequation>
+ <m:mo>&minus;</m:mo>
+ <m:mn>30</m:mn>
+ </informalequation>&deg; you need to type
+ <literal>\(-30\)°</literal>.<footnote>
+ <para>Bear in mind that the degree symbol is a non-<acronym
+ ref="ASCII"></acronym> character, so you must specify
+ what input encoding you are using if you want to type it:
+ see the example of the <methodname>inputenc</methodname>
+ package in <xref linkend="accents"/>. If you don&apos;t
+ want to use non-<acronym ref="ASCII"></acronym> characters
+ (or if you are using a system which cannot generate them),
+ you can use the command <command>textdegree</command> to
+ get the degree sign.</para>
+ </footnote></para>
+ <para>To typeset a math expression as <wordasword>displayed
+ math</wordasword> (centered between paragraphs), enclose it
+ in the commands <command>[</command> and
+ <command>]</command>.<footnote>
+ <para>You will also see dollar signs used for math mode.
+ This is quite common but deprecated: it&apos;s what plain
+ <TeX/> used in the days before <LaTeX/>, and the habit got
+ ingrained in many mathematicians. It still works as a
+ convenient shorthand like <literal>$x=y$</literal>, as do
+ double-dollars for display-mode math like
+ <literal>$$E=mc^2$$</literal>, but they are only mentioned
+ here to warn readers seeing them in other authors&apos;
+ work that <command>(</command>&hellip;<command>)</command>
+ and <command>[</command>&hellip;<command>]</command> are
+ the proper <LaTeX/> commands.</para>
+ </footnote></para>
+ <informalexample>
+ <programlisting>
+\[\bar n^*_j(s)=\frac{\left\{s\sum_{i=1}^k
+n_i(0)p^*{i,k+1}(s)+M^*(s)\right\}\sum_{i=1}^k
+p_{0i}p^*{ij}(s)}{1-s\sum_{i=1}^kp_{0i}p^*_{i,
+k+1}(s)}+\sum_{i=1}^kn_i(0)p^*_{ij}(s)[j=
+1,2,\dots,k].\]
+ </programlisting>
+ <para remap="math"><!--<equation> <m:msubsup>
+ <m:mi>&nbar;</m:mi> <m:mi>j</m:mi> <m:mi>*</m:mi>
+ </m:msubsup> <m:mo>(</m:mo> <m:mi>s</m:mi> <m:mo>)</m:mo>
+ <m:mo>=</m:mo> </equation>--><![CDATA[ \(\bar n^*_j(s)=
+ \frac{\left\{s\sum^k_{i=1}n_i(0)p^*_{i,k+1}(s)+M^*(s)\right\}
+ \sum^k_{i=1}p_{0i}p^*{ij}(s)}{1-s\sum^k_{i=1}p_{0i}p^*_{i,k+1}(s)}
+ +\sum^k_{i=1}n_i(0)p^*_{ij}(s)\,\rlap{[j=1,2,\dots,k]}\)
+ ]]></para>
+ </informalexample>
+ <para>Displayed equations can be auto-numbered with the
+ <modespec>equation</modespec> environment instead of the
+ <command>[</command> and <command>]</command> commands.</para>
+ </sect1>
+ </chapter>
+ <chapter id="basic">
+ <title>Basic document structures</title>
+ <indexterm>
+ <primary>sections</primary>
+ </indexterm>
+ <para><LaTeX/>&apos;s approach to formatting is to aim for
+ consistency. This means that as long as you identify each
+ <firstterm id="element">element</firstterm> of your document
+ correctly, it will be typeset in the same way as all the other
+ elements like it, so that you achieve a consistent finish with
+ minimum effort. Consistency helps make documents easier to read
+ and understand.</para>
+ <para>Elements are the component parts of a document, all the
+ pieces which make up the whole. Almost everyone who reads books,
+ newspapers, magazines, reports, articles, and other classes of
+ documents will be familiar with the popular structure of
+ chapters, sections, subsections, subsubsections, paragraphs,
+ lists, tables, figures, and so on, even if they don&apos;t
+ consciously think about it.</para>
+ <para>Consistency is also what publishers look for. They have a
+ house style, and often a reputation to keep, so they rightly
+ insist that if you do something a certain way once, you should
+ do it the same way each time.</para>
+ <para>To help achieve this consistency, every <LaTeX/> document
+ starts by declaring what <firstterm id="documentclass">document
+ class</firstterm> it belongs to.</para>
+ <sect1 id="docdecl">
+ <title>The Document Class Declaration</title>
+ <indexterm>
+ <primary>document class</primary>
+ </indexterm>
+ <para>To tell <LaTeX/> what class of document you are going to
+ create, you type a special first line into your file which
+ identifies it.<footnote>
+ <para>Readers familiar with <acronym ref="SGML"></acronym>,
+ <acronym ref="HTML"></acronym>, or <acronym
+ ref="XML"></acronym> will recognize the concept as
+ similar to the Document Type
+ Declaration.</para></footnote> To start a report, for
+ example, you would type the <command>documentclass</command>
+ command like this as your first line:</para>
+ <programlisting>
+\documentclass{report}
+ </programlisting>
+ <para>There are four built-in classes provided, and many others
+ that you can download (some may already be installed for
+ you):</para>
+ <variablelist>
+ <varlistentry>
+ <term><methodname>report</methodname></term>
+ <listitem>
+ <para>for business, technical, legal, academic, or
+ scientific reports;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><methodname>article</methodname></term>
+ <listitem>
+ <para>for white papers, magazine or journal articles,
+ reviews, conference papers, or research notes;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><methodname>book</methodname></term>
+ <listitem>
+ <para>for books and theses;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><methodname>letter</methodname></term>
+ <listitem>
+ <para>for letters.<footnote>
+ <para>The built-in <methodname>letter</methodname>
+ class is rather idiosyncratic: there are much better
+ ones you can download, such as
+ the <methodname>memoir</methodname> and
+ <methodname>komascript</methodname> packages.</para>
+ </footnote></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>The <methodname>article</methodname> class in particular
+ can be used (some would say <quote>abused</quote>) for almost
+ any short piece of typesetting by simply omitting the titling
+ and layout (see below).</para>
+ <para>The built-in classes are intended as starting-points,
+ especially for drafts and for compatibility when exchanging
+ documents with other <LaTeX/> users, as they come with every
+ copy of <LaTeX/> and are therefore guaranteed to format
+ identically everywhere. <emphasis>They are <emphasis
+ role='high'>not</emphasis> intended as final-format
+ publication-quality layouts.</emphasis> For most other
+ purposes, especially for publication, you use
+ add-in <link linkend="packages">packages</link> to extend
+ these classes to do what you need:</para>
+ <itemizedlist>
+ <listitem>
+ <para>The <methodname>memoir</methodname> and
+ <methodname>komascript</methodname> packages contain
+ more sophisticated replacements for all the built-in
+ classes;</para>
+ </listitem>
+ <listitem>
+ <para>Many academic and scientific publishers provide their
+ own special class files for articles and books (often on
+ their Web sites for download);</para>
+ </listitem>
+ <listitem>
+ <para>Conference organisers may also provide class files for
+ authors to write papers for presentation;</para>
+ </listitem>
+ <listitem>
+ <para>Many universities provide their own thesis document
+ class files in order to ensure exact fulfillment of their
+ formatting requirements;</para>
+ </listitem>
+ <listitem>
+ <para>Businesses and other organizations can provide their
+ users with corporate classes on a central server and
+ configure <LaTeX/> installations to look there first for
+ packages, fonts, etc.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Books and journals are not usually printed on office-size
+ paper. Although <LaTeX/>&apos;s layouts are designed to fit on
+ standard A4 or Letter stationery for draft purposes, it makes
+ them look odd: the margins are too wide, or the positioning is
+ unusual, or the font size is too small, because the finished
+ job will normally be trimmed to a different size
+ entirely&mdash;try trimming the margins of the <acronym
+ ref="PDF"></acronym> version of this book to 185mm by 235mm
+ (the same as <citetitle ref="companion"></citetitle> series)
+ and you&apos;ll be amazed at how it changes the appearance!
+ <!-- These classes are adequate for drafts or for sending to
+ another <LaTeX/> user (because you know their system will
+ understand them) but they are not designed for final-format
+ professional publishing. For this you need a style file
+ designed by the publisher to fit their series of publications
+ (quite often based on the default classes, but looking very
+ different). The packages noted above provide good facilities
+ for helping design these.--></para>
+ <sect2 id="doclayout">
+ <title>Document class options</title>
+ <indexterm>
+ <primary>paper sizes</primary>
+ </indexterm>
+ <para>The default layouts are designed to fit as drafts on US
+ Letter size paper.<footnote>
+ <para>Letter size is 8½&inch;&times;11&inch;, which is the
+ trimmed size of the old Demi Quarto, still in use in
+ North America. The other common US office size is
+ <wordasword>Legal</wordasword>, which is
+ 8½&inch;&times;14&inch;, a bastard cutting close to
+ the old Foolscap (8¼&inch;&times;13¼&inch;). ISO
+ standard <wordasword>A</wordasword>,
+ <wordasword>B</wordasword>, and
+ <wordasword>C</wordasword> paper sizes are still
+ virtually unknown in many parts of North America.</para>
+ </footnote> To create documents with the correct proportions
+ for standard A4 paper, you need to specify the paper size in
+ an optional argument in square brackets before the document
+ class name, &eg;</para>
+ <programlisting>
+\documentclass[a4paper]{report}
+ </programlisting>
+ <para>The two most common options are <option>a4paper</option>
+ and <option>letterpaper</option>. However, many European
+ distributions of <TeX/> now come preset for A4, not Letter, and
+ this is also true of all distributions of
+ <productname>pdf<LaTeX/></productname>.</para>
+ <para>The other default settings are for: <orderedlist>
+ <listitem>
+ <para>10pt type (all document classes)</para>
+ </listitem>
+ <listitem>
+ <para>two-sided printing (books and reports) or
+ one-sided (articles and letters)</para>
+ </listitem>
+ <listitem>
+ <para>separate title page (books and reports
+ only)</para>
+ </listitem>
+ </orderedlist>. These can be modified with the following
+ document class options which you can add in the same set of
+ square brackets, separated by commas:</para>
+ <indexterm>
+ <primary>fonts</primary>
+ <secondary>sizes</secondary>
+ </indexterm>
+ <variablelist id="docfontsize">
+ <varlistentry>
+ <term><option>11pt</option></term>
+ <listitem>
+ <para>to specify 11pt type (headings, footnotes,
+ &etc;&nbsp;get scaled up or down in
+ proportion);</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>12pt</option></term>
+ <listitem>
+ <para>to specify 12pt type (again, headings
+ scale);</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>oneside</option></term>
+ <listitem>
+ <para>to format one-sided printing for books and
+ reports;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>twoside</option></term>
+ <listitem>
+ <para>to format articles for two-sided printing;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>titlepage</option></term>
+ <listitem>
+ <para>to force articles to have a separate title
+ page;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>draft</option></term>
+ <listitem>
+ <para>makes <LaTeX/> indicate hyphenation and
+ justification problems with a small square in the
+ right-hand margin of the problem line so they can be
+ located quickly by a human.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>If you were using pdf<LaTeX/> for a report to be in 12pt
+ type on Letter paper, but printed one-sided in draft mode, you
+ would use:</para>
+ <programlisting>
+\documentclass[12pt,letterpaper,oneside,draft]{report}
+ </programlisting>
+ <para>There are extra preset options for other type sizes
+ which can be downloaded separately, but 10pt, 11pt, and 12pt
+ between them cover probably 99&percnt; of all document
+ typesetting. In addition there are the hundreds of add-in
+ packages which can automate other layout and formatting
+ variants without you having to program anything by hand or
+ even change your text.</para>
+ <example id="firstline">
+ <title>Create a new document</title>
+ <orderedlist>
+ <listitem>
+ <para>Use your editor to create a new document.</para>
+ </listitem>
+ <listitem>
+ <para>Type in a Document Class Declaration as shown
+ above.</para>
+ </listitem>
+ <listitem>
+ <para>Add a font size option if you wish.</para>
+ </listitem>
+ <listitem>
+ <para>In North America, omit the
+ <option>a4paper</option> option or change it to
+ <option>letterpaper</option>.</para>
+ </listitem>
+ <listitem>
+ <para>Save the file (make up a name) ensuring the name
+ ends with <filename>.tex</filename></para>
+ </listitem>
+ </orderedlist>
+ </example>
+ </sect2>
+ </sect1>
+ <sect1 id="docenv">
+ <title>The document environment</title>
+ <para>After the Document Class Declaration, the text of your
+ document is enclosed between two commands which identify the
+ beginning and end of the actual document:</para>
+ <programlisting>
+\documentclass[11pt,a4paper,oneside]{report}
+
+\begin{document}
+...
+\end{document}
+ </programlisting>
+ <para>(You would put your text where the dots are.) The reason
+ for marking off the beginning of your text is that <LaTeX/>
+ allows you to insert extra setup specifications before it
+ (where the blank line is in the example above: we&apos;ll be
+ using this soon). The reason for marking off the end of your
+ text is to provide a place for <LaTeX/> to be programmed to do
+ extra stuff automatically at the end of the document, like
+ making an index.</para>
+ <para>A useful side-effect of marking the end of the document
+ text is that you can store comments or temporary text
+ underneath the <literal>\end{document}</literal> in the
+ knowledge that <LaTeX/> will never try to typeset them.</para>
+ <programlisting>
+...
+\end{document}
+Don't forget to get the extra chapter from Jim!
+ </programlisting>
+ <para id="environments">This
+ <command>begin</command>&thinsp;&hellip;<command>end</command>
+ pair of commands is an example of a common <LaTeX/> structure called an
+ <firstterm id="environment">environment</firstterm>.
+ Environments enclose text which is to be handled in a particular
+ way. All environments start with
+ <literal>\begin{...}</literal> and end with
+ <literal>\end{...}</literal> (putting the name of the
+ environment in the curly braces).</para>
+ <example>
+ <title>Adding the document environment</title>
+ <orderedlist>
+ <listitem>
+ <para>Add the <modespec>document</modespec> environment to
+ your file.</para>
+ </listitem>
+ <listitem>
+ <para>Leave a blank line between the Document Class
+ Declaration and the <literal>\begin{document}</literal>
+ (you&apos;ll see why later).</para>
+ </listitem>
+ <listitem>
+ <para>Save the file.</para>
+ </listitem>
+ </orderedlist>
+ </example>
+ </sect1>
+ <sect1 id="titling">
+ <title>Titling</title>
+ <indexterm>
+ <primary>titles</primary>
+ </indexterm>
+ <para>The first thing you put in the
+ <modespec>document</modespec> environment is almost always the
+ document title, the author&apos;s name, and the date (except
+ in letters, which have a special set of commands for
+ addressing which we&apos;ll look at later). The title, author,
+ and date are all examples of <firstterm
+ id="metadata"></firstterm> or <firstterm
+ id="metainformation"></firstterm> (information
+ <emphasis>about</emphasis> information).</para>
+ <programlisting>
+\documentclass[11pt,a4paper,oneside]{report}
+
+\begin{document}
+
+\title{Practical Typesetting}
+\author{Peter Flynn\\Silmaril Consultants}
+\date{December 2004}
+\maketitle
+
+\end{document}
+ </programlisting>
+ <para>The <command>title</command>, <command>author</command>,
+ and <command>date</command> commands are
+ self-explanatory. You put the title, author name, and date in
+ curly braces after the relevant command. The title and author
+ are usually compulsory; if you omit the
+ <command>date</command> command, <LaTeX/> uses today&apos;s
+ date by default.</para>
+ <para>You always finish the metadata with the
+ <command>maketitle</command> command, which tells
+ <LaTeX/> that it&apos;s complete and it can typeset the titling
+ information at this point. If you omit
+ <command>maketitle</command>, the titling will never be
+ typeset. This command is reprogrammable so you can alter the
+ appearance of titles (like I did for the printed version of
+ this document).</para>
+ <para>The double backslash (<literal>\\</literal>) is the
+ <LaTeX/> command for forced linebreak. <LaTeX/> normally decides by
+ itself where to break lines, and it&apos;s usually right, but
+ sometimes you need to cut a line short, like here, and start a
+ new one. I could have left it out and just used a comma, so my
+ name and my company would all appear on the one line, but I
+ just decided that I wanted my company name on a separate line.
+ In some publishers&apos; document classes, they provide a special
+ <command>affiliation</command> command to put your company
+ or institution name in instead.</para>
+ <para>When this file is typeset, you get something like this
+ (I&apos;ve cheated and <link linkend="colorpkg">done it in
+ colour</link> for fun&mdash;yours will be in black and white
+ for the moment):</para>
+ <graphic fileref="title" width="80%" remap="frame"/>
+ <example>
+ <title>Adding the metadata</title>
+ <orderedlist>
+ <listitem>
+ <para>Add the <command>title</command>,
+ <command>author</command>, <command>date</command>, and
+ <command>maketitle</command> commands to your
+ file.</para>
+ </listitem>
+ <listitem>
+ <para>Use your own name, make up a title, and give a
+ date.</para>
+ </listitem>
+ </orderedlist>
+ <para>The order of the first three commands is not important,
+ but the <command>maketitle</command> command must come
+ last.</para>
+ </example>
+ <para>The document isn&apos;t really ready for printing like this,
+ but if you&apos;re really impatient, look at <xref
+ linkend="process"/> to see how to typeset and display
+ it.</para>
+ </sect1>
+ <sect1 id="abstracts">
+ <title>Abstracts and summaries</title>
+ <indexterm>
+ <primary>abstracts</primary>
+ </indexterm>
+ <indexterm>
+ <primary>summaries</primary>
+ </indexterm>
+ <para>In reports and articles it is normal for the author
+ to provide an Summary or Abstract, in which you describe
+ briefly what you have written about and explain its
+ importance. Abstracts in articles are usually only a few
+ paragraphs long. Summaries in reports can run to several
+ pages, depending on the length and complexity of the report
+ and the readership it&apos;s aimed at.</para>
+ <para>In both cases (reports and articles) the Abstract or
+ Summary is optional (that is, <LaTeX /> doesn&apos;t force you
+ to have one), but it&apos;s rare to omit it because readers want
+ and expect it. In practice, of course, you go back and type
+ the Abstract or Summary <emphasis>after</emphasis> having
+ written the rest of the document, but for the sake of the
+ example we&apos;ll jump the gun and type it now.</para>
+ <programlisting>
+\documentclass[11pt,a4paper,oneside]{report}
+\usepackage[latin1]{inputenc}
+\renewcommand{\abstractname}{Summary}
+\begin{document}
+
+\title{Practical Typesetting}
+\author{Peter Flynn\\Silmaril Consultants}
+\date{December 2004}
+\maketitle
+
+\begin{abstract}
+This document presents the basic concepts of
+typesetting in a form usable by non-specialists. It
+is aimed at those who find themselves (willingly or
+unwillingly) asked to undertake work previously sent
+out to a professional printer, and who are concerned
+that the quality of work (and thus their corporate
+æsthetic) does not suffer unduly.
+\end{abstract}
+
+\end{document}
+ </programlisting>
+<!--
+The topics cover layout, the need for accuracy, the choice
+of typeface, arrangement of the document, adherence to
+specifications, and the production process. No
+foreknowledge of printing or publishing is needed, but an
+eye for detail, a feeling for æsthetics, and some fluency
+with a computer is expected.
+-->
+ <para>After the <command>maketitle</command> you use the
+ <modespec>abstract</modespec> environment, in which you simply
+ type your Abstract or Summary, leaving a blank line between
+ paragraphs if there&apos;s more than one (see <xref
+ linkend="paragraphs"/> for this convention).</para>
+ <para>In business and technical documents, the Abstract is often
+ called a Management Summary, or Executive Summary, or Business
+ Preview, or some similar phrase. <LaTeX/> lets you change the
+ name associated with the <modespec>abstract</modespec>
+ environment to any kind of title you want, using the
+ <command>renewcommand</command> command to give the command
+ <command>abstractname</command> a new value:</para>
+ <programlisting>
+\renewcommand{\abstractname}{Executive Summary}
+ </programlisting>
+ <example>
+ <title>Using an Abstract or Summary</title>
+ <orderedlist>
+ <listitem>
+ <para>Add the <command>renewcommand</command> as shown
+ above to your Preamble.</para>
+ <para>The Preamble is at the start of the document, in
+ that gap <emphasis>after</emphasis> the
+ <command>documentclass</command> line but
+ <emphasis>before</emphasis> the
+ <literal>\begin{document}</literal> (remember I said
+ we&apos;d see what we left it blank for: see <xref
+ linkend="preamble"/>).</para>
+ </listitem>
+ <listitem>
+ <para>Add an <modespec>abstract</modespec> environment
+ after the <command>maketitle</command> and type in a
+ paragraph or two of text.</para>
+ </listitem>
+ <listitem>
+ <para>Save the file (no, I&apos;m not paranoid, just
+ careful).</para>
+ </listitem>
+ </orderedlist>
+ </example>
+ <para>Notice how the name of the command you are renewing (here,
+ <command>abstractname</command>) goes in the first set of
+ curly braces, and the new value you want it to have goes in
+ the second set of curly braces (this is an example of a
+ command with two arguments). The environment you use is still
+ called <modespec>abstract</modespec> (that is, you still type
+ <literal>\begin{abstract}</literal>&hellip;<literal>\end{abstract}</literal>).
+ What the <command>abstractname</command> does is change the
+ name that gets displayed and printed, not the name of the
+ environment you store the text in.</para>
+ <para>If you look carefully at the example document, you&apos;ll
+ see I sneakily added an extra command to the Preamble.
+ We&apos;ll see later what this means (Brownie points for
+ guessing it, though, if you read <xref
+ linkend="accents"/>).</para>
+ <sidebar id="preamble">
+ <title>The Preamble</title>
+ <para>Modifications which you want to affect a whole document
+ go at the start of your <LaTeX/> file, immediately
+ after the <command>documentclass</command> line and before
+ the <literal>\begin{document}</literal> line:</para>
+ <programlisting>
+\documentclass[11pt,a4paper,oneside]{report}
+\renewcommand{\abstractname}{Sneak Preview}
+\begin{document}
+...
+\end{document}
+ </programlisting>
+ <para>This position, between the Document Class Declaration
+ and the beginning of the <modespec>document</modespec>
+ environment, is called the <firstterm
+ id="pre">preamble</firstterm>, and it is used for small or
+ temporary modifications to the style and behaviour of the
+ document. Major or permanent modifications should go in a
+ <filename>.sty</filename> file and be invoked with a
+ <command>usepackage</command> command.</para>
+ </sidebar>
+ </sect1>
+ <sect1 id="sections">
+ <title>Sections</title>
+ <indexterm>
+ <primary>sections</primary>
+ </indexterm>
+ <para>In the body of your document, <LaTeX/> provides seven
+ levels of division or sectioning for you to use in structuring
+ your text. They are all optional: it is perfectly possible to
+ write a document consisting solely of paragraphs of
+ unstructured text. But even novels are normally divided into
+ chapters, although short stories are often made up solely of
+ paragraphs.</para>
+ <para>Chapters are only
+ available in the <methodname>book</methodname> and
+ <methodname>report</methodname> document classes, because they
+ don&apos;t have any meaning in articles and letters. Parts are
+ also undefined in letters.<footnote
+ id="repchap">
+ <para>It is arguable that chapters also have no place in
+ reports, either, as these are conventionally divided into
+ sections as the top-level division. <LaTeX/>, however,
+ assumes your reports have chapters, but this is only the
+ default, and can be changed very simply (see
+ <xref linkend="reprog"/>).</para>
+ </footnote></para>
+ <informaltable id="secdepths">
+ <tgroup cols="4">
+ <colspec align="center" colsep="flush"/>
+ <colspec align="left"/>
+ <colspec align="left"/>
+ <colspec align="left" colsep="flush"/>
+ <thead>
+ <row>
+ <entry>Depth</entry>
+ <entry>Division</entry>
+ <entry>Command</entry>
+ <entry>Notes</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><inlineequation>
+ <m:mo>&minus;</m:mo>
+ <m:mn>1</m:mn>
+ </inlineequation></entry>
+ <entry>Part</entry>
+ <entry><command>part</command></entry>
+ <entry>Not in letters</entry>
+ </row>
+ <row>
+ <entry>0</entry>
+ <entry>Chapter</entry>
+ <entry><command>chapter</command></entry>
+ <entry>Books and reports</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>Section</entry>
+ <entry><command>section</command></entry>
+ <entry>Not in letters</entry>
+ </row>
+ <row>
+ <entry>2</entry>
+ <entry>Subsection</entry>
+ <entry><command>subsection</command></entry>
+ <entry>Not in letters</entry>
+ </row>
+ <row>
+ <entry>3</entry>
+ <entry>Subsubsection</entry>
+ <entry><command>subsubsection</command></entry>
+ <entry>Not in letters</entry>
+ </row>
+ <row>
+ <entry>4</entry>
+ <entry>Titled paragraph</entry>
+ <entry><command>paragraph</command></entry>
+ <entry>Not in letters</entry>
+ </row>
+ <row>
+ <entry>5</entry>
+ <entry>Titled subparagraph</entry>
+ <entry><command>subparagraph</command></entry>
+ <entry>Not in letters</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>In each case the title of the part, chapter, section,
+ &etc; goes in curly braces after the command. <LaTeX/>
+ automatically calculates the correct numbering and prints the
+ title in bold. You can turn section numbering off at a
+ specific depth: details in <xref linkend="secnum"/>.</para>
+ <programlisting>
+\section{New recruitment policies}
+...
+\subsection{Effect on staff turnover}
+...
+\chapter{Business plan 2005--2007}
+ </programlisting>
+ <para>There are packages<footnote>
+ <para>Details of how to use <LaTeX/> packages are in <xref
+ linkend="packages"/>.</para>
+ </footnote> to let you control the typeface, style, spacing,
+ and appearance of section headings: it&apos;s much easier to
+ use them than to try and reprogram the headings manually. Two
+ of the most popular are the <methodname>ssection</methodname>
+ and <methodname>sectsty</methodname> packages.</para>
+ <para>Headings also get put automatically into the Table of
+ Contents, if you specify one (it&apos;s optional). But if you
+ make manual styling changes to your heading, for example a
+ very long title, or some special line-breaks or unusual
+ font-play, this would appear in the Table of Contents as well,
+ which you almost certainly <emphasis>don&apos;t</emphasis>
+ want. <LaTeX/> allows you to give an optional extra version of
+ the heading text which only gets used in the Table of Contents
+ and any running heads, if they are in effect <link
+ linkend="runningheads"></link>. This optional alternative
+ heading goes in [square brackets] before the curly
+ braces:</para>
+ <programlisting>
+\section[Effect on staff turnover]{An analysis of the
+effect of the revised recruitment policies on staff
+turnover at divisional headquarters}
+ </programlisting>
+ <example>
+ <title>Start your document text</title>
+ <orderedlist>
+ <listitem>
+ <para>Add a <command>chapter</command> command after your
+ Abstract or Summary, giving the title of your first
+ chapter.</para>
+ </listitem>
+ <listitem>
+ <para>If you&apos;re planning ahead, add a few more
+ <command>chapter</command> commands for
+ subsequent chapters. Leave a few blank lines between
+ them to make it easier to add paragraphs of text
+ later.</para>
+ </listitem>
+ <listitem>
+ <para>By now I shouldn&apos;t need to tell you what to do
+ after making significant changes to your document
+ file.</para>
+ </listitem>
+ </orderedlist>
+ </example>
+ <sect2 id="secnum">
+ <title>Section numbering</title>
+ <indexterm>
+ <primary>section numbering</primary>
+ </indexterm>
+ <para>All document divisions get numbered automatically. Parts
+ get Roman numerals (Part&nbsp;I, Part&nbsp;II, &etc;);
+ chapters and sections get decimal numbering like this
+ document, and Appendixes (which are just a special case of
+ chapters, and share the same structure) are lettered (A, B,
+ C, &etc;).</para>
+ <para>You can change the depth to which section numbering
+ occurs, so you can turn it off selectively. In this document
+ it is set
+ to&nbsp;<literallayout role="3">\arabic{secnumdepth}</literallayout>.
+ If you only want parts, chapters, and sections numbered, not
+ subsections or subsubsections &etc;, you can change the
+ value of the <varname role="counter">secnumdepth</varname>
+ counter using the the <command>setcounter</command> command,
+ giving the depth value from <xref
+ linkend="secdepths"/>:</para>
+ <programlisting>
+\setcounter{secnumdepth}{1}
+ </programlisting>
+ <para>A related counter is <varname
+ role="counter">tocdepth</varname>, which specifies what
+ depth to take the Table of Contents to. It can be reset in
+ exactly the same way as <varname
+ role="counter">secnumdepth</varname>. The current setting
+ for this document is&nbsp;<literallayout
+ role="2">\arabic{tocdepth}</literallayout>.</para>
+ <programlisting>
+\setcounter{tocdepth}{3}
+ </programlisting>
+ <para>To get an <emphasis>unnumbered</emphasis> section
+ heading which does <emphasis>not</emphasis> go into the
+ Table of Contents, follow the command name with an asterisk
+ before the opening curly brace:</para>
+ <programlisting>
+\subsection*{Shopping List}
+ </programlisting>
+ <para>All the divisional commands from
+ <command>part*</command> to <command>subparagraph*</command>
+ have this <wordasword>starred</wordasword> version which can
+ be used on special occasions for an unnumbered heading when
+ the setting of <varname role="counter">secnumdepth</varname>
+ would normally mean it would be numbered.</para>
+ </sect2>
+ </sect1>
+ <sect1 id="paragraphs">
+ <title>Ordinary paragraphs</title>
+ <para>After section headings comes your text. Just type it and
+ leave a blank line between paragraphs. That&apos;s all
+ <LaTeX/> needs.</para>
+ <para>The blank line means <quote>start a new paragraph
+ here</quote>: it does <emphasis>not</emphasis> (repeat:
+ <emphasis role="high">not</emphasis>) mean you get a blank
+ line in the typeset output. Now read this paragraph
+ again and again until that sinks in.</para>
+ <para>The spacing between paragraphs is a separately definable
+ quantity, a <firstterm id="dimension">dimension</firstterm> or
+ <firstterm id="length">length</firstterm> called <varname
+ role="dimension">parskip</varname>. This is normally zero
+ (no space between paragraphs, because that&apos;s how books
+ are normally typeset), but you can easily set it to any size
+ you want with the <command>setlength</command> command in the
+ Preamble:</para>
+ <programlisting>
+\setlength{\parskip}{1cm}
+ </programlisting>
+ <para id="paraspace">This will set the space between paragraphs
+ to 1cm. See <xref linkend="dimensions"/> for details of the
+ various size units <LaTeX/> can use. <emphasis>Leaving
+ multiple blank lines between paragraphs in your source
+ document achieves nothing</emphasis>: all extra blank lines
+ get ignored by <LaTeX/> because the space between paragraphs
+ is
+ controlled only by the value of <varname
+ role="dimension">parskip</varname>.</para>
+ <para>White-space in <LaTeX/> can also be made flexible (what
+ <citetitle ref="latexbook" show="authoronly"></citetitle> calls
+ <wordasword>rubber</wordasword> lengths). This means that
+ values such as <varname role="dimension">parskip</varname> can
+ have a default dimension plus an amount of expansion minus an
+ amount of contraction. This is useful on pages in complex
+ documents where not every page may be an exact number of
+ fixed-height lines long, so some give-and-take in vertical
+ space is useful. You specify this in a
+ <command>setlength</command> command like this:</para>
+ <programlisting>
+\setlength{\parskip}{1cm plus4mm minus3mm}
+ </programlisting>
+ <para>Paragraph indentation can also be set with the
+ <command>setlength</command> command, although you would
+ always make it a fixed size, never a flexible one, otherwise
+ you would have very ragged-looking paragraphs.</para>
+ <programlisting>
+\setlength{\parindent}{6mm}
+ </programlisting>
+ <para>By default, the first paragraph after a heading follows
+ the standard Anglo-American publishers&apos; practice of
+ <emphasis>no</emphasis> indentation. Subsequent paragraphs are
+ indented by the value of <varname
+ role="dimension">parindent</varname> (default
+ 18pt).<footnote>
+ <para>Paragraph spacing and indentation are cultural
+ settings. If you are typesetting in a language other than
+ English, you should use the <methodname>babel</methodname>
+ package, which alters many things, including the spacing
+ and the naming of sections, to conform with the standards
+ of different countries and languages.</para>
+ </footnote> You can change this in the same way as any other
+ length.</para>
+ <para>In the printed copy of this document, the paragraph
+ indentation is set to <literallayout
+ role="12pt">\the\parindent</literallayout> and the space
+ between paragraphs is set to <literallayout
+ role="0pt">\the\parskip</literallayout>. These values do not
+ apply in the Web (<acronym ref="HTML"></acronym>) version because not all browsers are
+ capable of that fine a level of control, and because users can
+ apply their own stylesheets regardless of what this document
+ proposes.</para>
+ <example>
+ <title>Start typing!</title>
+ <orderedlist>
+ <listitem>
+ <para>Type some paragraphs of text. Leave a blank line
+ between each. Don&apos;t bother about line-wrapping or
+ formatting&mdash;<LaTeX/> will take care of all
+ that.</para>
+ </listitem>
+ <listitem>
+ <para>If you&apos;re feeling adventurous, add a
+ <command>section</command> command with the title of a
+ section within your first chapter, and continue typing
+ paragraphs of text below that.</para>
+ </listitem>
+ <listitem>
+ <para>Add one or more <command>setlength</command>
+ commands to your Preamble if you want to experiment with
+ changing paragraph spacing and indentation.</para>
+ </listitem>
+ </orderedlist>
+ </example>
+ <para>To turn off indentation completely, set it to zero (but
+ you still have to provide units: it&apos;s still a
+ measure!).</para>
+ <programlisting>
+\setlength{\parindent}{0in}
+ </programlisting>
+ <para>If you do this, though, and leave <varname
+ role="dimension">parskip</varname> set to zero, your readers
+ won&apos;t be able to tell easily where each paragraph begins!
+ If you want to use the style of having no indentation with a
+ space between paragraphs, use the
+ <methodname>parskip</methodname> package, which does it for
+ you (and makes adjustments to the spacing of lists and other
+ structures which use paragraph spacing, so they don&apos;t get
+ too far apart).</para>
+ </sect1>
+ <sect1 id="toc">
+ <title>Table of contents</title>
+ <indexterm>
+ <primary>table of contents</primary>
+ <secondary>automated entries</secondary>
+ </indexterm>
+ <para>All auto-numbered headings get entered in the Table of
+ Contents (ToC) automatically. You don&apos;t have to print a
+ ToC, but if you want to, just add the command
+ <command>tableofcontents</command> at the point where you want
+ it printed (usually after the Abstract or Summary).</para>
+ <para>Entries for the ToC are recorded each time you process
+ your document, and reproduced the <emphasis>next</emphasis>
+ time you process it, so you need to re-run <LaTeX/> one extra
+ time to ensure that all ToC page-number references
+ are correctly calculated.</para>
+ <para>We&apos;ve already seen in <xref linkend="sections"/> how
+ to use the optional argument to the sectioning commands to add
+ text to the ToC which is slightly different from the one
+ printed in the body of the document. It is also possible to
+ add extra lines to the ToC, to force extra or unnumbered
+ section headings to be included.</para>
+ <example>
+ <title>Inserting the table of contents</title>
+ <orderedlist>
+ <listitem>
+ <para>Go back and add a <command>tableofcontents</command>
+ command after the <literal>\end{abstract}</literal> command
+ in your document.</para>
+ </listitem>
+ <listitem>
+ <para>You guessed.</para>
+ </listitem>
+ </orderedlist>
+ </example>
+ <para id="loflot">The commands <command>listoffigures</command>
+ and <command>listoftables</command> work in exactly the same
+ way as <command>tableofcontents</command> to automatically
+ list all your tables and figures. If you use them, they
+ normally go after the <command>tableofcontents</command>
+ command.</para>
+ <para>The <command>tableofcontents</command> command normally
+ shows only numbered section headings, and only down to the
+ level defined by the <varname
+ role="counter">tocdepth</varname> counter (see <xref
+ linkend="secnum"/>), but you can add extra entries with the
+ <command>addcontentsline</command> command. For example if you
+ use an unnumbered section heading command to start a
+ preliminary piece of text like a Foreword or Preface, you can
+ write:<indexterm>
+ <primary>table of contents</primary>
+ <secondary>adding manual entry</secondary>
+ </indexterm></para>
+ <programlisting>
+\subsection*{Preface}
+\addcontentsline{toc}{subsection}{Preface}
+ </programlisting>
+ <para>This will format an unnumbered ToC entry for
+ <wordasword>Preface</wordasword> in the
+ <wordasword>subsection</wordasword> style. You can use
+ the same mechanism to add lines to the List of Figures or List
+ of Tables by substituting <filename>lof</filename> or
+ <filename>lot</filename> for <filename>toc</filename>.</para>
+ </sect1>
+ </chapter>
+ <chapter id="process">
+ <title>Typesetting, viewing and printing</title>
+ <indexterm><primary>typesetting</primary></indexterm>
+ <indexterm><primary>viewing</primary></indexterm>
+ <indexterm><primary>printing</primary></indexterm>
+ <para>We&apos;ve now got far enough to typeset what you&apos;ve
+ entered. I&apos;m assuming at this stage that you have typed
+ some sample text in the format specified in the previous
+ chapter, and you&apos;ve saved it in a plain-text file with a
+ filetype of
+ <literal>.tex</literal> and a name of your own choosing.</para>
+ <indexterm>
+ <primary>filenames</primary>
+ </indexterm>
+ <example>
+ <title>Saving your file</title>
+ <para>If you haven&apos;t already saved your file, do so now
+ (some editors and interfaces let you typeset the document
+ without saving it!).</para>
+ <para>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 <xref
+ linkend="filenames"/> for more details.</para>
+ </example>
+ <sidebar id="filenames">
+ <title>Picking suitable filenames</title>
+ <para>Never, ever use directories (folders) or file names
+ which contain spaces. Although your operating system
+ probably supports them, some don&apos;t, and they will
+ only cause grief and tears with <TeX/>.</para>
+ <para>Make filenames as short or as long as you wish, but
+ strictly avoid spaces. Stick to upper- and lower-case
+ letters without accents (A&ndash;Z and a&ndash;z), the
+ digits 0&ndash;9, the hyphen (<literal>-</literal>), and
+ the full point or period (<literal>.</literal>), (similar
+ to the conventions for a Web <acronym
+ ref="URI"></acronym>): it will let you refer to <TeX/>
+ files over the Web more
+ easily and make your files more portable.</para>
+ </sidebar>
+ <sect1 id="setting">
+ <title>Typesetting</title>
+ <para>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&mdash;there are two
+ formats available:</para>
+ <itemizedlist>
+ <listitem>
+ <para>The standard (default) <LaTeX/> program produces a
+ <acronym id="DVI">device-independent</acronym> 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/>.</para>
+ </listitem>
+ <listitem>
+ <para>The <productname>pdf<LaTeX/></productname> program
+ produces an Adobe Acrobat <acronym ref="PDF"></acronym>
+ file which can be used with any suitable previewer, such
+ as <productname>GSview</productname>,
+ <productname>PDFview</productname>,
+ <productname>Xpdf</productname>, the
+ <productname>Opera</productname> browser, or Adobe&apos;s
+ own <productname>Acrobat Reader</productname>.</para>
+ </listitem>
+ </itemizedlist>
+ <para>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&apos;t always come
+ pre-set with buttons or menus for every possible option,
+ because they can&apos;t guess which one you want.</para>
+ <sect2>
+ <title>Standard <LaTeX/></title>
+ <para>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 <wordasword>batch</wordasword> or
+ <wordasword>scripted</wordasword> processing).</para>
+ <para>Whichever way you run <LaTeX/>, it will process your
+ file and display a log or record of what it&apos;s doing
+ (see <xref linkend="terminal"/>: it looks the
+ same no matter what system you use). This is to let you see
+ where (if!) there are any errors or problems.</para>
+ <example>
+ <title>Running <LaTeX/> from the toolbar or menu</title>
+ <para>Run <LaTeX/> on your file. According to which system
+ you&apos;re using this will either be the
+ <guiicon><LaTeX/></guiicon> toolbar icon or the
+ <guimenu><TeX/></guimenu><guimenuitem><TeX/>
+ File</guimenuitem> menu item.</para>
+ <para>Your editor may suggest you save your file if you
+ haven&apos;t already done so. Do it.</para>
+ </example>
+ <para>If <LaTeX/> reports any errors&mdash;easily identifiable
+ as lines in the log beginning with an exclamation mark
+ (!)&mdash;<emphasis>don&apos;t panic!</emphasis> Turn to <xref
+ linkend="errmsg"/>, 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.</para>
+<!--
+ <itemizedlist>
+ <listitem>
+ <para>In some editors the log appears
+ in a separate window and you have to press the
+ <keycap>Enter</keycap> key to dismiss it after checking
+ it.</para>
+ </listitem>
+ <listitem>
+ <para>In <productname>Emacs</productname>, the log appears
+ in the bottom half of the edit window and can be
+ dismissed with the
+ <guimenu>Files</guimenu><guimenuitem>One
+ Window</guimenuitem> menu or by pressing <keycombo>
+ <keycap>Ctrl</keycap>
+ <keycap>X</keycap>
+ </keycombo><keycap>1</keycap>. Some recent versions of
+ <productname>Emacs</productname> hide the log if there
+ were no errors, and display it only if something went
+ wrong.</para>
+ </listitem>
+ </itemizedlist>
+-->
+ </sect2>
+ <sect2 id="cmdwin">
+ <title>Running <LaTeX/> from a command window</title>
+ <para>This is worth practising even if you normally use a
+ <acronym ref="GUI"></acronym>, so that you understand what it
+ does. See <xref linkend="cliex"/> for an example.</para>
+ <example id="terminal">
+ <title>Running <LaTeX/> in a terminal or console
+ window</title>
+ <itemizedlist>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ <listitem>
+ <para>Under Microsoft Windows you open a command window
+ by clicking on the
+ <guimenu>Start</guimenu><guisubmenu>Programs</guisubmenu><guimenuitem>MS-DOS</guimenuitem>
+ or
+ <guimenu>Start</guimenu><guisubmenu>Command
+ Prompt</guisubmenu> menu item.</para>
+ </listitem>
+ </itemizedlist>
+ <para>When the command window appears, type</para>
+ <programlisting remap="commandchars=\\\{\}">
+cd <userinput>documents</userinput>
+latex <userinput>mybook</userinput>&nbsp;
+ </programlisting>
+ <para>Substitute the relevant directory and file name.
+ Remember to press the <keycap>Enter</keycap> key at the
+ end of each line.</para>
+ </example>
+ <figure id="cliex">
+ <title>Command-line usage</title>
+ <graphic id="clidemo" fileref="terminal" width="75%"/>
+ </figure>
+ </sect2>
+ <sect2>
+ <title>pdf<LaTeX/></title>
+ <para>If your editor is set up to generate <acronym
+ ref="PDF"></acronym> files direct instead of <acronym
+ ref="DVI"></acronym> files, then you can click the
+ <guiicon>pdf<LaTeX/></guiicon> toolbar icon or type the
+ command <literal>pdflatex
+ <userinput>filename</userinput></literal> in a terminal
+ (console) window. <productname>Emacs</productname> does not
+ have a default menu configured for
+ <productname>pdf<LaTeX/></productname> but if you have
+ already run standard <LaTeX/> on the file, you can type ther
+ <literal>pdflatex</literal> command in the
+ <literal>*TeX-Shell*</literal> pane.</para>
+ </sect2>
+ </sect1>
+ <sect1 id="errmsg">
+ <title>Errors and warnings</title>
+ <para><LaTeX/> describes what it&apos;s typesetting while it does it,
+ and if it encounters something it doesn&apos;t understand or can&apos;t
+ do, it will display a message saying what&apos;s wrong. It may
+ also display warnings for less serious conditions.</para>
+ <para><emphasis>Don&apos;t panic if you see error
+ messages</emphasis>: it&apos;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 <xref linkend="errmsg"/> with an
+ explanation of how to fix them.</para>
+ <graphic fileref="dontpanic" width="50%"/>
+ <sect2 id="errs">
+ <title>Error messages</title>
+ <para>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&apos;s an example, showing that the user
+ mistyped the <command>tableofcontents</command>
+ command:</para>
+ <programlisting>
+! Undefined control sequence.
+l.6 \tableofcotnetns
+ </programlisting>
+ <para>When <LaTeX/> finds an error like this, it displays the
+ error message and pauses. You must type one of the following
+ letters to continue:</para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec align="center"/>
+ <colspec colwidth="4in" align="justify"/>
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Meaning</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><keycap>x</keycap></entry>
+ <entry>Stop immediately and e<emphasis
+ role="high">x</emphasis>it the program.</entry>
+ </row>
+ <row>
+ <entry><keycap>q</keycap></entry>
+ <entry>Carry on <emphasis
+ role="high">q</emphasis>uietly as best you can and
+ don&apos;t bother me with any more error
+ messages.</entry>
+ </row>
+ <row>
+ <entry><keycap>e</keycap></entry>
+ <entry>Stop the program but re-position the text in my
+ <emphasis role="high">e</emphasis>ditor at the point
+ where you found the error.<footnote>
+ <para>This only works if you&apos;re using an editor
+ which <LaTeX/> can communicate with.</para>
+ </footnote></entry>
+ </row>
+ <row>
+ <entry><keycap>h</keycap></entry>
+ <entry>Try to give me more <emphasis
+ role="high">h</emphasis>elp.</entry>
+ </row>
+ <row>
+ <entry><keycap>i</keycap></entry>
+ <entry>(followed by a correction) means <emphasis
+ role="high">i</emphasis>nput the correction in
+ place of the error and carry on.<footnote>
+ <para>This is only a temporary fix to get the file
+ processed. You still have to make that
+ correction in the editor.</para>
+ </footnote></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>Some systems (<productname>Emacs</productname> is one
+ example) run <LaTeX/> with a
+ <wordasword>non-stop</wordasword> switch turned on, so it
+ will always process through to the end of the file,
+ regardless of errors, or until a limit is reached.</para>
+ </sect2>
+ <sect2 id="warn">
+ <title>Warnings</title>
+ <para>Warnings don&apos;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).</para>
+ <para>Unlike other systems, which try to hide unevennesses in
+ the text&mdash;usually unsuccessfully&mdash;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/>&apos;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.</para>
+ </sect2>
+ <sect2>
+ <title>Examples</title>
+ <para>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&apos;s not
+ clear what you should do, ask for help.</para>
+ <para>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.</para>
+ <para>Newcomers should remember to check the list of special
+ characters in <link linkend="specials"></link>: a very large
+ number of errors when you are learning <LaTeX/> are due to
+ accidentally typing a special character when you didn&apos;t
+ mean to. This disappears after a few days as you get used to
+ them.</para>
+ <sect3 id="toomany">
+ <title>Too many &rbrace;&apos;s</title>
+ <indexterm>
+ <primary>Too many &rbrace;&apos;s</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Error messages</primary>
+ <secondary>Too many &rbrace;&apos;s</secondary>
+ </indexterm>
+ <programlisting>
+! Too many }'s.
+l.6 \date December 2004}
+ </programlisting>
+ <para>The reason <LaTeX/> thinks there are too many
+ <literal>}</literal>&apos;s here is that the opening curly
+ brace is missing after the <command>date</command> control
+ sequence and before the word <literal>December</literal>,
+ so the closing curly brace is seen as one too many (which
+ it is!).</para>
+ <para>In fact, there are other things which can follow the
+ <command>date</command> command apart from a date in curly
+ braces, so <LaTeX/> cannot possibly guess that
+ you&apos;ve missed out the opening curly brace&mdash;until
+ it finds a closing one!</para>
+ </sect3>
+ <sect3 id="undefcs">
+ <title>Undefined control sequence</title>
+ <indexterm>
+ <primary>Undefined control sequence</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Error messages</primary>
+ <secondary>Undefined control sequence</secondary>
+ </indexterm>
+ <programlisting>
+! Undefined control sequence.
+l.6 \dtae
+ {December 2004}
+ </programlisting>
+ <para>In this example, <LaTeX/> is complaining that it has
+ no such command (<wordasword>control
+ sequence</wordasword>) as <literal>\dtae</literal>.
+ Obviously it&apos;s been mistyped, but only a human can
+ detect that fact: all <LaTeX/> knows is
+ that <literal>\dtae</literal> is not a command it knows
+ about&mdash;it&apos;s undefined.</para>
+ <para>Mistypings are the commonest source of error. If your
+ editor has drop-down menus to insert common commands and
+ environments, use them!</para>
+ </sect3>
+ <sect3 id="runaway">
+ <title>Runaway argument</title>
+ <indexterm>
+ <primary>Runaway argument</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Error messages</primary>
+ <secondary>Runaway argument</secondary>
+ </indexterm>
+ <programlisting>
+Runaway argument?
+{December 2004 \maketitle
+! Paragraph ended before \date was complete.
+<![CDATA[<to be read again>]]>
+ \par
+l.8
+ </programlisting>
+ <para>In this error, the closing curly brace has been
+ omitted from the date. It&apos;s the opposite of the error in
+ <xref
+ linkend="toomany"/>, and it results in
+ <command>maketitle</command> trying to format the title
+ page while <LaTeX/> is still expecting more text for the
+ date! As
+ <command>maketitle</command> creates new paragraphs on the
+ title page, this is detected and <LaTeX/> complains that
+ the
+ previous paragraph has ended but <command>date</command>
+ is not yet finished.</para>
+ </sect3>
+ <sect3 id="underfull">
+ <title>Underfull hbox</title>
+ <indexterm>
+ <primary>Underfull hbox</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Error messages</primary>
+ <secondary>Underfull hbox</secondary>
+ </indexterm>
+ <programlisting>
+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]
+ </programlisting>
+ <para>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
+ <firstterm id="badness"></firstterm> (0&ndash;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.</para>
+ <para>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 <xref linkend="fdfiles"/> if you&apos;re
+ curious.</para>
+ </sect3>
+ <sect3 id="overfull">
+ <title>Overfull hbox</title>
+ <indexterm>
+ <primary>Overfull hbox</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Error messages</primary>
+ <secondary>Overfull hbox</secondary>
+ </indexterm>
+ <programlisting>
+[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-
+ </programlisting>
+ <para>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
+ (<emphasis>Win-</emphasis>). Line numbers and page numbers
+ are given as before. In this case, 9pt is too much to
+ ignore (over 3mm or more than <inlineequation>
+ <m:mfrac>
+ <m:mover>
+ <m:mn>1</m:mn>
+ </m:mover>
+ <m:munder>
+ <m:mn>8</m:mn>
+ </m:munder>
+ </m:mfrac>
+ </inlineequation>&inch;), 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).</para>
+ </sect3>
+ <sect3 id="nopkg">
+ <title>Missing package</title>
+ <indexterm>
+ <primary>File not found</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Error messages</primary>
+ <secondary>File not found</secondary>
+ </indexterm>
+ <programlisting><![CDATA[
+! 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:
+ ]]></programlisting>
+ <para>When you use the <command>usepackage</command> command
+ to request <LaTeX/> to use a certain package, it will look
+ for a file with the specified name and the filetype
+ <filename>.sty</filename>. In this case the user has
+ mistyped the name of the <methodname>paralist</methodname>
+ package, so it&apos;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 <xref linkend="ctan"/>).</para>
+ </sect3>
+ </sect2>
+ </sect1>
+ <sect1 id="dvi">
+ <title>Screen preview</title>
+ <indexterm><primary>preview</primary></indexterm>
+ <para>Once the file has been processed without errors (or even
+ if there are still errors, but you want to see what it&apos;s
+ doing with them), standard <LaTeX/> will have created a
+ <acronym ref="DVI"></acronym> file with the same name as your
+ document but the filetype
+ <literal>.dvi</literal>. If you&apos;re using
+ <productname>pdf<LaTeX/></productname>, a <acronym
+ ref="PDF"></acronym> file will have been created, and you
+ can skip to
+ <xref linkend="pdfview"/>.</para>
+ <sect2 id="dvipreview">
+ <title>Previewing DVI output</title>
+ <para>To see the typeset output, click on the
+ <guiicon>dvi</guiicon> Preview toolbar icon or use the
+ <guimenu>TeX</guimenu><guimenuitem>TeX View</guimenuitem>
+ menu item. A <acronym
+ ref="WYSIWYG"></acronym> preview window will appear with
+ your typeset display (see <xref linkend="dviview"/>).</para>
+ <warning id="bitmappreview">
+ <title>Bitmap preview fonts in DVI viewers</title>
+ <para>The first time you display your <acronym
+ ref="DVI"></acronym> 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&nbsp;1 fonts, however,
+ and don&apos;t have this delay.</para>
+ </warning>
+ <figure id="dviview">
+ <title>DVI preview</title>
+ <graphic fileref="xdvi" width="75%"/>
+ </figure>
+ <para>Most previewers have a wide range of scaling, zooming,
+ and measuring functions, but remember this is a
+ <emphasis>picture</emphasis> of your output: you cannot edit
+ the image. To change it, you always edit your source text
+ and reprocess the file.</para>
+ <para>With <productname>xdvi</productname> and its derivatives
+ like <productname>dviview</productname>, you can leave the
+ display window open, and after you&apos;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).</para>
+ <para><xref linkend="dviview"/> shows
+ <productname>xdvi</productname> displaying a page. With a
+ standard three-button mouse you get three levels of
+ micro-zoom to let you inspect fine details.</para>
+ </sect2>
+ <sect2 id="makeps">
+ <title>Previewing with PostScript</title>
+ <para><trademark>PostScript</trademark> is a page description
+ language invented by Adobe and used in laser printers and
+ high-end typesetters. It&apos;s been the universal standard
+ for electronically-formatted print files for nearly two
+ decades, and all printers and publishers are accustomed to
+ using it. <acronym ref="PDF"></acronym> is a descendant of
+ PostScript, and is rapidly taking over, but
+ <trademark>PostScript</trademark> itself is still extremely
+ common, largely because it is very robust, and is usually an
+ <acronym ref="ASCII"></acronym> 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 <trademark>PostScript</trademark> files, especially if
+ they contain bitmapped graphics.</para>
+ <para>The <productname>dvips</productname> program which comes
+ with all <TeX/> systems is used to generate
+ <trademark>PostScript</trademark> files directly from your
+ <acronym ref="DVI"></acronym> output. These
+ <filename>.ps</filename> files can be viewed, printed, sent
+ to a platemaker or filmsetter, or put online for
+ downloading.</para>
+ <para><acronym ref="DVI"></acronym> viewers cannot render some
+ <trademark>PostScript</trademark> graphical manipulations
+ like rotating and deforming, so an alternative to viewing
+ the DVI file direct is to generate a
+ <trademark>PostScript</trademark> file and use a
+ <trademark>PostScript</trademark> 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
+ <guiicon>dvips</guiicon> toolbar icon or menu entry and
+ click on it.</para>
+ <para>It&apos;s also very simple to do manually: let&apos;s
+ assume your <LaTeX/> file was called
+ <filename>mydoc.tex</filename>, so processing it has created
+ <filename>mydoc.dvi</filename>. Just type:</para>
+ <programlisting>
+dvips -o mydoc.ps mydoc
+ </programlisting>
+ <para role="cont">in a command window (see <xref
+ linkend="terminal"/> for how to use one)
+ and <productname>dvips</productname> will create
+ <filename>mydoc.ps</filename> which can be used both for
+ previewing and printing.</para>
+ <para>To view a <trademark>PostScript</trademark> file, you
+ need a <trademark>PostScript</trademark> previewer like
+ <productname>GSview</productname>, which works with the
+ <trademark>PostScript</trademark> interpreter
+ <productname>Ghostscript</productname>, which should have
+ been installed automatically along with your <TeX/> system
+ (if not, install both now: <productname>GSview</productname>
+ is separately licensed and cannot legally be included in
+ some older <TeX/> distributions, so you may have to download
+ it yourself).</para>
+ <para><productname>GSview</productname> can be set to watch
+ the <trademark>PostScript</trademark> file and automatically
+ update the display any time the file is changed, without you
+ even having to click on the window.</para>
+ </sect2>
+ <sect2 id="pdfview">
+ <title>Previewing with PDF</title>
+ <para>The <acronym id="PDF">Portable Document Format</acronym>
+ is a derivative of <trademark>PostScript</trademark>.
+ Whereas <trademark>PostScript</trademark> is a programming
+ language in itself, <acronym ref="PDF"></acronym> is in effect
+ the <emphasis>result</emphasis> of processing a document
+ through <trademark>PostScript</trademark>: it&apos;s a binary
+ file format, extremely compact, and well-supported on all
+ platforms.</para>
+ <para>If your system is configured to generate <acronym
+ ref="PDF"></acronym> files direct instead of <acronym
+ ref="DVI"></acronym> files, just open the
+ <filename>.pdf</filename> file using any <acronym
+ ref="PDF"></acronym> previewer or browser.</para>
+ <para>Most editors are configured to display a toolbar icon
+ which will pop up <productname>Acrobat Reader</productname>
+ or some other viewer with the current <acronym
+ ref="PDF"></acronym> output file.</para>
+ <para>Adobe&apos;s <productname>Acrobat Reader</productname>
+ cannot automatically update the view if you reprocess your
+ document, in the way that <productname>xdvi</productname>
+ and <productname>GSview</productname> can. You
+ have to close the display with <keycombo>
+ <keycap>Ctrl</keycap>
+ <keycap>W</keycap>
+ </keycombo> and reload the file with <keycombo>
+ <keycap>Alt</keycap>
+ <keycap>F</keycap>
+ </keycombo><keycap>1</keycap>.</para>
+ <warning>
+ <title>Bitmap preview fonts in Acrobat Reader</title>
+ <para>Acrobat Reader is extremely poor at rendering
+ Type&nbsp;3 (bitmap) fonts. If you are using these (either
+ in an old <LaTeX/> installation which has not been
+ upgraded to Type&nbsp;1, or with files using specialist
+ fonts only available in Type&nbsp;3 format), you will see
+ a very fuzzy display at low magnifications. It will print
+ perfectly, but Acrobat Reader&apos;s display is
+ disappointing. The solution is to use a better previewer
+ or to upgrade to the Type&nbsp;1 versions of the fonts
+ if possible, or both. If you need to
+ use Type&nbsp;3 fonts in <acronym ref="PDF"></acronym>s,
+ 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.</para>
+ </warning>
+ </sect2>
+ </sect1>
+ <sect1 id="print">
+ <title>Printer output</title>
+ <indexterm>
+ <primary>printing</primary>
+ </indexterm>
+ <para><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.
+ <emphasis>How</emphasis> you do it varies slightly according
+ to how you do your typesetting and previewing:</para>
+ <variablelist>
+ <varlistentry>
+ <term>If you are using DVI</term>
+ <listitem>
+ <para>and you have a previewer which has a
+ <function>print</function> function configured for your
+ printer, you can use that. If not, create a
+ <trademark>PostScript</trademark> file and use
+ <productname>GSview</productname> instead.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>If you are using PDF</term>
+ <listitem>
+ <para>you can print directly from your <acronym
+ ref="PDF"></acronym> viewer. Be careful about using
+ the <quote>Fit to page</quote> options, as they will
+ change the size of your document so all your
+ measurements will be different.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Non-<trademark>PostScript</trademark> printers</term>
+ <listitem>
+ <para>You can create a <trademark>PostScript</trademark>
+ file with <productname>dvips</productname> (see <xref
+ linkend="makeps"/>) and use
+ <productname>GSview</productname> to print it
+ (<productname>GSview</productname> can print
+ <trademark>PostScript</trademark> files to almost any
+ make or model of non-<trademark>PostScript</trademark>
+ printer).</para>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>If you have a real <trademark>PostScript</trademark>
+ printer</term>
+ <listitem>
+ <para>or you are using a system with built-in
+ <trademark>PostScript</trademark> printing support (such
+ as Linux or Mac), you can create and send
+ <trademark>PostScript</trademark> output directly from
+ your editor to the printer without the need to open it
+ in a previewer first. In
+ <productname>Emacs</productname>, for example, this is
+ what happens when you use the
+ <guimenu><TeX/></guimenu><guimenuitem><TeX/>
+ Print</guimenuitem> menu item.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>Both the <productname>dvips</productname> program and all
+ the previewers that print tend to have facilities for printing
+ selected pages, printing in reverse, scaling the page size,
+ <indexterm>
+ <primary>page size</primary>
+ <secondary>scaling</secondary>
+ </indexterm><indexterm>
+ <primary>printing</primary>
+ <secondary>reverse order</secondary>
+ </indexterm><indexterm>
+ <primary>printing</primary>
+ <secondary>selected pages</secondary>
+ </indexterm> and printing only odd or even pages for two-sided
+ work. If you are using <trademark>PostScript</trademark> there
+ are programs for manipulating the output
+ (<productname>pstops</productname>), for example to perform
+ page imposition to get 4, 8, or 16 pages to a sheet for making
+ booklets (<productname>psnup</productname>).</para>
+ <example>
+ <title>Print it!</title>
+ <para>Show that you have understood the process of
+ typesetting, previewing, and printing, by displaying your
+ document and printing it.</para>
+ </example>
+ <para>If you need a
+ non-<trademark>PostScript</trademark>/<productname>Ghostscript</productname>
+ solution, install a separate <TeX/> print driver for your
+ printer. Some
+ may be supplied with your <TeX/> installation, and there are
+ dozens more on <acronym ref="CTAN"></acronym>. Their names all
+ start with <filename>dvi</filename> and are followed by an
+ abbreviation for the printer make or model like
+ <productname>dvieps</productname> for Epson,
+ <productname>dvihp</productname> for Hewlett-Packard,
+ <productname>dvialw</productname> 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</para>
+ <programlisting>
+dvihp mydoc | lpr
+ </programlisting>
+ <para>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):</para>
+ <programlisting>
+dvihp mydoc -o mydoc.hp
+copy /b mydoc.hp LPT1:
+ </programlisting>
+ <para>Read the documentation for the driver, as the options and
+ defaults vary.</para>
+ </sect1>
+ </chapter>
+ <chapter id="ctan">
+ <title>CTAN, packages, <?LaTeX \newline{}?>and online help</title>
+ <para>The <acronym id="CTAN">Comprehensive <TeX/> Archive
+ Network</acronym> is a repository of Web and <acronym
+ ref="FTP"></acronym> servers worldwide which contain copies of
+ almost every piece of free software related to <TeX/> and
+ <LaTeX/>.</para>
+ <para><acronym ref="CTAN"></acronym> is based on three main
+ servers, and there are several online indexes available. There
+ are complete <TeX/> and <LaTeX/> systems for all platforms,
+ utilities for text and graphics processing, conversion programs
+ into and out of <LaTeX/>, printer drivers, extra typefaces, and
+ (possibly the most important) the <LaTeX/> packages. The three
+ main servers are:</para>
+ <itemizedlist>
+ <listitem>
+ <para><TeX/> Users Group: <ulink
+ url="http://www.ctan.org/"></ulink></para>
+ </listitem>
+ <listitem>
+ <para>UK <TeX/> Users Group: <ulink
+ url="http://www.tex.ac.uk/"></ulink></para>
+ </listitem>
+ <listitem>
+ <para>Deutschsprachige Anwendervereinigung <TeX/> e.V. (DANTE,
+ the German-speaking <TeX/> Users Group); <ulink
+ url="http://dante.ctan.org/"></ulink></para>
+ </listitem>
+ </itemizedlist>
+ <sidebar>
+ <para><acronym ref="CTAN"></acronym> should
+ <emphasis>always</emphasis> be your first port of call when
+ looking for a software update or a feature you want to use.
+ Please don&apos;t ask the <link linkend="help">network help
+ resources</link> until you have checked <acronym
+ ref="CTAN"></acronym> and the <acronym
+ ref="FAQ"></acronym> (<xref linkend="faq"/>).</para>
+ </sidebar>
+ <sect1 id="packages">
+ <title>Packages</title>
+ <indexterm>
+ <primary>packages</primary>
+ <secondary>using</secondary>
+ </indexterm>
+ <para>Add-on features for <LaTeX/> are known as <firstterm
+ id="pack">packages</firstterm>. Dozens of these are
+ pre-installed with <LaTeX/> and can be used in your documents
+ immediately. They should all be stored in subdirectories of
+ <filename>texmf/tex/latex</filename> named after each package.
+ To find out what other packages are available and what they
+ do, you should use the <ulink
+ url="http://www.ctan.org/search"><acronym
+ ref="CTAN"></acronym> search page</ulink> which includes a
+ link to Graham Williams&apos; comprehensive package
+ catalogue.</para>
+ <para>A package is a file or collection of files containing
+ extra <LaTeX/> commands and programming which add new styling
+ features or modify those already existing. Installed package
+ files all end with <filename>.sty</filename> (there may be
+ ancillary files as well).</para>
+ <para>When you try to typeset a document which requires a
+ package which is not installed on your system, <LaTeX/> will
+ warn you with an error message that it is missing (see <xref
+ linkend="nopkg"/>), and you can
+ then download the package and install it using the
+ instructions in <xref linkend="pkginst" />. You can also
+ download updates to packages you already have (both the ones
+ that were installed along with your version of <LaTeX/> as
+ well as ones you added).</para>
+ <para>There is no limit to the number of packages you can have
+ installed on your computer (apart from disk space!), but there
+ is probably a physical limit to the number that can be used
+ inside any one <LaTeX/> document at the same time, although it
+ depends on how big each package is. In practice there is no
+ problem in having even a couple of dozen packages active (the
+ style file for this document uses over 30).</para>
+ <sect2 id="colorpkg">
+ <title>Using an existing package</title>
+ <para>To use a package already installed on your system,
+ insert a <command>usepackage</command> command in your
+ document preamble with the package name in curly braces, as
+ we have already seen in earlier chapters. For example, to
+ use the <methodname>color</methodname> package, which lets
+ you typeset in colours (I warned you this was
+ coming!), you would type:</para>
+ <programlisting>
+\documentclass[11pt,a4paper,oneside]{report}
+\usepackage{color}
+\begin{document}
+...
+\end{document}
+ </programlisting>
+ <para>You can include several package names in one
+ <command>usepackage</command> command by separating the
+ names with commas, and you can have more than one
+ <command>usepackage</command> command.</para>
+ <para>Some packages allow optional settings in square
+ brackets. If you use these, you must give the package its
+ own separate <command>usepackage</command> command, like
+ <methodname>geometry</methodname> shown below:</para>
+ <programlisting id="oldtitle">
+\documentclass[11pt,a4paper,oneside]{report}
+\usepackage{pslatex,palatino,avant,graphicx,color}
+\usepackage[margin=2cm]{geometry}
+\begin{document}
+
+\title{\color{red}Practical Typesetting}
+\author{\color{blue}Peter Flynn\\Silmaril Consultants}
+\date{\color{green}December 2005}
+\maketitle
+
+\end{document}
+ </programlisting>
+ <para>(Incidentally, this is a rather crude way to do colours in
+ titling on a once-off basis: if it&apos;s for a repeatable
+ style we&apos;ll see in <xref linkend="macros"/> how it can
+ be automated and kept out of the author&apos;s way.)</para>
+ <para>Many packages can have additional formatting
+ specifications in optional arguments in square brackets, in
+ the same way as <methodname>geometry</methodname>
+ does. Read the documentation for the package concerned to
+ find out what can be done.</para>
+ <example id="geoex">
+ <title>Add colour</title>
+ <para>Use the <methodname>color</methodname> package to add
+ some colour to your document. Stick with primary colours
+ for the moment.</para>
+ <para>Use the <methodname>geometry</methodname>
+ package to change the margins.</para>
+ <para>Reprocess and print your document if you have a colour
+ printer (monochrome printers should print it in shades of
+ grey).</para>
+ </example>
+ <para><acronym ref="CMYK"></acronym> and <acronym
+ ref="RGB"></acronym> are not the only colour
+ models. <personname id="ul">
+ <firstname>Uwe</firstname>
+ <surname>Kern</surname>
+ </personname>&apos;s
+ <methodname>xcolor</methodname> package defines half a
+ dozen, and includes facilities for converting colour
+ values from one model to another.</para>
+ </sect2>
+ <sect2 id="packagedoc">
+ <title>Package documentation</title>
+ <indexterm>
+ <primary>packages</primary>
+ <secondary>documentation</secondary>
+ </indexterm>
+ <para>To find out what commands a package provides (and thus
+ how to use it), you need to read the documentation. In the
+ <filename>texmf/doc</filename> subdirectory of your
+ installation there should be directories full of
+ <filename>.dvi</filename> files, one for every package
+ installed. These can be previewed or printed like any other
+ <acronym ref="DVI"></acronym> file (see
+ <xref linkend="dvipreview"/>). If your installation
+ procedure has not installed the documentation, the <acronym
+ ref="DVI"></acronym> files can all be downloaded from
+ <acronym ref="CTAN"></acronym>.</para>
+ <para>Before using a package, you should read the
+ documentation carefully, especially the subsection usually
+ called <wordasword>User Interface</wordasword>, which
+ describes the commands the package makes available. You
+ cannot just guess and hope it will work: you have to read it
+ and find out.</para>
+ <para>See the next section for details of how to create the
+ documentation <filename>.dvi</filename> file for additional
+ packages you install yourself.</para>
+ <example>
+ <title>Read all about it</title>
+ <para>Find and view (or print) the documentation on the
+ <methodname>geometry</methodname> package you used in
+ <xref linkend="geoex"/>.</para>
+ <para>Investigate some of the other package documentation
+ files in the directory.</para>
+ </example>
+ </sect2>
+ </sect1>
+ <sect1 id="pkginst">
+ <title>Downloading and installing packages</title>
+ <indexterm>
+ <primary>packages</primary>
+ <secondary>downloading</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>packages</primary>
+ <secondary>installing</secondary>
+ </indexterm>
+ <para>Once you have identified a package you need and
+ haven&apos;t already got (or you have got it and need to
+ update it), use the indexes on any <acronym
+ ref="CTAN"></acronym> server to find the package you need
+ and the directory where it can be downloaded from.</para>
+ <sect2 id="downloadpkg">
+ <title>Downloading packages</title>
+ <para>What you need to look for is always <emphasis>two
+ files</emphasis>, one ending in <filename>.dtx</filename>
+ and the other in <filename>.ins</filename>. The first is a
+ DOC<TeX/><indexterm>
+ <primary>DOC<TeX/></primary>
+ </indexterm> file, which combines the package program and its
+ documentation in a single file. The second is the
+ installation routine (much smaller). You <emphasis>must
+ always</emphasis> download <emphasis>both</emphasis>
+ files.</para>
+ <para>If the two files are not there, it means one of two
+ things:</para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>Either</emphasis> the package is part of a
+ much larger bundle which you shouldn&apos;t normally update
+ unless you change version of <LaTeX/>;<footnote>
+ <para>For example, there is no
+ <filename>color.dtx</filename> and
+ <filename>color.ins</filename> for the
+ <methodname>color</methodname> package because it
+ forms part of the <methodname>graphics</methodname>
+ bundle, which is installed on all <LaTeX/> systems
+ anyway. Such packages change very rarely, as they
+
+ form part of the core of <LaTeX/> and are very
+ stable. In
+ general you should never try to update these
+ packages in isolation.</para>
+ </footnote></para>
+ </listitem>
+ <listitem>
+ <para><emphasis>or</emphasis> it&apos;s one of a few rare or
+ unusual packages still supplied as a single
+ <filename>.sty</filename> file intended for the now
+ obsolete <LaTeX/>&thinsp;2.09.<footnote>
+ <para>You can try to use these if you wish but they
+ are not guaranteed to work, and have now almost all
+ been replaced by <LaTeXe/> versions. Always look for
+ the
+ <filename>.dtx</filename> and
+ <filename>.ins</filename> pair of files
+ first.</para>
+ </footnote></para>
+ </listitem>
+ </itemizedlist>
+ <para id="packinst">Download both files to a <firstterm
+ id="tempdir">temporary directory</firstterm>. If you use
+ Windows, keep a folder like <filename>C:\tmp</filename> or
+ <filename>C:\temp</filename> for this; Mac and Linux systems
+ already have a <filename>/tmp</filename> directory.</para>
+ </sect2>
+ <sect2 id="installpkg">
+ <title>Installing a package</title>
+ <para>There are four steps to installing a <LaTeX/>
+ package:</para>
+ <indexterm>
+ <primary>packages</primary>
+ <secondary>installing</secondary>
+ </indexterm>
+ <procedure>
+ <step id="extract">
+ <title>Extract the files</title>
+ <para>Run <LaTeX/> on the <filename>.ins</filename> file.
+ That is, open the file in your editor and process it as
+ if it were a <LaTeX/> document (which is it), or if you
+ prefer, type <literal>latex</literal> followed by the
+ <filename>.ins</filename> filename in a command window
+ in your temporary directory.</para>
+ <para>This will extract all the files needed from the
+ <filename>.dtx</filename> file (which is why you must
+ have both of them present in the temporary directory).
+ Note down or print the names of the files created if
+ there are a lot of them (read the log file if you want
+ to see their names again).</para>
+ </step>
+ <step id="dtxdoc">
+ <title>Create the documentation</title>
+ <para>Run <LaTeX/> on the <filename>.dtx</filename> file
+ twice. This will create a <filename>.dvi</filename> file
+ of documentation explaining what the package is for and
+ how to use it. Two passes through <LaTeX/> are needed in
+ order to resolve any internal crossreferences in the
+ text (a feature we&apos;ll come onto later). If you
+ prefer to create <acronym ref="PDF"></acronym> then run
+ <productname>pdf<LaTeX/></productname> instead. View or
+ print this file in the usual manner (see <xref
+ linkend="dvi"/>).</para>
+ </step>
+ <step>
+ <title>Install the files</title>
+ <para>While the documentation is printing, move or copy
+ the files created in <xref remap="step"
+ linkend="extract"/>
+ from your temporary directory to the right place[s] in
+ your <TeX/>&nbsp;<emphasis>local</emphasis> installation
+ directory tree&mdash;always your <quote>local</quote>
+ directory tree, <orderedlist>
+ <listitem>
+ <para>to prevent your new package accidentally
+ overwriting files in the main <TeX/>
+ directories</para>
+ </listitem>
+ <listitem>
+ <para>to avoid your newly-installed files being
+ overwritten when you next update your version of
+ <TeX/></para>
+ </listitem>
+ </orderedlist>.</para>
+ <table id="where">
+ <title>Where to put files from packages</title>
+ <tgroup cols="3">
+ <colspec colsep="flush" align="left"/>
+ <colspec align="left" role="\ttfamily"/>
+ <colspec colwidth="1.5in" align="justify" colsep="flush"
+ role="\pbs{\raggedright}\footnotesize"/>
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Directory (under
+ <filename>texmf-local/</filename>)</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><filename>.cls</filename></entry>
+ <entry>tex/latex/base</entry>
+ <entry>Document class file</entry>
+ </row>
+ <row>
+ <entry><filename>.sty</filename></entry>
+ <entry>tex/latex/<userinput>packagename</userinput></entry>
+ <entry>Style file: the normal package
+ content</entry>
+ </row>
+ <row>
+ <entry><filename>.bst</filename></entry>
+ <entry>bibtex/bst/<userinput>packagename</userinput></entry>
+ <entry><BibTeX/> style</entry>
+ </row>
+ <row>
+ <entry><filename>.mf</filename></entry>
+ <entry>fonts/source/public/<userinput>typeface</userinput></entry>
+ <entry>&metafont; outline</entry>
+ </row>
+ <row>
+ <entry><filename>.fd</filename></entry>
+ <entry>tex/latex/mfnfss</entry>
+ <entry>Font Definition files for &metafont; fonts</entry>
+ </row>
+ <row>
+ <entry><filename>.fd</filename></entry>
+ <entry>tex/latex/psnfss</entry>
+ <entry>Font Definition files for PostScript
+ Type&nbsp;1 fonts</entry>
+ </row>
+ <row>
+ <entry><filename>.pfb</filename></entry>
+ <entry>/fonts/type1/<userinput>foundry</userinput>/<userinput>typeface</userinput></entry>
+ <entry>PostScript Type&nbsp;1 outline</entry>
+ </row>
+ <row>
+ <entry><filename>.afm</filename></entry>
+ <entry>/fonts/afm/<userinput>foundry</userinput>/<userinput>typeface</userinput></entry>
+ <entry>Adobe Font Metrics for Type&nbsp;1
+ fonts</entry>
+ </row>
+ <row>
+ <entry><filename>.tfm</filename></entry>
+ <entry>/fonts/tfm/<userinput>foundry</userinput>/<userinput>typeface</userinput></entry>
+ <entry><TeX/> Font Metrics for &metafont; and
+ Type&nbsp;1 fonts</entry>
+ </row>
+ <row>
+ <entry><filename>.vf</filename></entry>
+ <entry>/fonts/vf/<userinput>foundry</userinput>/<userinput>typeface</userinput></entry>
+ <entry><TeX/> virtual fonts</entry>
+ </row>
+ <row>
+ <entry><filename>.dvi</filename></entry>
+ <entry>/doc</entry>
+ <entry>package documentation</entry>
+ </row>
+ <row>
+ <entry><filename>.pdf</filename></entry>
+ <entry>/doc</entry>
+ <entry>package documentation</entry>
+ </row>
+ <row>
+ <entry>others</entry>
+ <entry>tex/latex/<userinput>packagename</userinput></entry>
+ <entry>other types of file unless instructed
+ otherwise</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para><quote>The right place</quote> sometimes causes
+ confusion, especially if your <TeX/> installation is old
+ or does not conform to the <acronym ref="TDS"><TeX/>
+ Directory Structure</acronym>. For a <acronym
+ ref="TDS"></acronym>-conformant system, this is either
+ <itemizedlist>
+ <listitem>
+ <para>for <LaTeX/> packages, a suitably-named
+ subdirectory of
+ <filename>texmf-local/tex/latex/</filename><footnote>
+ <para>See <xref linkend="rightplace"/> for how
+ to create a parallel structure in your local
+ directory if your installation didn&apos;t create
+ one for you.</para>
+ </footnote></para>
+ </listitem>
+ <listitem>
+ <para>a suitably-named subdirectory of
+ <filename>texmf-local/</filename> for files like
+ <BibTeX/> styles which are not just for <LaTeX/> but can
+ be used in other <TeX/> systems</para>
+ </listitem>
+ </itemizedlist>.</para>
+ <para><quote>Suitably-named</quote> means sensible and
+ meaningful (and probably short). For a package like
+ <methodname>paralist</methodname>, for example, I&apos;d call
+ the directory <filename>paralist</filename>.</para>
+ <para>Often there is just a <filename>.sty</filename> file
+ to move but in the case of complex packages there may be
+ more, and they may belong in different locations. For
+ example, new <BibTeX/> packages or font packages will
+ typically have several files to install. This is why it
+ is a good idea to create a subdirectory for the package
+ rather than dump the files into
+ <filename>misc</filename> along with other unrelated
+ stuff.</para>
+ <para>If there are configuration or other files, read the
+ documentation to find out if there is a special or
+ preferred location to move them to.</para>
+<!--
+ <para>For <BibTeX/> styles, the <LaTeX/>
+ <filename>.sty</filename> files belong in
+ <filename>texmf-local/tex/latex/...</filename> (called
+ after the package) but the <filename>.bst</filename> file
+ belongs in
+ <filename>texmf-local/bibtex/bst</filename>.</para>
+ <para>Don&apos;t forget to move the
+ <filename>.dvi</filename> or <filename>.pdf</filename>
+ file of documentation into
+ <filename>texmf-local/doc</filename>.</para>
+-->
+ </step>
+ <step id="texindex">
+ <title>Update your index</title>
+ <indexterm>
+ <primary>packages</primary>
+ <secondary>indexing</secondary>
+ </indexterm>
+ <para>Finally, run your <TeX/> indexer program to update
+ the package database. This program comes with every
+ modern version of <TeX/> and is variously called
+ <productname>texhash</productname>,
+ <productname>mktexlsr</productname>, or even
+ <productname>configure</productname>, or it might just
+ be a mouse click on a button or menu in your editor.
+ Read the documentation that came with your installation
+ to find out which it is.</para>
+ </step>
+ </procedure>
+ <warning>
+ <para>This last step is <emphasis>utterly
+ essential</emphasis>, otherwise nothing will
+ work.</para>
+ </warning>
+ <example id="insttest">
+ <title>Install a package</title>
+ <para>Download and install the
+ <methodname>paralist</methodname> package (which
+ implements inline lists).</para>
+ </example>
+ <para>The reason this process has not been automated widely is
+ that there are still thousands of installations which do not
+ conform to the <acronym ref="TDS"></acronym>, such as old
+ shared Unix systems and some Microsoft Windows systems, so
+ there is no way for an installation program to guess where
+ to put the files: <emphasis>you</emphasis> have to know
+ this. There are also systems where the owner, user, or
+ installer has chosen <emphasis>not</emphasis> to follow the
+ recommended <acronym ref="TDS"></acronym> directory
+ structure, or is unable to do so for political or security
+ reasons (such as a shared system where she cannot write to a
+ protected directory).</para>
+ <para>The reason for having the
+ <filename>texmf-local</filename> directory (called
+ <filename>texmf.local</filename> on some systems) is to
+ provide a place for local modifications or personal updates,
+ especially if you are a user on a shared or managed system
+ (Unix, Linux, VMS, Windows NT/2000/XP, &etc;) where you may
+ not have write-access to the main <TeX/>
+ installation directory tree. You can also have a personal
+ <filename>texmf</filename> subdirectory in your own login
+ directory. Your installation must be configured to look in
+ these directories first, however, so that any updates to
+ standard packages will be found there
+ <emphasis>before</emphasis> the superseded copies in the
+ main <filename>texmf</filename> tree. All modern <TeX/>
+ installations should do this anyway, but if not, you can
+ edit <filename>texmf/web2c/texmf.cnf</filename> yourself.
+ There is an example in <xref linkend="cnf"/>.</para>
+ </sect2>
+ <sect2 id="rightplace">
+ <title>Replicating the TDS</title>
+ <para>The <acronym id="TDS"><TeX/> Directory
+ Structure</acronym> is documented at <ulink
+ url="http://www.tug.org/tds/"></ulink>. I find it useful to
+ make the directory structure of
+ <filename>texmf-local</filename> the same as that of
+ <filename>texmf</filename>. Examine the subdirectories of
+ <filename>texmf/tex/latex/</filename> for examples. For
+ updates of packages which came with your <LaTeX/>
+ distribution (as distinct from new ones you are adding
+ yourself), you can then use the same subdirectory name and
+ position in <filename>texmf-local/...</filename> as the
+ original used in <filename>texmf/...</filename>.</para>
+ <para>If you want to create the entire subdirectory structure
+ ready for use, you can do it under Unix with the following
+ commands:</para>
+ <programlisting>
+cd /usr/TeX/texmf
+find . -type d -exec mkdir -p /usr/TeX/texmf-local/{} \;
+ </programlisting>
+ <para>If you are using Microsoft Windows, you can download
+ <productname>Cygwin</productname>, which provides you with
+ the standard Unix tools in a shell window. The above command
+ should also work on a Mac running OS&thinsp;X. In all cases,
+ if your installation directory is not
+ <filename>/usr/TeX</filename>, you need to substitute the
+ actual paths to your <filename>texmf</filename> and
+ <filename>texmf-local</filename> directories.</para>
+ </sect2>
+ </sect1>
+ <sect1 id="help">
+ <title>Online help</title>
+ <indexterm>
+ <primary>help</primary>
+ </indexterm>
+ <para>The indexes and documentation files on <acronym
+ ref="CTAN"></acronym> are the primary online resource for
+ self-help on specific packages, and you should read these
+ carefully before asking questions about packages.</para>
+ <sect2 id="faq">
+ <title>The FAQ</title>
+ <para>For general queries you should read the <acronym
+ id="FAQ">Frequently-Asked Questions</acronym> document so
+ that you avoid wasting online time asking about things for
+ which there is already an easily-accessible answer.</para>
+ <para>The <acronym ref="FAQ"></acronym> is managed by the UK
+ <TeX/> Users Group and can be found at <ulink
+ url="http://www.tex.ac.uk/faq/"></ulink>&thinsp;.</para>
+ </sect2>
+ <sect2>
+ <title>The <TeX/>hax mailing list</title>
+ <para>Another support resource is the mailing list <ulink
+ url="texhax@tug.org"></ulink>. Again, feel free to ask
+ questions, but again, try to answer the question yourself
+ first (and say what you&apos;ve tried in your
+ message).</para>
+ </sect2>
+ <sect2>
+ <title>Web sites</title>
+ <para>The <TeX/> Users Group, as well as most local user
+ groups, maintains a web site (<ulink
+ url="http://www.tug.org"></ulink>) with lots of information
+ about various aspects of the <TeX/>
+ system. See <xref linkend="tugform"/> for information on
+ joining TUG.</para>
+ </sect2>
+ <sect2>
+ <title>News</title>
+ <para>The Usenet newsgroup <ulink url="comp.text.tex"
+ type="news:"></ulink> is the principal forum for other
+ questions and answers about <LaTeX/>. Feel free to ask
+ questions, but
+ please do not ask frequently-asked questions: read the
+ <acronym ref="FAQ"></acronym> instead. The people who answer
+ the questions do so voluntarily, unpaid, and in their own
+ time, so please don&apos;t treat this as a commercial
+ support service.</para>
+ <para>To access Usenet news, type the following <acronym
+ ref="URI"></acronym> into your browser&apos;s
+ <wordasword>Location</wordasword> or
+ <wordasword>Address</wordasword> window:
+ <systemitem>news:comp.text.tex</systemitem> (if your browser
+ doesn&apos;t support Usenet news properly, change it for one
+ that does, like <ulink
+ url="http://www.mozilla.org/"><productname>Mozilla</productname></ulink>), or download one of the many free newsreaders.<footnote>
+ <para>Note that this means newsreaders for the Usenet News
+ (NNTP) service. It does <emphasis>not</emphasis> mean
+ syndication readers for RSS, which are a different thing
+ entirely&mdash;these are unfortunately also sometimes
+ referred to as <quote>newsreaders</quote>.</para>
+ </footnote></para>
+ </sect2>
+ <sect2>
+ <title>Commercial support</title>
+ <para>If you need commercial levels of support, such as
+ 24-hour phone contact, or macro-writing services, you can
+ buy one of the several excellent commercial versions of
+ <TeX/>, or contact a consultancy which deals with <TeX/>
+ (details on the TUG Web site).</para>
+ </sect2>
+ </sect1>
+ </chapter>
+ <chapter id="otherdoc">
+ <title>Other document structures</title>
+ <para>It is perfectly possible to write whole documents using
+ nothing but section headings and paragraphs. As mentioned in
+ <xref linkend="sections"/>, novels, for example, usually consist
+ just of chapters divided into paragraphs. However, it&apos;s more
+ common to need other features as well, especially if the
+ document is technical in nature or complex in structure.</para>
+ <para>It&apos;s worth pointing out that
+ <wordasword>technical</wordasword> doesn&apos;t necessarily mean
+ <wordasword>computer technical</wordasword> or
+ <wordasword>engineering technical</wordasword>: it just means it
+ contains a lot of <foreignphrase lang="gr"
+ remap="&tau;&eta;&chi;&nu;&epsilon;">tekne</foreignphrase>, the
+ specialist material or artistry of its field. A literary
+ analysis such as <citetitle ref="macnamara"></citetitle> (on the
+ marginal notes in the manuscripts of <citetitle ref="bovary"
+ show="authoronly"></citetitle>&apos;s novel) is every bit as
+ technical in the literary or linguistic field as the maintenance
+ manual for the Airbus 380 is in the aircraft engineering
+ field.</para>
+ <para>This chapter covers the most common features needed in
+ writing structured documents: lists, tables, figures (including
+ images), sidebars like boxes and panels, and verbatim text
+ (computer program listings). In <xref linkend="texttools"/> we
+ will cover footnotes, cross-references, citations, and other
+ textual tools.</para>
+ <sect1 id="briefstruct">
+ <title>A little think about structure</title>
+ <para>It&apos;s very easy to sit down at a keyboard with a
+ traditional wordprocessor and just start typing. If it&apos;s
+ a very short document, or something transient or relatively
+ unimportant, then you just want to type it in and make it look
+ <wordasword>right</wordasword> by highlighting with the mouse
+ and clicking on font styles and sizes.</para>
+ <para>In doing so, you may achieve the effect you wanted, but
+ your actions have left no trace behind of
+ <emphasis>why</emphasis> you made these changes. This is
+ usually unimportant for trivial or short-term documents, but
+ if you write longer or more complex documents, or if you often
+ write documents to a regular pattern, then making them
+ consistent by manual methods becomes a nightmare.
+ <LaTeX/>&apos;s facilities for automation are based on you
+ providing this <wordasword>why</wordasword>
+ information.</para>
+ <para>If your documents have any of the features below, then you
+ have probably already started thinking about structure.</para>
+ <itemizedlist mark="\Square">
+ <listitem>
+ <para>The document naturally divides into sections (parts,
+ chapters, &etc;).</para>
+ </listitem>
+ <listitem>
+ <para>The document is long.</para>
+ </listitem>
+ <listitem>
+ <para>There is lots of repetitive formatting in the
+ document.</para>
+ </listitem>
+ <listitem>
+ <para>The document is complex (intellectually or
+ visually).</para>
+ </listitem>
+ <listitem>
+ <para>There are lots of figures or tables (or examples,
+ exercises, panels, sidebars, &etc;).</para>
+ </listitem>
+ <listitem>
+ <para>Accuracy is important in formatting the
+ document.</para>
+ </listitem>
+ <listitem>
+ <para>A master copy is needed for future reference or
+ reprinting.</para>
+ </listitem>
+ <listitem>
+ <para>This is a formal or official document needing special
+ care and attention.</para>
+ </listitem>
+ <listitem>
+ <para>It&apos;s <emphasis>my</emphasis> thesis, book,
+ leaflet, pamphlet, paper, article, &etc;
+ <emphasis>That</emphasis>&apos;s why I care.</para>
+ </listitem>
+ <listitem>
+ <para>The document (or part of it) may need ongoing or
+ occasional re-editing and republishing.</para>
+ </listitem>
+ </itemizedlist>
+ <para>If you&apos;ve got that far, you&apos;re over half-way
+ done. Using a structural editor&mdash;even a simple
+ outliner&mdash;can make a huge difference to the quality of
+ your thinking because you are consciously organising your
+ thoughts before setting them down. And it can make just as big
+ a difference to your formatting as well: more consistent,
+ better presented, easier for the reader to navigate through,
+ and more likely to be read and understood&mdash;which is
+ presumably why you are writing the document in the first
+ place.</para>
+ </sect1>
+ <sect1 id="lists">
+ <title>Lists</title>
+ <indexterm><primary>lists</primary></indexterm>
+ <para>Lists are useful tools for arranging thoughts in a
+ digestible format, usually a small piece of information at a
+ time. There are four basic types of list, shown in <xref
+ linkend="listtypes"/>.</para>
+ <table id="listtypes">
+ <title>Types of lists</title>
+ <tgroup cols="2">
+ <colspec colwidth="48%" colsep="flush" align="justify"
+ role="\pbs{\raggedright}"/>
+ <colspec colwidth="48%" colsep="flush" align="justify"
+ role="\pbs{\raggedright}"/>
+ <tbody>
+ <row>
+ <entry><formalpara>
+ <title>Random or arbitrary lists</title>
+ <para>(sometimes called
+ <wordasword>itemized</wordasword> or
+ <wordasword>bulleted</wordasword> lists) where the
+ order of items is unimportant. The
+ items are often prefixed with a bullet or other
+ symbol for clarity or decoration, but are
+ sometimes simply left blank, looking like
+ miniature paragraphs (when they are known as
+ <wordasword>simple</wordasword> or
+ <wordasword>trivial</wordasword> lists).</para>
+ </formalpara></entry>
+ <entry><formalpara>
+ <title>Enumerated or sequential lists</title>
+ <para>(sometimes called
+ <wordasword>numbered</wordasword> lists) where the
+ order of items is critical, such as sequences of
+ instructions or rankings of importance. The
+ enumeration can be numeric (Arabic or Roman), or
+ lettered (uppercase or lowercase), and can even be
+ programmed to be hierarchical (1.a.viii, 2.3.6,
+ &etc;).</para>
+ </formalpara></entry>
+ </row>
+ <row>
+ <entry><formalpara>
+ <title>Descriptive or labelled lists</title>
+ <para>(sometimes called
+ <wordasword>discussion</wordasword> lists), which
+ are composed of subheadings or topic labels
+ (usually unnumbered but typographically distinct),
+ each followed by one or more indented paragraphs
+ of discussion or explanation.</para>
+ </formalpara></entry>
+ <entry><formalpara>
+ <title>Inline lists</title>
+ <para>which are sequential in nature, just like
+ enumerated lists, but are
+ <orderedlist>
+ <listitem>
+ <para>formatted <emphasis>within</emphasis>
+ their paragraph</para>
+ </listitem>
+ <listitem>
+ <para>usually labelled with letters,</para>
+ </listitem>
+ </orderedlist>&nbsp;like this example. The items
+ are often mutually inclusive or exclusive, with
+ the final item prefixed by
+ <wordasword>and</wordasword> or
+ <wordasword>or</wordasword> respectively.</para>
+ </formalpara></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>There are actually two other types, segmented lists and
+ reference lists, but these are much rarer, and outside the
+ scope of this document.</para>
+ <indexterm><primary>environment</primary></indexterm>
+ <para>The structure of lists in <LaTeX/> is identical for each
+ type, but with a different environment name. Lists are another
+ example of this <LaTeX/> technique (environments), where a pair
+ of matched commands surrounds some text which needs special
+ treatment.</para>
+ <para>Within a list environment, list items are always
+ identified by the command <command>item</command> (followed by
+ an item label in [square brackets] in the case of labelled
+ lists). You don&apos;t type the bullet or the number or the
+ formatting, it&apos;s all automated.</para>
+ <sect2>
+ <title>Itemized lists</title>
+ <indexterm>
+ <primary>lists</primary>
+ <secondary>itemized</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>lists</primary>
+ <secondary>bulleted</secondary>
+ </indexterm>
+ <para>To create an itemized list, use the the
+ <modespec>itemize</modespec> environment:</para>
+ <informalexample>
+ <programlisting>
+\begin{itemize}
+
+\item Itemized lists usually have a bullet;
+
+\item Long items use `hanging indentation',
+whereby the text is wrapped with a margin
+which brings it clear of the bullet used in
+the first line of each item;
+
+\item The bullet can be changed for any other
+symbol, for example from the \textsf{bbding}
+or \textsf{pifont} package.
+
+\end{itemize}
+ </programlisting>
+ <itemizedlist id="labelitem"
+ mark="\raisebox{-.25ex}{\PencilRight}">
+ <listitem>
+ <para>Itemized lists usually have a bullet;</para>
+ </listitem>
+ <listitem>
+ <para>Long items use <wordasword>hanging
+ indentation</wordasword>, whereby the text is
+ wrapped with a margin which brings it clear of the
+ bullet used in the first line of each item;</para>
+ </listitem>
+ <listitem>
+ <para>The bullet can be changed for any other symbol,
+ for example from the <methodname>bbding</methodname>
+ or <methodname>pifont</methodname> package.</para>
+ </listitem>
+ </itemizedlist>
+ </informalexample>
+ <para>The default list bullet is round and solid<footnote>
+ <para>If your browser font doesn&apos;t show it, don't
+ worry: most don&apos;t. <LaTeX/> will.</para>
+ </footnote> (&bull;) which is also available with the
+ command <command>textbullet</command> if you load the
+ <methodname>textcomp</methodname> package. See <xref
+ linkend="bullets"/> for details of how to change the
+ settings for list item bullets.</para>
+ </sect2>
+ <sect2>
+ <title>Enumerated lists</title>
+ <indexterm>
+ <primary>lists</primary>
+ <secondary>numbered</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>lists</primary>
+ <secondary>enumerated</secondary>
+ </indexterm>
+ <para>To create an enumerated list, use the
+ <modespec>enumerate</modespec> environment:</para>
+ <informalexample>
+ <programlisting>
+\begin{enumerate}
+
+\item Enumerated lists use numbering on each
+item (can also be letters or roman numerals);
+
+\item Long items use `hanging indentation'
+just the same as for itemized lists;
+
+\item The numbering system can be changed for
+any level.
+
+\end{enumerate}
+ </programlisting>
+ <orderedlist>
+ <listitem>
+ <para>Enumerated lists use numbering on each
+ item (can also be letters or roman numerals);</para>
+ </listitem>
+ <listitem>
+ <para>Long items use <wordasword>hanging
+ indentation</wordasword>, just the same as for
+ itemized lists;</para>
+ </listitem>
+ <listitem>
+ <para>The numbering system can be changed for any
+ level.</para>
+ </listitem>
+ </orderedlist>
+ </informalexample>
+ <para>See <xref linkend="numberschemes"/> for details of how
+ to change the numbering schemes for each level.</para>
+ <para>In standard <LaTeX/> document classes, the vertical
+ spacing between items, and above and below the lists as a
+ whole, is more than between paragraphs. If you want
+ tightly-packed lists, use the
+ <methodname>mdwlist</methodname> package, which provides
+ <wordasword>starred</wordasword> versions
+ (<modespec>itemize*</modespec>,
+ <modespec>enumerate*</modespec>, etc).</para>
+ </sect2>
+ <sect2 id="desc">
+ <title>Description lists</title>
+ <indexterm>
+ <primary>lists</primary>
+ <secondary>description</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>lists</primary>
+ <secondary>discussion</secondary>
+ </indexterm>
+ <para>To create a description list, use the
+ <modespec>description</modespec> environment:</para>
+ <informalexample>
+ <programlisting>
+\begin{description}
+
+\item[Identification:] description lists
+require a topic for each item given in
+square brackets;
+
+\item[Hanging indentation:] Long items use
+this in the same way as all other lists;
+
+\item[Reformatting:] Long topics can be
+reprogrammed to fold onto multiple lines.
+
+\end{description}
+ </programlisting>
+ <variablelist>
+ <varlistentry>
+ <term>Identification:</term>
+ <listitem>
+ <para>description lists require a topic for each item
+ given in square brackets;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Hanging indentation:</term>
+ <listitem>
+ <para>Long items use this in the same way as all other
+ lists;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Reformatting:</term>
+ <listitem>
+ <para>Long topics can be reprogrammed to fold onto
+ multiple lines.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </informalexample>
+ <para>All three of these types of lists can have multiple
+ paragraphs per item: just type the additional paragraphs in
+ the normal way, with a blank line between each. So long as
+ they are still contained within the enclosing environment,
+ they will automatically be indented to follow underneath their
+ item.</para>
+ </sect2>
+ <sect2 id="inlinelists">
+ <title>Inline lists</title>
+ <indexterm>
+ <primary>lists</primary>
+ <secondary>inline</secondary>
+ </indexterm>
+ <para>Inline lists are a special case as they require the use
+ of the <methodname>paralist</methodname> package which
+ provides the <modespec>inparaenum</modespec> environment
+ (with an optional formatting specification in square
+ brackets):</para>
+ <informalexample>
+ <programlisting>
+\usepackage{paralist}
+...
+\textbf{\itshape Inline lists}, which are
+sequential in nature, just like enumerated
+lists, but are \begin{inparaenum}[\itshape
+a\upshape)]\item formatted within their
+paragraph; \item usually labelled with
+letters; and \item usually have the final
+item prefixed with `and' or
+`or'\end{inparaenum}, like this example.
+ </programlisting>
+ <para><firstterm id="inlines">Inline lists</firstterm>,
+ which are sequential in nature, just like enumerated
+ lists, but are <orderedlist>
+ <listitem>
+ <para>formatted within their paragraph</para>
+ </listitem>
+ <listitem>
+ <para>usually labelled with letters</para>
+ </listitem>
+ <listitem>
+ <para>usually have the final
+ item prefixed with <wordasword>and</wordasword> or
+ <wordasword>or</wordasword></para>
+ </listitem>
+ </orderedlist>, like this example.</para>
+ </informalexample>
+ <para>See <xref linkend="typo"/> for details of the
+ font-changing commands used in the optional argument to
+ <modespec>inparaenum</modespec>.</para>
+ <example>
+ <title>List practice</title>
+ <para>Add some lists to your document. Pick any two of the
+ ones described here to practice with.</para>
+ <para>If you successfully installed
+ <methodname>paralist</methodname> in <xref
+ linkend="insttest"/> then you can use inline lists as
+ described in <xref linkend="inlinelists"/>.</para>
+ </example>
+ </sect2>
+ <sect2>
+ <title>Reference lists and segmented lists</title>
+ <para>Reference lists are visually indistinguishable from
+ numbered or lettered lists, but the numbering or lettering
+ does <emphasis>not</emphasis> imply a sequence. The numbers
+ or letters are just used as labels so that the items can be
+ referred to from elsewhere in the text (as in <quote>see
+ item 501(c)3</quote>). In this sense they are really a
+ kind of sub-sectional division, and <LaTeX/>&apos;s
+ <command>paragraph</command> or
+ <command>subparagraph</command> commands (with appropriate
+ renumbering) would probably be a far better solution than
+ using a list. Label them and refer to them with
+ <command>label</command> and <command>ref</command> as for
+ any other cross-reference (see <xref
+ linkend="xrefs"/>).</para>
+ <para>Segmented lists are a highly specialised structure and
+ outside the scope of this document. For details of their
+ usage, see the <citetitle pubwork="chapter"
+ ref="teiguide">Segmentation and
+ Alignment</citetitle>.</para>
+ </sect2>
+ <sect2 id="numberschemes">
+ <title>Lists within lists</title>
+ <para>You can start a new list environment within the item of
+ an existing list, so you can embed one list inside another
+ up to four deep. The lists can be of any type, so you can
+ have a description list containing an item in which there is
+ a numbered sub-list, within which there is an item
+ containing a bulleted sub-sub-list. </para>
+ <orderedlist>
+ <listitem>
+ <para>by default an outer enumerated list is numbered in
+ Arabic numerals;</para>
+ <orderedlist>
+ <listitem>
+ <para>an embedded enumerated list is lettered in
+ lowercase;</para>
+ <orderedlist>
+ <listitem>
+ <para>a third level is numbered in lowercase Roman
+ numerals;</para>
+ <orderedlist>
+ <listitem>
+ <para>the fourth level uses uppercase
+ alphabetic letters.</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </orderedlist>
+ <para>Multiple embedded lists automatically change the bullet
+ or numbering scheme so that the levels don&apos;t get
+ confused, and the spacing between levels is adjusted to
+ become fractionally tighter for more deeply nested
+ levels.</para>
+ <para>These are only defaults and can easily be changed by
+ redefining the relevant set of values. You could also add a
+ fifth and further levels, although I suspect that would mean
+ your document structure needed some careful analysis, as
+ lists embedded five deep will probably confuse your
+ readers.</para>
+ <para>The values for lists come in pairs: for each level there
+ is a counter to count the items and a command to produce the
+ label:<footnote>
+ <para>In fact, any time you define a counter in <LaTeX/>,
+ you automatically get a command to reproduce its value.
+ So if you defined a new counter <varname
+ role="counter">example</varname> to use in a teaching
+ book, by saying <literal>\newcounter{example}</literal>,
+ that automatically makes available the command
+ <literal>\theexample</literal> for use when you want to
+ display the current value of <varname
+ role="counter">example</varname>.</para>
+ </footnote></para>
+ <informaltable>
+ <tgroup cols="4">
+ <colspec align="right"/>
+ <colspec align="center"/>
+ <colspec align="left"/>
+ <colspec align="left"/>
+ <thead>
+ <row>
+ <entry>Level</entry>
+ <entry>Default</entry>
+ <entry>Counter</entry>
+ <entry>Label command</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>1</entry>
+ <entry>digit.</entry>
+ <entry><varname role="counter">enumi</varname></entry>
+ <entry><command>theenumi</command></entry>
+ </row>
+ <row>
+ <entry>2</entry>
+ <entry>(letter)</entry>
+ <entry><varname
+ role="counter">enumii</varname></entry>
+ <entry><command>theenumii</command></entry>
+ </row>
+ <row>
+ <entry>3</entry>
+ <entry>roman.</entry>
+ <entry><varname
+ role="counter">enumiii</varname></entry>
+ <entry><command>theenumiii</command></entry>
+ </row>
+ <row>
+ <entry>4</entry>
+ <entry>LETTER.</entry>
+ <entry><varname
+ role="counter">enumiv</varname></entry>
+ <entry><command>theenumiv</command></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>Note that each counter and command ends with the Roman
+ numeral value of its level (this is to overcome the rule
+ that <LaTeX/> commands can only be made of
+ letters&mdash;digits wouldn&apos;t work here). To
+ change the format of a numbered list item counter, just
+ renew the meaning of its label:</para>
+ <programlisting>
+\renewcommand{\theenumi}{\Alph{enumi}}
+\renewcommand{\theenumii}{\roman{enumii}}
+\renewcommand{\theenumiii}{\arabic{enumiii}}
+ </programlisting>
+ <para role="cont" id="thecounter">This would make the
+ outermost list use uppercase letters, the second level use
+ lowercase roman, and the third level use ordinary Arabic
+ numerals. The fourth level would remain unaffected.</para>
+ <example>
+ <title>Nesting</title>
+ <para>Extend your use of lists by nesting one type inside a
+ different one.</para>
+ </example>
+ <warning>
+ <title>Lists: a caution to the unwary</title>
+ <para>Treat lists with care: people sometimes use tables for
+ labelled information which is really a list and would be
+ better handled as such. They often do this because their
+ wordprocessor has no way to do what they want (usually to
+ place the item label level with the description or
+ explanation) <emphasis>except</emphasis> by using a table,
+ hence they are misled into believing that their text is
+ really a table when it&apos;s actually not.</para>
+ </warning>
+ </sect2>
+ </sect1>
+ <sect1 id="tables">
+ <title>Tables</title>
+ <indexterm><primary>tables</primary></indexterm>
+ <para>Tabular typesetting is the most complex and time-consuming
+ of all textual features to get right. This holds true whether
+ you are typing in plain-text form, using a wordprocessor,
+ using <LaTeX/>, using <acronym ref="HTML"></acronym> or
+ <acronym ref="XML"></acronym>, using a <acronym
+ ref="DTP"></acronym> system, or some other text-handling
+ package. Fortunately, <LaTeX/> provides a
+ table model with a mixture of defaults and configurability to
+ let it produce very high quality tables with a minimum of
+ effort.</para>
+ <warning>
+ <title>Terminology</title>
+ <para><LaTeX/>, in common with standard typesetting
+ practice, uses the word <wordasword>Table</wordasword> to
+ mean a formal textual feature, numbered and with a caption,
+ referred to from the text (as in <wordasword>See
+ Table&nbsp;5</wordasword>). Sometimes you can get
+ <wordasword>informal</wordasword> tables, which simply occur
+ between two paragraphs, without caption or number.</para>
+ <para>The arrangement of information in rows and columns
+ <emphasis>within</emphasis> either of these structures is
+ called a <wordasword>tabulation</wordasword> or
+ <wordasword>tabular matter</wordasword>.</para>
+ <para>It is important to keep this distinction firmly in mind
+ for this section.</para>
+ </warning>
+ <sect2 id="floats">
+ <title>Floats</title>
+ <indexterm><primary>floats</primary></indexterm>
+ <para>Tables and Figures are what printers refer to as
+ <wordasword>floats</wordasword>. This means they are not
+ part of the normal stream of text, but separate entities,
+ positioned in a part of the page to themselves (top, middle,
+ bottom, left, right, or wherever the designer specifies).
+ They always have a caption describing them and they are
+ always numbered so they can be referred to from elsewhere in
+ the text.</para>
+ <para><LaTeX/> automatically floats Tables and Figures,
+ depending on how much space is left on the page at the point
+ that they are processed. If there is not enough room on the
+ current page, the float is moved to the top of the next
+ page. This can be changed by moving the Table or Figure
+ definition to an earlier or later point in the text, or by
+ adjusting some of the parameters which control automatic
+ floating.</para>
+ <para>Authors sometimes have many floats occurring in rapid
+ succession, which raises the problem of how they are
+ supposed to fit on the page and still leave room for text.
+ In this case, <LaTeX/> stacks them all up and prints them
+ together if possible, or leaves them to the end of the
+ chapter in protest. The skill is to space them out within
+ your text so that they intrude neither on the thread of your
+ argument or discussion, nor on the visual balance of the
+ typeset pages. But this is a skill few authors have, and
+ it&apos;s one point at which professional typographic advice
+ or manual intervention may be needed.</para>
+ <para>There is a <modespec>float</modespec> package which lets
+ you create new classes of floating object (perhaps Examples
+ or Exercises).</para>
+ </sect2>
+ <sect2>
+ <title>Formal tables</title>
+ <para>To create a <LaTeX/> Table, use the <modespec>table</modespec>
+ environment containing a <command>caption</command> command
+ where you type the caption, and a <command>label</command>
+ command to give the Table a label by which you can refer to
+ it.</para>
+ <programlisting>
+\begin{table}
+\caption{Project expenditure to year-end 2006}
+\label{ye2006exp}
+...
+\end{table}
+ </programlisting>
+ <para>Numbering is automatic, but the <command>label</command>
+ command <emphasis>must follow</emphasis> the
+ <command>caption</command> command, not precede it. The
+ numbering automatically includes the chapter number in
+ document classes where this is appropriate (but this can of
+ course be overridden). The <command>caption</command>
+ command has an optional argument to provide a short caption
+ if the full caption would be too long for the <link
+ linkend="loflot">List of Tables</link>:</para>
+ <programlisting>
+\caption[Something short]{Some very long caption that
+will only look reasonable in the full figure.}
+ </programlisting>
+ </sect2>
+ <sect2>
+ <title>Tabular matter</title>
+ <para>Within a Table, you can either typeset the tabular
+ matter using <LaTeX/>, or include a table captured as an
+ image from elsewhere. We will see how to include images in
+ <xref linkend="figures"/> on Figures, where they are more
+ common.</para>
+ <para>To typeset tabular matter, use the
+ <modespec>tabular</modespec> environment. The
+ <literal>\begin{tabular}</literal> command must be followed
+ by a compulsory second argument in curly braces giving the
+ alignment of the columns. These are specified for each
+ column using one of single letters <literal>l</literal>,
+ <literal>c</literal>, and <literal>r</literal> for
+ left-aligned, centered, or right-aligned text, or the letter
+ <literal>p</literal> followed by a width argument if you
+ want a long entry to wrap to several lines (a miniature
+ paragraph as a single cell on each row).</para>
+ <para><TeX/>&apos;s original tabular settings were designed
+ for classical numerical tabulations, where each cell
+ contains a single value. The <literal>p</literal>
+ specification allows a cell to be a miniature paragraph set
+ to a specific width. These are <literal>p</literal> column
+ specifications are <emphasis>not</emphasis> multi-row
+ entries, they are single cells which contain multiple lines
+ of typesetting: the distinction is very important.
+ Auto-adjusting space between columns is possible with the
+ <methodname>tabularx</methodname> package, but the
+ auto-resizing column widths used in web pages are not
+ available in <LaTeX/>.</para>
+ <para>The <methodname>array</methodname> package provides for
+ many other typographic variations such as left-aligned,
+ right-aligned, and centred multi-line columns, and other
+ packages provide decimal-aligned columns, row-spanning and
+ column-spanning, multi-page, and rotated (landscape format)
+ tables.</para>
+ <table id="ye2006exp" condition="b">
+ <title>Project expenditure to year-end 2006</title>
+ <tgroup cols="3">
+ <colspec align="center"/>
+ <colspec align="left"/>
+ <colspec align="right"/>
+ <thead>
+ <row>
+ <entry></entry>
+ <entry>Item</entry>
+ <entry>&EUR; Amount</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry></entry>
+ <entry>Total</entry>
+ <entry role="total">64,783</entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <row>
+ <entry>a)</entry>
+ <entry>Salaries (2 research assistants)</entry>
+ <entry>28,000</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>Conference fees and travel expenses</entry>
+ <entry>14,228</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>Computer equipment (5 workstations)</entry>
+ <entry>17,493</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>Software</entry>
+ <entry>3,562</entry>
+ </row>
+ <row>
+ <entry>b)</entry>
+ <entry>Rent, light, heat, &etc;</entry>
+ <entry>1,500</entry>
+ </row>
+ </tbody>
+ <para>The Institute also contributes to (a) and
+ (b).</para>
+ </tgroup>
+ </table>
+ <para>As an example, a tabular setting with three columns, the
+ first one centered, the second left-aligned, and the third
+ one right-aligned, would therefore be specified as
+ <literal>{clr}</literal>, as in the example below. Note the
+ use of indentation to make the elements of the table clear
+ for editing, and note also how the typeset formatting is
+ unaffected by this (see <xref linkend="ye2006exp"/>).</para>
+ <programlisting><![CDATA[
+\begin{table}
+ \caption{Project expenditure to year-end 2006}
+ \label{ye2006exp}
+ \begin{center}
+ \begin{tabular}{clr}
+ &Item&\EUR\ Amount\\
+ \hline
+ a)&Salaries (2 research assistants)&28,000\\
+ &Conference fees and travel expenses&14,228\\
+ &Computer equipment (5 workstations)&17,493\\
+ &Software&3,562\\
+ b)&Rent, light, heat, etc.&1,500\\\cline{3-3}
+ &Total&64,783
+ \end{tabular}
+ \par\medskip\footnotesize
+The Institute also contributes to (a) and (b).
+ \end{center}
+\end{table}
+ ]]></programlisting>
+ <para>You do not need to format the tabular data in your
+ editor: <LaTeX/> does this for you when it typesets the
+ table, using the column specifications you provided. Extra
+ space is automatically added between columns, and can be
+ adjusted by changing the <varname
+ role="dimension">tabcolsep</varname> dimension.
+ <personname id="tak">
+ <firstname>Takaaki</firstname>
+ <surname>Ota</surname>
+ </personname> provides an excellent Tables mode for
+ <productname>Emacs</productname> which provides a
+ spreadsheet-like interface and can generate <LaTeX/> table
+ source code (see <xref
+ linkend="tabmode"/>).</para>
+ <figure id="tabmode">
+ <title>Tables mode for
+ <productname>Emacs</productname></title>
+ <graphic fileref="table" width="75%"/>
+ </figure>
+ <para>It is conventional to centre the tabular setting within
+ the Table, using the <modespec>center</modespec> environment
+ (note US spelling) or the <command>centering</command>
+ command. The entries for each cell are separated by an
+ ampersand character (<literal>&amp;</literal>) and the end
+ of a row is marked by
+ the double-backslash (<literal>\\</literal>).</para>
+ <para>The <command>hline</command> command draws a rule across
+ all columns and the <command>cline</command> command draws a
+ rule across a range of columns (here, under column three
+ only&mdash;the argument needs a range). If used, these commands <emphasis>follow</emphasis>
+ the
+ <literal>\\</literal> of the row they apply to. There are
+ some extra formatting commands after the tabular material in
+ the example. These are explained in
+ <xref linkend="typo"/>.</para>
+ <para>If there is no data for a cell, just don&apos;t type
+ anything&mdash;but you still need the
+ <literal>&amp;</literal> separating it from the next
+ column&apos;s data. The astute reader will already have
+ deduced that for a table of
+ <inlineequation>
+ <m:mi>n</m:mi>
+ </inlineequation> columns, there must always be
+ <inlineequation>
+ <m:mi>n</m:mi>
+ <m:mo>&minus;</m:mo>
+ <m:mn>1</m:mn>
+ </inlineequation> ampersands in each row. The exception to
+ this is when the <command>multicolumn</command> command is
+ used to create cells which span multiple columns. There is
+ also a package (<modespec>multirow</modespec>) to enable
+ cells to span multiple rows, but both of these techniques
+ are outside the scope of this document.</para>
+ </sect2>
+ <sect2>
+ <title>Tabular techniques for alignment</title>
+ <para>As mentioned earlier, it&apos;s also perfectly possible
+ to typeset tabular matter outside a formal Table, where you
+ want to lay out an informal tabulation between paragraphs
+ where a fully floating formal Table would be unnecessary
+ (these are usually quite short: there are several of them in
+ this document).</para>
+ <para>Tabular mode can also be used wherever you need to align
+ material side by side, such as in designing letterheads,
+ where you may want your company logo and address on one side
+ and some other information on the other.</para>
+ <para>By default, <LaTeX/> typesets
+ <modespec>tabular</modespec> environments inline to the
+ surrounding text, so if you want your alignment displayed by
+ itself, put it inside a positioning environment like
+ <modespec>center</modespec>,
+ <modespec>flushright</modespec>, or
+ <modespec>flushleft</modespec>, or leave a blank line or
+ <command>par</command> before and after so it gets typeset
+ separately.</para>
+ <para>There is much more to tabular setting:
+ full details are in the manuals mentioned in
+ <xref linkend="docs"/>. One final note to remind you of the
+ automated crossreferencing features: because the example
+ table is labelled, it can be referenced from anywhere in the
+ document as <xref linkend="ye2006exp"/> just by using
+ <literal>\ref{ye2006exp}</literal>, regardless of how much
+ the surrounding document or structure is moved or
+ edited.</para>
+ <example>
+ <title>Create a tabulation</title>
+ <para>Create one of the following in your document:</para>
+ <itemizedlist>
+ <listitem>
+ <para>a formal Table with a caption showing the number
+ of people in your class broken down by age and
+ sex;</para>
+ </listitem>
+ <listitem>
+ <para>an informal tabulation showing the price for three
+ products;</para>
+ </listitem>
+ <listitem>
+ <para>the logo <literallayout width="48"
+ remap="y2klogo">\setlength{\fboxsep}{-3pt}\setlength{\fboxrule}{.4pt}
+ \fbox{\begin{tabular}{cc}\tiny YEAR\\[-.8em]\tiny 2
+ 0 0 0\vrule depth1em
+ width0pt\end{tabular}}</literallayout> (hint: <xref
+ linkend="fbox"/>)</para>
+ </listitem>
+ </itemizedlist>
+ </example>
+ </sect2>
+ </sect1>
+ <sect1 id="figures">
+ <title>Figures</title>
+ <indexterm><primary>figures</primary></indexterm>
+ <indexterm><primary>floats</primary></indexterm>
+ <para>As explained in <xref linkend="floats"/>, Figures and
+ Tables float to a vacant part of the page, as they are not
+ part of the sequence of sentences making up your text, but
+ illustrative objects that you refer to.</para>
+ <para>Figures can contain text, diagrams, pictures, or any other
+ kind of illustration. To create a figure, use the
+ <modespec>figure</modespec> environment: like Tables, they
+ automatically get numbered, and must include a caption (with a
+ label after the caption, if needed, exactly the same as for
+ Tables)</para>
+ <programlisting>
+\begin{figure}
+\caption{Total variable overhead variance (after
+ \citeauthor[p.191]{bull}}
+\label{workeff}
+\begin{center}
+\includegraphics[width=.75\columnwidth]{diagram}
+\end{center}
+\end{figure}
+ </programlisting>
+ <figure id="workeff">
+ <title>Total variable overhead variance (after <citetitle
+ ref="bull" show="both">p.191</citetitle>)</title>
+ <graphic fileref="diagram" width="75%" />
+ </figure>
+ <para>You can see that the structure is very similar to the
+ <modespec>table</modespec> environment, but in this case we
+ have a graphic included. Details of this command
+ (<command>includegraphics</command>) are in the next section.
+ Details of the bibliographic citation mechanism are in <xref
+ linkend="bib"/></para>
+ <para>The content of the Figure could of course also be textual,
+ in the form of a list or a text diagram. <LaTeX/> has a simple
+ drawing environment called <modespec>picture</modespec>, which
+ lets you create a limited set of lines and curves, but for a
+ diagram of any complexity, you should use a standard vector
+ drawing program (see <xref linkend="graphictypes"/>).</para>
+ </sect1>
+ <sect1 id="images">
+ <title>Images</title>
+ <indexterm>
+ <primary>images</primary>
+ </indexterm>
+ <indexterm>
+ <primary>graphics</primary>
+ </indexterm>
+ <para>Images (graphics) can be included anywhere in a <LaTeX/>
+ document, although in most cases of formal documents they will
+ occur in Figures (see preceding section). To use graphics, you
+ need to use the <methodname>graphicx</methodname> package in
+ your preamble:
+ <literal>\usepackage{graphicx}</literal><footnote>
+ <para>You may find a lot of old files which use a package
+ called <methodname>epsf</methodname>. Don&apos;t use it.
+ It&apos;s obsolete.</para>
+ </footnote></para>
+ <para>This enables the command
+ <command>includegraphics</command> which is used to insert an
+ image in the document. The command is followed by the name of
+ your graphics file <emphasis>without the filetype</emphasis>,
+ for example: <literal>\includegraphics{myhouse}</literal>
+ (we&apos;ll see in a minute why you don&apos;t include the
+ filetype).</para>
+ <para>In most cases you should just make sure the image file is
+ in the same folder (directory) as the document you use it in.
+ This avoids a lot of messing around remembering where you put
+ the files. If you have images you want to use in several
+ different documents in different places on your disk, there is
+ a way to tell <LaTeX/> where to look (see <xref
+ linkend="graphicsdir"/>).</para>
+ <para>For standard <LaTeX/> with
+ <productname>dvips</productname>, graphics files
+ <emphasis>must</emphasis> be in <acronym id="EPS">Encapsulated
+ PostScript</acronym> format: this has been the publishing
+ industry standard for portable graphics for many years, and no
+ other format will work portably in standard <LaTeX/>.<footnote>
+ <para>Some distributions of <TeX/> systems allow other
+ formats to be used, such as <acronym ref="PNG"></acronym>,
+ <acronym id="BMP">Microsoft Bitmap</acronym> files,
+ Hewlett-Packard&apos;s <acronym id="PCL">Printer Control
+ Language</acronym> files, and others; but you cannot
+ send such documents to other <LaTeX/> users and expect
+ them to work if they don&apos;t have the same distribution
+ installed as you have. Stick to <acronym
+ ref="EPS"></acronym>.</para>
+ </footnote></para>
+ <para>All good graphics packages can save images as <acronym
+ ref="EPS"></acronym>, but be very careful because some
+ packages, especially on Microsoft Windows platforms, use a
+ very poor quality driver, which creates very poor quality
+ <acronym ref="EPS"></acronym> files. If in doubt, check with
+ an expert. If you find an <acronym ref="EPS"></acronym>
+ graphic doesn&apos;t print, the chances are it&apos;s been
+ badly made by the graphics software. Download Adobe&apos;s own
+ PostScript driver from their Web site instead.</para>
+ <para>For <productname>pdf<LaTeX/></productname>, graphics files
+ can be in <acronym id="PNG">Portable Network
+ Graphic</acronym>, <acronym id="JPG">Joint Photographic
+ Experts Group</acronym>, or <acronym ref="PDF"></acronym>
+ format, <emphasis>not</emphasis>&nbsp;<acronym
+ ref="EPS"></acronym>. This means if you want to use both
+ standard <LaTeX/> as well
+ as <productname>pdf<LaTeX/></productname>, you need to keep
+ your graphics in two formats, <acronym ref="EPS"></acronym>
+ and one of the others. This is why you don&apos;t include the
+ filetype in the filename you give with
+ <command>includegraphics</command>: <LaTeX/> will assume
+ <acronym ref="EPS"></acronym> and
+ <productname>pdf<LaTeX/></productname> will look for <acronym
+ ref="JPG"></acronym>, <acronym ref="PNG"></acronym> or
+ <acronym ref="PDF"></acronym> files matching the name.</para>
+ <para>The <command>includegraphics</command> command can take
+ optional arguments within square brackets before the filename
+ to specify either the height or width, and the other dimension
+ will automatically change to scale. If you specify both, the
+ image will be distorted to fit. You can scale an image by a
+ factor instead of specifying height or width; clip it to
+ specified coordinates; and rotate it in either direction.
+ Multiple optional arguments are separated with commas.</para>
+ <informalexample>
+ <programlisting>
+\begin{center}
+\includegraphics[width=3cm]{twithcat}
+\end{center}
+ </programlisting>
+ <graphic fileref="twithcat" format="PNG" width="3cm"
+ align="center"/>
+ </informalexample>
+ <para>For details of all the arguments, see the documentation on
+ the <methodname>graphicx</methodname> package or a copy of the
+ <citetitle ref="companion"></citetitle>. This package also
+ includes commands to <literallayout
+ remap="rotate">\raisebox{1ex}{\rotatebox{180}{rotate}}</literallayout>,
+ <literallayout
+ remap="mirror">\scalebox{-1}[1]{mirror}</literallayout>, and
+ <literallayout
+ remap="scale">\scalebox{2}[1]{scale}</literallayout> text.
+ <indexterm>
+ <primary>rotate</primary>
+ </indexterm><indexterm>
+ <primary>mirror</primary>
+ </indexterm><indexterm>
+ <primary>scale</primary>
+ </indexterm></para>
+ <para>It is in fact possible to tell <LaTeX/> to generate the
+ right file format by itself, but this requires an external
+ command-line graphics converter, and as it gets done afresh
+ each time, it slows things down rather a lot.</para>
+ <para><acronym ref="EPS"></acronym> files, especially bitmaps,
+ can be very large indeed, because they are stored in <acronym
+ ref="ASCII"></acronym> format.
+ <personname id="sw">
+ <firstname>Staszek</firstname>
+ <surname>Wawrykiewicz</surname>
+ </personname> has drawn my attention to a useful MS-DOS program to
+ overcome this, called <productname>cep</productname>
+ (<quote>Compressed Encapsulated Postscript</quote>) available
+ from <acronym ref="CTAN"></acronym> in the
+ <filename>support/pstools</filename> directory, which can
+ compress <acronym ref="EPS"></acronym> files to a fraction of
+ their original size. The original file can be replaced by the
+ new smaller version and still used directly with
+ <command>includegraphics</command>.</para>
+ <sect2 id="graphictypes">
+ <title>Making images</title>
+ <para>There are two types of image: bitmaps and
+ vectors.</para>
+ <variablelist>
+ <varlistentry>
+ <term>Bitmaps</term>
+ <listitem>
+ <para>Bitmap images are made of coloured dots, so if you
+ enlarge them, they go jagged at the edges, and if you
+ shrink them, they go blurry. Bitmaps are fine for
+ photographs, where every dot is a different colour,
+ and no-one will notice if you don&apos;t shrink or enlarge
+ too much. Bitmaps for diagrams and drawings, however,
+ are almost always the wrong choice, and
+ often disastrously bad.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Vectors</term>
+ <listitem>
+ <para>Vector drawings are made from instructions (eg
+ <quote>draw this from here to here, using a line this
+ thick</quote>). They can be enlarged or shrunk as
+ much as you like, and never lose accuracy, because
+ they <emphasis>get redrawn</emphasis> automatically at
+ any size. You can&apos;t do photographs as vectors, but
+ it&apos;s the only acceptable method for drawings or
+ diagrams.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>Vector graphic packages are also better suited for
+ saving your image directly in <acronym ref="EPS"></acronym>
+ or <acronym ref="PDF"></acronym> format (both of which use
+ vectors internally). All the major graphics-generating
+ packages in all disciplines output vector formats:
+ <productname>AutoCAD</productname>,
+ <productname>ChemDraw</productname>,
+ <productname>MathCAD</productname>,
+ <productname>Maple</productname>,
+ <productname>Mathematica</productname>,
+ <productname>ArcInfo</productname>, and so on. <acronym
+ ref="EPS"></acronym> is the universally-accepted format
+ for creating vector graphics for publication, with <acronym
+ ref="PDF"></acronym> a close second. Most of the major
+ graphics (drawing) packages can also save as <acronym
+ ref="EPS"></acronym>, such as
+ <productname>PhotoShop</productname>, <productname>PaintShop
+ Pro</productname>, Adobe
+ <productname>Illustrator</productname>, Corel
+ <productname>Draw</productname>, and
+ <productname>GIMP</productname>. There are also some free
+ vector plotting and diagramming packages available like
+ <productname>tkPaint</productname> and
+ <productname>GNUplot</productname> which do the same. Never,
+ ever (except in the direst necessity) save any
+ <emphasis>diagram</emphasis> as a bitmap.</para>
+ <figure>
+ <title>The diagram from <xref linkend="workeff"/> shrunk and
+ enlarged</title>
+ <graphic fileref="diagram" format="EPS" width="3.95cm"
+ remap="frame"/>
+ <graphic fileref="diagram" format="EPS" scale="2" remap="frame"
+ scalefit="250 250 300 300"/>
+ </figure>
+ <para>Bitmap formats like <acronym ref="JPG"></acronym> and
+ <acronym ref="PNG"></acronym> are ideal for photographs, as
+ they are also able to compress the data substantially
+ without too much loss of quality. However, compressed
+ formats are bad for screenshots, if you are documenting
+ computer tasks, because too much compression makes them
+ blurry. The popular <acronym id="GIF">Graphics Interchange
+ Format</acronym> is good for screenshots, but is not
+ supported by <TeX/>: use <acronym ref="PNG"></acronym>
+ instead, with the compression turned down to minimum. Avoid
+ uncompressible formats like <acronym ref="BMP"></acronym> as
+ they produce enormous and unmanageable files. The <acronym
+ id="TIFF">Tagged Image File Format</acronym>, popular with
+ graphic designers, should also be avoided because far too
+ many companies have designed and implemented non-standard,
+ conflicting, proprietary extensions to the format, making it
+ virtually useless for transfer between different types of
+ computers (except in faxes, where it&apos;s still used in a
+ much stricter version).</para>
+ <example>
+ <title>Adding pictures</title>
+ <para>Add <literal>\usepackage{graphicx}</literal> to the
+ preamble of your document, and copy or download an image
+ you want to include. Make sure it is a <acronym
+ ref="JPG"></acronym>, <acronym ref="PNG"></acronym>, or
+ <acronym ref="PDF"></acronym> image if you use
+ <productname>pdf<LaTeX/></productname>, or an <acronym
+ ref="EPS"></acronym> image if you use standard
+ <LaTeX/>.</para>
+ <para>Add <command>includegraphics</command> and the
+ filename in curly braces (without the filetype), and
+ process the document and preview or print it.</para>
+ <para>Make it into a figure following the example in <xref
+ linkend="figures"/>.</para>
+ <para>Be aware that some <acronym ref="DVI"></acronym>
+ previewers are not able to display all types of graphics,
+ and some cannot display colour. For best results, use
+ <acronym ref="PDF"></acronym> or
+ <trademark>PostScript</trademark> preview.</para>
+ </example>
+ </sect2>
+ <sect2 id="graphicsdir">
+ <title>Graphics storage</title>
+ <para>I mentioned earlier that there was a way to tell
+ <LaTeX/> where to look if you had stored images centrally
+ for use in many different documents. The answer is in a
+ command <command>graphicspath</command> which you supply
+ with an argument giving the name of an additional directory
+ path you want searched when a file uses the
+ <command>includegraphics</command> command, for
+ example:</para>
+ <programlisting>
+\graphicspath{c:\mypict~1\camera}
+\graphicspath{/var/lib/images}
+\graphicspath{HardDisk:Documents:Reports:Pictures}
+ </programlisting>
+ <para>I&apos;ve used the <wordasword>safe</wordasword>
+ (MS-DOS) form of the Windows <filename>My
+ Pictures</filename> folder because it&apos;s A Bad Idea to
+ use directory names containing spaces (see <xref
+ linkend="filenames"/>). Using
+ <command>graphicspath</command> does make your file less
+ portable, though, because file paths tend to be specific
+ both to an operating system and to your computer, like the
+ examples above.</para>
+ </sect2>
+ </sect1>
+ <sect1 id="verbatim">
+ <title>Verbatim text</title>
+ <indexterm>
+ <primary>verbatim text</primary>
+ </indexterm>
+ <para>If you are documenting computer procedures, you probably
+ need fixed-width type for examples of programming or data
+ input or output. Even if you are writing about completely
+ non-computer topics, you may often want to quote a <acronym
+ ref="URI"></acronym> or email address which needs to be
+ typeset specially. It is particularly important in these two
+ examples to avoid hyphenating them if they have to break over
+ a line-end, because the hyphen might be taken by the user as a
+ part of the address.</para>
+ <para>Standard <LaTeX/> includes two features for handling
+ fixed-format text, and there are many more available in
+ packages.</para>
+ <sect2 id="inlineverb">
+ <title>Inline verbatim</title>
+ <para>To specify a word or phrase as verbatim text in
+ typewriter type within a sentence, use the special command
+ <command>verb</command>, followed by your piece of text
+ surrounded by any suitable character which does
+ <emphasis>not</emphasis> occur in the text itself. This is a
+ very rare exception to the rule that arguments go in curly
+ braces. I often use the plus sign for this, for example to
+ show a <LaTeX/> command, I type
+ <literal
+ remap="`">\verb+\includegraphics[width=3in]{myhouse}+</literal>
+ in order to display
+ <literal>\includegraphics[width=3in]{myhouse}</literal>, but
+ sometimes I use the
+ <firstterm id="grave">grave accent</firstterm> (<firstterm
+ id="backtick">backtick</firstterm> or open-quote) or the
+ vertical bar when the phrase already has a plus sign in it,
+ like <literal remap='`'>\verb|\(y=a+2x^2\)|</literal> when
+ illustrating the <LaTeX/> equation
+ <literal remap="|">\(y=a+x^2\)</literal>.</para>
+ <para>This command has the advantage that it turns off all
+ special characters (see <xref linkend="specials"/>) except
+ the one you use as the delimiter, so you can easily quote
+ sequences of characters in any computer syntax without
+ problems. However, <LaTeX/> will never break the argument of
+ <command>verb</command> at a line-end when formatting a
+ paragraph, even if it contains spaces, so if it happens to
+ be long, and falls towards the end of a line, it will stick
+ out into the margin. See <xref linkend="hyph"/> for more
+ information on line-ends and hyphenation.</para>
+ <para>The <methodname>url</methodname> package avoids this by
+ providing the command <command>url</command> which works in
+ the same way as <command>verb</command>, with the argument
+ enclosed in a pair of characters, but performs a hyphenless
+ break at punctuation characters, as in <systemitem
+ remap="http://www.ucc.ie:8080/cocoon/cc/ docs/siteowner.xml"
+ class="resource">http://www.ucc.ie:8080/cocoon/cc/docs/siteowner.xml</systemitem>.
+ It was designed for Web <acronym
+ ref="URI"></acronym>s,<footnote>
+ <para>The original term <acronym id="URL">Uniform Resource
+ Locator</acronym> is now strongly deprecated in the Web
+ community in favour of the more accurate <acronym
+ id="URI">Uniform Resource Indicator</acronym>. For
+ details see <ulink
+ url="http://www.w3.org/Addressing/"></ulink>.
+ Unfortunately the older term still persists, especially
+ in <LaTeX/> and <acronym ref="XML"></acronym>
+ markup.</para>
+ </footnote> so it understands their syntax and will never
+ break mid-way through an unpunctuated word, only at slashes
+ and full points. Bear in mind, however, that spaces are
+ forbidden in <acronym ref="URI"></acronym>s, so using spaces
+ in <command>url</command> arguments will fail, as will using
+ other non-<acronym ref="URI"></acronym>-valid
+ characters.</para>
+ </sect2>
+ <sect2>
+ <title>Display verbatim</title>
+ <para>For longer (multiline) chunks of fixed-format text, use
+ the <modespec>verbatim</modespec> environment:</para>
+ <programlisting>
+\begin{verbatim}
+\documentclass[11pt,a4paper,oneside]{report}
+\begin{document}
+
+\title{Practical Typesetting}
+\author{Peter Flynn\\Silmaril Consultants}
+\date{December 2004}
+\maketitle
+
+\end{document}
+\end{verbatim}
+ </programlisting>
+ <para>Like <command>verb</command>, this turns off all special
+ characters, so you can include anything at all in the
+ verbatim text except the exact line
+ <literal>\end{verbatim}</literal></para>
+ <para>For more control over formatting, however, I recommend
+ the use of the <methodname>fancyvrb</methodname> package,
+ which provides a <modespec>Verbatim</modespec> environment
+ (note the capital letter) which lets you draw a rule round
+ the verbatim text, change the font size, and even have
+ typographic effects inside the <modespec>Verbatim</modespec>
+ environment. It can also be used in conjunction with the
+ <methodname>fancybox</methodname> package (see <xref
+ linkend="fancybox"/>), and it can add reference line numbers
+ (useful for chunks of data or programming), and it can even
+ include entire external files.</para>
+ <example>
+ <title>Try some fixed-format text</title>
+ <para>Add your email address and home page <acronym
+ ref="URI"></acronym> using the <command>verb</command>
+ and <command>url</command> commands. You&apos;ll need to
+ <literal>\usepackage{url}</literal> for the latter.</para>
+ <para>If you know some programming, try a few lines enclosed
+ in <modespec>verbatim</modespec> and
+ <modespec>Verbatim</modespec> environments.</para>
+ </example>
+ </sect2>
+ </sect1>
+ <sect1 id="boxes">
+ <title>Boxes, sidebars, and panels</title>
+ <indexterm><primary>boxes</primary></indexterm>
+ <indexterm><primary>sidebars</primary></indexterm>
+ <indexterm><primary>panels</primary></indexterm>
+ <para><LaTeX/>, like most typesetting systems, works by setting
+ text into boxes. The default box is the width of the current
+ page, and works like an old compositor&apos;s galley (tray)
+ from the days of metal type: it accumulates typeset text until
+ it&apos;s a bit longer than the specified page height. At this
+ stage <LaTeX/> works out how much of it really will fit on a
+ page, snips it off and ships it out to the <acronym
+ ref="DVI"></acronym> or <acronym ref="PDF"></acronym> file,
+ and puts the rest back into the galley to accumulate towards
+ the following page.</para>
+ <sect2 id="boxtext">
+ <title>Boxes of text</title>
+ <para>Because of this <wordasword>box</wordasword> model,
+ <LaTeX/> can typeset any text into a box of any width
+ wherever on the page you need it.</para>
+ <para>The simplest command for small amounts of text is
+ <command>parbox</command>. This command needs two arguments
+ in curly braces: the first is the width you want the text
+ set to, and the second is the text itself, for
+ example:</para>
+ <informalexample>
+ <programlisting>
+\parbox{1in}{Please make sure you send in your
+ completed forms by January 1st
+ next year, or the penalty clause
+ 2(a) will apply}
+ </programlisting>
+ <informaltable>
+ <tgroup cols="1">
+ <colspec colwidth="1in" align="justify"/>
+ <tbody>
+ <row>
+ <entry>Please make sure you send in your completed
+ forms by January 1st next year, or the penalty
+ clause 2(a) will apply</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </informalexample>
+ <para>The text is typeset to the required width, and the box
+ is extended downwards for as long as is required to fit the
+ text. Note that the baseline of a <command>parbox</command>
+ is set to the midpoint of the box; that is, if you include a
+ <command>parbox</command> in mid-sentence, the centre of the
+ box will be lined up with the line of type currently being
+ set.<caution remap="parbox1" colwidth="1cm">
+ <para><format fontstep="scriptsize" paragraph="yes">Like
+ this small paragraph.</format></para>
+ </caution> You can specify that it should be the top or
+ bottom by adding an optional <option>t</option> or
+ <option>b</option> in square brackets before the width. For
+ example,
+ <literal>\parbox[t]{1in}{...}</literal> will produce
+ <caution colwidth="1in" role="top" remap="parbox2">
+ <para>a box with the baseline aligned with the top line of
+ the text in the box.</para>
+ </caution></para>
+ <para>Notice that when setting very narrow measures with type
+ that is too large, the spacing may become uneven and there
+ may be too much hyphenation. Either use
+ <command>raggedright</command> or reduce the type size, or
+ (in extreme cases) reword the text or break each line by
+ hand. It is rare for <LaTeX/> to need this: the example above
+ was deliberately chosen to be obtuse as an
+ illustration.</para>
+ <para>Where the contents is more extensive or more
+ complicated, you can use the <modespec>minipage</modespec>
+ environment.</para>
+ <para>Within this you can use virtually everything
+ that occurs in normal text (&eg;&nbsp;lists, paragraphs,
+ tabulations, &etc;)&nbsp;with the exception of floats like
+ tables and figures. The <modespec>minipage</modespec>
+ environment has an argument just like
+ <command>parbox</command> does, and it means the same: the
+ width you want the text set to.</para>
+ <para>Note that in <modespec>minipage</modespec>s and
+ <command>parbox</command>es, the paragraph indentation
+ (<varname role="dimension">parindent</varname>) is
+ reset to zero. If you need to change it, set it inside the
+ <modespec>minipage</modespec> or <command>parbox</command>
+ using the <command>setlength</command> command (see <xref
+ linkend="paragraphs"/>).</para>
+ <informalexample>
+ <programlisting>
+\begin{minipage}{3in}
+Please make sure you send in your completed
+forms by January 1st next year, or the
+penalty clause 2(a) will apply.
+\begin{itemize}
+\item Incomplete forms will be returned to
+you unprocessed.
+\item Forms must be accompanied by the
+correct fee.
+\item There is no appeal. The adjudicators'
+decision is final.
+\end{itemize}
+\end{minipage}
+ </programlisting>
+ <informaltable>
+ <tgroup cols="1">
+ <colspec colwidth="3in" align="justify"/>
+ <tbody>
+ <row>
+ <entry><para>Please make sure you send in your
+ completed forms by January 1st next year, or the
+ penalty clause 2(a) will
+ apply.</para><itemizedlist>
+ <listitem>
+ <para>Incomplete forms will be returned to you
+ unprocessed.</para>
+ </listitem>
+ <listitem>
+ <para>Forms must be accompanied by the correct
+ fee.</para>
+ </listitem>
+ <listitem>
+ <para>There is no appeal. The
+ adjudicators&apos; decision is final.</para>
+ </listitem>
+ </itemizedlist></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </informalexample>
+ <para>There are two other ways of typesetting text to widths
+ other than the normal text width: you can use a one-row,
+ one-cell <modespec>tabular</modespec> environment with the
+ <systemitem>p</systemitem> column type specification, or you
+ can use the <command>vbox</command> command, which is raw
+ <TeX/>, and outside the scope of this document.</para>
+ </sect2>
+ <sect2 id="fbox">
+ <title>Framed boxes</title>
+ <para>To put a frame round <literallayout remap="fbox"
+ width="64">\fbox{some text}</literallayout>, use the
+ <command>fbox</command> command:
+ <literal>\fbox{some text}</literal>. This works for a few
+ words in mid-line, but the framed box and its contents
+ won&apos;t break over the end of a line. To typeset
+ multiline text in a box, put it in a
+ <command>parbox</command>, or use a
+ <modespec>minipage</modespec> or
+ <modespec>tabular</modespec> environment as described above,
+ and enclose the whole thing in a
+ <command>fbox</command>.</para>
+ <informalexample>
+ <programlisting>
+\fbox{\begin{minipage}{3in}
+This multiline text is more flexible than
+a tabular setting:
+\begin{itemize}
+\item it can contain any type of normal
+<LaTeX/> typesetting;
+\item it can be any specified width;
+\item it can even have its own
+footnotes\footnote{Like this}.
+\end{itemize}
+\end{minipage}}
+ </programlisting>
+ <calloutlist id="mp" remap="\setlength{\fboxrule}{1pt}">
+ <callout arearefs="mp" remap="3in">
+ <para>This multiline text is more flexible than a
+ tabular setting:</para><itemizedlist>
+ <listitem>
+ <para>it can contain any type of normal <LaTeX/>
+ typesetting;</para>
+ </listitem>
+ <listitem>
+ <para>it can be any specified width;</para>
+ </listitem>
+ <listitem>
+ <para>it can even have its own footnotes.<footnote>
+ <para>Like this.</para>
+ </footnote></para>
+ </listitem>
+ </itemizedlist>
+ </callout>
+ </calloutlist>
+ </informalexample>
+ <para>The spacing between text and box is controlled by the
+ value of <varname role="dimension">fboxsep</varname>, and
+ the thickness of the line by <varname
+ role="dimension">fboxrule</varname>. The following values
+ were used above:</para>
+ <programlisting>
+\setlength{\fboxsep}{1em}
+\setlength{\fboxrule}{2pt}
+ </programlisting>
+ <para>As we saw before, setting justified text in narrow
+ measures will produce poor spacing: either use the
+ <command>raggedright</command> command, or change the font
+ size, or add explicit extra hyphenation points.</para>
+ <para>Note the <literal>\begin{tabular}</literal> and
+ <literal>\begin{minipage}</literal> commands still need the
+ width specifying: in the case of the
+ <literal>\begin{tabular}</literal> by the use of the
+ <literal>p</literal> column type with its width
+ specification, and in the case of
+ <literal>\begin{minipage}</literal> by the second
+ argument.</para>
+ <informalexample>
+ <programlisting>
+\fbox{\begin{tabular}{p{1in}}
+Multiline text in a box typeset using
+\textsf{tabular}
+\end{tabular}}
+ </programlisting>
+ <informaltable frame="all" colsep="6pt">
+ <tgroup cols="1">
+ <colspec colwidth="1in" align="justify"/>
+ <tbody>
+ <row>
+ <entry>Multiline text in a box typeset using
+ <methodname>tabular</methodname></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </informalexample>
+ </sect2>
+ <sect2 id="fancybox">
+ <title>Sidebars and panels</title>
+ <para>The <methodname>fancybox</methodname> package lets you
+ extend the principle of <command>fbox</command> with
+ commands to surround text in square, oval (round-cornered),
+ and drop-shadow boxes (&eg; <command>ovalbox</command>,
+ <command>shadowbox</command>, &etc;: see the documentation
+ for details).</para>
+ <para>You can create panels of any size with these borders by
+ using the <modespec>minipage</modespec> environment to
+ typeset the text inside a special <modespec>Sbox</modespec>
+ environment which <methodname>fancybox</methodname> defines.
+ The <modespec>minipage</modespec> formats the text but the
+ <modespec>Sbox</modespec>&nbsp;<wordasword>captures</wordasword>
+ it, allowing you to put the frame round it as it
+ prints.</para>
+ <para>The printed version of this document uses this extensively and
+ there is a useful example shown in <xref
+ linkend="macenv"/>.</para>
+ </sect2>
+ </sect1>
+ </chapter>
+ <chapter id="texttools">
+ <title>Textual tools</title>
+ <indexterm><primary>tools</primary></indexterm>
+ <para>Every text-handling system needs to support a repertoire of
+ tools for doing things with text. <LaTeX/> implements many
+ dozens, of which a small selection of the most frequently used
+ is given here:</para>
+ <itemizedlist>
+ <listitem>
+ <para>offset quotations (sometimes called <wordasword>block
+ quotes</wordasword>);</para>
+ </listitem>
+ <listitem>
+ <para>footnotes and end-notes;</para>
+ </listitem>
+ <listitem>
+ <para>marginal notes;</para>
+ </listitem>
+ <listitem>
+ <para>cross-references, both normal ones and bibliographic
+ citations;</para>
+ </listitem>
+ <listitem>
+ <para>indexes and glossaries;</para>
+ </listitem>
+ <listitem>
+ <para>typesetting in multiple columns.</para>
+ </listitem>
+ </itemizedlist>
+ <sect1 id="quotations">
+ <title>Quotations</title>
+ <para>Direct speech and short quotes within a sentence
+ <wordasword>like this</wordasword> are done with simple
+ quotation marks as described in <xref
+ linkend="quotes"/>. Sometimes, however, you may want longer
+ quotations set as a separate paragraph. Typically these are
+ indented from the surrounding text. <LaTeX/> has two
+ environments for doing this.</para>
+ <para>Such quotations are often set in a smaller size of type,
+ although this is not the default, hence the use of the
+ <command>small</command> command in the second example. The
+ inclusion of the bibliographic citation at the end is
+ optional: here it is done with a non-standard command
+ <command>citequote</command> which I invented for this example
+ (there is more about how to do things like this in <xref
+ linkend="macros"/>).</para>
+ <variablelist>
+ <varlistentry>
+ <term>The <format
+ fontseries="m"><methodname>quote</methodname></format>
+ environment</term>
+ <listitem>
+ <para>is for up to a line of text each per (short)
+ quotation, with the whole thing indented from the
+ previous paragraph but with no additional indentation on
+ each quote;</para>
+ <informalexample>
+ <programlisting>
+
+\begin{quote}
+Do, Ronny, Do. \textit{Nancy Reagan}
+
+Da Do Ron Ron. \textit{The Crystals}
+\end{quote}
+ </programlisting>
+ <para>Do, Ronny, Do. <format fontshape="it">Nancy
+ Reagan</format></para>
+ <para>Da Do Ron Ron. <format fontshape="it">The
+ Crystals</format></para>
+ </informalexample>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>The <format
+ fontseries="m"><methodname>quotation</methodname></format>
+ environment</term>
+ <listitem>
+ <para>is for longer passages (a paragraph or more) of a
+ single quotation, where not only is the block of text
+ indented, but each paragraph of it also has its own
+ extra indentation on the first line.</para>
+ <informalexample>
+ <programlisting>
+\begin{quotation}\small
+At the turn of the century William Davy,
+a Devonshire parson, finding errors in
+the first edition of his \titleof{davy},
+asked for a new edition to be printed.
+His publisher refused and Davy purchased
+a press, type, and paper. He harnessed
+his gardener to the press and apprenticed
+his housemaid to the typesetting. After
+twelve years&apos; work, a new edition
+of fourteen sets of twenty-six volumes
+was issued---which surely indicates that,
+when typomania is coupled with religious
+fervour, anything up to a miracle may be
+achieved.\citequote[p.76]{ryder}
+\end{quotation}
+ </programlisting>
+ <blockquote citedoc="ryder" citedetail="p.76">
+ <para>At the turn of the century William Davy, a
+ Devonshire parson, finding errors in the first
+ edition of his <citetitle ref="davy"></citetitle>,
+ asked for a new edition to be printed. His publisher
+ refused and Davy purchased a press, type, and paper.
+ He harnessed his gardener to the press and
+ apprenticed his housemaid to the typesetting. After
+ twelve years&apos; work, a new edition of fourteen
+ sets of twenty-six volumes was issued---which surely
+ indicates that, when typomania is coupled with
+ religious fervour, anything up to a miracle may be
+ achieved.</para>
+ </blockquote>
+ </informalexample>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+<!-- not yet there isn't: needs an example of reprogramming jurabib -->
+ </sect1>
+ <sect1 id="footnotes">
+ <title>Footnotes and end-notes</title>
+ <indexterm>
+ <primary>footnotes</primary>
+ </indexterm>
+ <para>The command <command>footnote</command>, followed by the
+ text of the footnote in curly braces, will produce an
+ auto-numbered footnote with a raised small number where you
+ put the command, and the numbered text automatically printed
+ at the foot of the page.<footnote>
+ <para>Like this.</para>
+ </footnote> The number is reset to&nbsp;1 at the start of each
+ chapter (but you can override that and make them run
+ continuously throughout the document, or even restart at&nbsp;1 on
+ each page or section).</para>
+ <para><LaTeX/> automatically creates room for the footnote, and
+ automatically reformats it if you change your document in such
+ a way that the point of attachment and the footnote would move
+ to the next (or preceding) page.</para>
+ <para>Because of the way <LaTeX/> reads the whole footnote before
+ doing anything with it, you can&apos;t use
+ <command>verb</command> (<xref linkend="inlineverb"/>) alone
+ in footnotes: either precede it with
+ <command>protect</command> or use [abuse?] the
+ <command>url</command> command instead, which you should be
+ using for Web and email addresses in any case).</para>
+ <para>Footnotes inside minipages (see <xref
+ linkend="boxes"/>) produce lettered notes instead of
+ numbered ones, and they get printed at the bottom of the
+ minipage, <emphasis>not</emphasis> the bottom of the physical
+ page (but this too can be changed).</para>
+ <para>There is a package to hold over your footnotes and make
+ them print at the end of the chapter instead
+ (<methodname>endnote</methodname>) or at the end of the whole
+ document, and there is a package to print many short footnotes
+ in a single footnoted paragraph so they take up less space
+ (<methodname>fnpara</methodname>). It is also possible to have
+ several separate series of footnotes active simultaneously,
+ which is useful in critical editions or commentaries: a
+ numbered series may be used to refer to an original
+ author&apos;s notes; a lettered series can be used for notes
+ by a commentator or authority; and a third series is available
+ for your own notes. It is also possible to format footnotes
+ within footnotes.</para>
+ <para>If your footnotes are few and far between, you may want to
+ use footnote symbols instead of numbers. You can do this by
+ redefining the output of the footnote counter to be the
+ <command>fnsymbol</command> command:</para>
+ <programlisting>
+\renewcommand{\thefootnote{\fnsymbol{footnote}}
+ </programlisting>
+ <para>There are also ways to refer more than once to the
+ same footnote, and to defer the positioning of the footnote if
+ it occurs in a float like a Table or Figure, where it might
+ otherwise need to move to a different page.</para>
+ </sect1>
+ <sect1 id="marginals">
+ <title>Marginal notes</title>
+ <indexterm>
+ <primary>marginal notes</primary>
+ </indexterm>
+ <para>You can add marginal notes to your text<note
+ role="marginal"><para>Like this.</para></note> instead of
+ (or as well as) footnotes. You need to make sure that you have
+ a wide-enough margin, of course: use the
+ <methodname>geometry</methodname> package (see <xref
+ linkend="colorpkg"/>) to allocate enough space, otherwise
+ the notes will be too cramped. There are several packages to
+ help with formatting marginal notes, but the simplest way is
+ to define it yourself. Add this new command to your
+ preamble:</para>
+ <programlisting>
+\newcommand{\marginal}[1]{%
+ \leavevmode\marginpar{\tiny\raggedright#1\par}}
+ </programlisting>
+ <para>Then you can use <literal>\marginal{Some
+ text}</literal><note
+ role="marginal"><para>Some text where you need
+ it.</para></note> Be careful, however, because marginal
+ notes are aligned with the line where the command starts, so a
+ very long one followed too closely by another will cause
+ <LaTeX/> to try and
+ adjust the position so they don&apos;t overlap.</para>
+ <para>We&apos;re jumping ahead a bit here, as we haven&apos;t
+ covered how to define your own commands yet. I won&apos;t even
+ try to explain it here, although the attentive reader can
+ probably deduce some of it by inspection. See <xref
+ linkend="macros"/> for more information about making up your
+ own commands.</para>
+ </sect1>
+ <sect1 id="xrefs">
+ <title>Cross-references</title>
+ <indexterm>
+ <primary>cross-references</primary>
+ </indexterm>
+ <para>This is one of the most powerful features of <LaTeX/>. You
+ can label any point in a document with a name you make up, and
+ then refer to it by that name from anywhere else in the
+ document, and <LaTeX/> will always work out the cross-reference
+ number for you, no matter how much you edit the text or move
+ it around.</para>
+ <para>A similar method is used to cite documents in a
+ bibliography or list of references, and there are packages to
+ sort and format these in the correct manner for different
+ journals.</para>
+ <sect2 id="normalxref">
+ <title>Normal cross-references</title>
+ <para>You label a place in your document by using the command
+ <command>label</command> followed by a short name you make
+ up, in curly braces:<footnote>
+ <para>This section is labelled
+ <wordasword><systemitem>normalxref</systemitem></wordasword>,
+ for example.</para>
+ </footnote> we&apos;ve already seen this done for labelling
+ Figures and Tables.</para>
+ <programlisting>
+\section{New Research}
+\label{newstuff}
+ </programlisting>
+ <para>You can then refer to this point from anywhere in the
+ same document with the command <command>ref</command>
+ followed by the name you used, &eg;</para>
+ <informalexample>
+ <programlisting>
+In \S~\ref{newstuff} there is a list of recent
+projects.
+ </programlisting>
+ <para>In <xref xreflabel="&#x000A7;" linkend="normalxref"/>
+ there is a list of recent projects.</para>
+ </informalexample>
+ <para>(The <command>S</command> command produces a section
+ sign (<literallayout role="&#x000A7;">\S</literallayout>) and the
+ <command>P</command> command produces a paragraph sign
+ (<literallayout role="&#x000B6;">\P</literallayout>).)</para>
+ <para>If the label is in normal text, the reference will
+ provide the current chapter or section number or both
+ (depending on the current document
+ class).<footnote><para>Thus I can
+ refer here to
+ <literal>\ref{normalxref}</literal> and get the
+ value&nbsp;<xref
+ linkend="normalxref"/>.</para></footnote> If the label
+ was inside a Table or Figure, the reference provides the
+ Table number or Figure number prefixed by the chapter
+ number. A label in an enumerated list will provide a
+ reference to the item number. If there is no apparent
+ structure to this part of the document, the reference will
+ be null. Labels must be unique (that is, each value must
+ occur only <emphasis>once</emphasis> as a label within a
+ single document), but you can have as many references to
+ them as you like.</para>
+ <para>Note the use of the unbreakable space
+ (<literal>~</literal>) between the <command>ref</command>
+ and the word before it. This prints a space but prevents the
+ line ever breaking at that point, should it fall close to
+ the end of a line.</para>
+ <para>The command <command>pageref</command> followed by any
+ of your label values will provide the page number where the
+ label occurred, regardless of the document structure. This
+ makes it possible to refer to something by page number as
+ well as its <command>ref</command> number, which is useful
+ to readers in very long documents.</para>
+ <note>
+ <para><LaTeX/> records the label values each time the
+ document is processed, but updated values only get used
+ the <emphasis>next</emphasis> time the document is
+ processed. You always need to process the document an
+ extra time before printing or viewing, if you have changed
+ or added references, to make sure the values are correctly
+ resolved.</para>
+ </note>
+ <para>Unresolved references are printed as two question
+ marks, and also cause a warning message at the end of the
+ log file. There&apos;s never any harm in having
+ <command>label</command>s you don&apos;t refer to, but using
+ <command>ref</command> when you don&apos;t have a matching
+ <command>label</command> is an error.</para>
+ </sect2>
+ <sect2 id="bib">
+ <title>Bibliographic references</title>
+ <indexterm>
+ <primary>bibliographies</primary>
+ </indexterm><indexterm>
+ <primary>references</primary>
+ </indexterm>
+ <para>The mechanism used for references to reading lists and
+ bibliographies is almost identical to that used for normal
+ cross-references. Although it is possible to type the
+ details of each citation manually, there is a companion
+ program to <LaTeX/> called <BibTeX/>, which manages
+ bibliographic references automatically. This reduces the time
+ needed to maintain and format them, and dramatically
+ improves accuracy. Using <BibTeX/> means you only ever have
+ to type the bibliographic details of a work once. You can
+ then cite it in any document you write, and it will get
+ formatted automatically to the style you specify.</para>
+ <sect3 id="citation">
+ <title>Citing references</title>
+ <para><BibTeX/> works exactly the same way as other
+ bibliographic databases: you keep details of every
+ document you want to refer to in a separate file, using
+ <BibTeX/>&apos;s own format (see example below). Many
+ writers make a habit of adding the details of every book
+ and article they read, so that when they write a document,
+ these entries are always available for reference. You give
+ each entry a short label, just like you do with normal
+ cross-references (see <xref linkend="normalxref"/>), and
+ it is this label you use to refer to in your own documents
+ when you cite the work using the <command>cite</command>
+ command:</para>
+ <programlisting>
+...as has clearly been shown by Fothergill~\cite{fg}.
+ </programlisting>
+ <para>By default, this creates a cross-reference number in
+ square brackets&nbsp;[1] which is a common style in the
+ Natural Sciences (see <xref linkend="othercite"/> for
+ details of how to change this). There are dozens of
+ alternative citation formats in extra packages, including
+ the popular author/year format:</para>
+ <informalexample>
+ <programlisting>
+...as has clearly been shown
+by~\citeauthoryear{fg}.
+ </programlisting>
+ <para>&hellip;as has clearly been shown by&nbsp;<citetitle
+ ref="fg" show="both"></citetitle>.</para>
+ </informalexample>
+ <para>Note that in this case you don&apos;t type the
+ author&apos;s name because it is automatically extracted
+ by <BibTeX/>. There are lots of variants on this technique
+ in many packages, allowing you to phrase your sentences
+ with references in as natural a way as possible, and rely
+ on <BibTeX/> to insert the right data. (If you examine the
+ source of this document you&apos;ll find I use some
+ homebrew commands like <command>authorof</command> and
+ <command>titleof</command> which I use for a similar
+ purpose.)</para>
+ <para>To print the bibliographic listing (usually called
+ <wordasword>References</wordasword> in articles and
+ <wordasword>Bibliography</wordasword> in books and
+ reports), add these two lines towards the end of your
+ document, or wherever you want it printed, substituting
+ the name of your own <BibTeX/> file and the name of your
+ chosen bibliography style:</para>
+ <programlisting>
+\bibliographystyle{ieeetr}
+\bibliography{mybib}
+ </programlisting>
+ <itemizedlist>
+ <listitem>
+ <para>The <command>bibliography</command> command is
+ followed by the filename of your <BibTeX/> file
+ <emphasis>without</emphasis> the
+ <filename>.bib</filename> extension.</para>
+ </listitem>
+ <listitem>
+ <para>The <command>bibliographystyle</command> command
+ is followed by the name of any of <LaTeX/>&apos;s
+ supported bibliography styles, of which there are many
+ dozens available from <acronym
+ ref="CTAN"></acronym>.<footnote><para>The style
+ shown in the example here provides formatting
+ according to the specifications for Transactions
+ of the IEEE (revised).</para></footnote></para>
+ </listitem>
+ </itemizedlist>
+ <para>The styles <option>plain</option> and
+ <option>alpha</option> are two common generic styles used
+ for drafts. The example above uses <acronym
+ id="IEEETR">Transactions of the Institute of Electrical
+ and Electronics Engineers</acronym>.</para>
+ </sect3>
+ <sect3 id="bibtex">
+ <title>Running <productname>bibtex</productname></title>
+ <para>When you run the <productname>bibtex</productname>
+ program, the details of every document you have cited will
+ be extracted from your database, formatted according to
+ the style you specify, and stored in a temporary
+ bibliographic (<filename>.bbl</filename>) file with a
+ label corresponding to the one you used in your citation,
+ ready for <LaTeX/> to use. This is entirely automatic: all
+ you do is cite your references in your <LaTeX/> document
+ using the labels you gave the entries in your <BibTeX/>
+ file, and run the <productname>bibtex</productname>
+ program.</para>
+ <para>After processing your file with <LaTeX/>, run
+ <BibTeX/> on it by clicking on the
+ <guiicon><BibTeX/></guiicon> toolbar icon (if your editor
+ has one), or use the
+ <guimenu>TeX</guimenu><guimenuitem>BibTeX
+ File</guimenuitem> menu entry, or type the command
+ <literal>bibtex</literal> followed by the name of your
+ document (without the <filename>.tex</filename>
+ extension). When you run <LaTeX/> again it will use the
+ <filename>.bbl</filename> file which <BibTeX/> created,
+ and subsequent runs of <LaTeX/> will format the correct
+ citation numbers (or author/year, or whatever format you
+ are using).</para>
+ <programlisting>
+$ latex mybook
+$ bibtex mybook
+$ latex mybook
+$ latex mybook
+ </programlisting>
+ <para>Because of this three-stage process, you always get a
+ warning message about an <wordasword>unresolved
+ reference</wordasword> the first time you add a new
+ reference to a previously uncited work. This will
+ disappear after subsequent runs of
+ <productname>bibtex</productname> and <LaTeX/>.</para>
+ <para>In practice, authors tend to run <LaTeX/> from time to
+ time during writing anyway, so they can preview the
+ document. Just run <BibTeX/> after adding a new
+ <command>cite</command> command, and subsequent runs of
+ <LaTeX/> will incrementally incorporate all references
+ without you having to worry about it. You only need to
+ follow the full formal sequence (<LaTeX/>, <BibTeX/>,
+ <LaTeX/>, <LaTeX/>) when you have finished writing and
+ want to ensure that all references have been
+ resolved.</para>
+ </sect3>
+ <sect3 id="bibspec">
+ <title><BibTeX/> format</title>
+ <para>The format for the <BibTeX/> file is specified in the
+ <BibTeX/> documentation (see <xref linkend="packagedoc"/>
+ for how to find and print it). You create a file with a
+ name ending in <filename>.bib</filename>, and add your
+ entries, for example:</para>
+ <programlisting>
+@book{fg,
+ title = {{An Innkeeper's Diary}},
+ author = {John Fothergill},
+ edition = {3rd},
+ publisher = {Penguin},
+ year = 1929,
+ address = {London}
+}
+ </programlisting>
+ <para>There is a prescribed set of fields for each of a
+ dozen or so types of document: book, article (in a
+ journal), article (in a collection), chapter (in a book),
+ thesis, report, paper (in a Proceedings), &etc; Each entry
+ identifies the document type after the
+ <wordasword><literal>@</literal></wordasword> sign,
+ followed by the entry label that you make up, and then
+ each field (in any order), using the format:</para>
+ <programlisting>
+keyword = {value},
+ </programlisting>
+ <para>Most <TeX/>-sensitive editors have a <BibTeX/> mode
+ which understands these entries.
+ <productname>Emacs</productname> automatically uses its
+ <filename>bibtex-mode</filename> whenever you open a
+ filename ending in <filename>.bib</filename>. When editing
+ <BibTeX/> databases, the rules are simple:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Omit the comma after the last field in the entry
+ (only&mdash;eg after <literal>{London}</literal> in
+ the example).</para>
+ </listitem>
+ <listitem>
+ <para>Titles may have their case changed in some styles:
+ to prevent this, enclose the title in double curly
+ braces as in the example.</para>
+ </listitem>
+ <listitem>
+ <para>Values which are purely numeric (&eg;&nbsp;years)
+ may omit the curly braces.</para>
+ </listitem>
+ <listitem>
+ <para>Fields can occur in any order but the format must
+ otherwise be strictly observed.</para>
+ </listitem>
+ <listitem>
+ <para>Fields which are not used do not have to be
+ included (so if your editor automatically inserts them
+ as blank or prefixed by <literal>OPT</literal>
+ [optional], you can safely delete them as unused
+ lines).</para>
+ </listitem>
+ </itemizedlist>
+ <para>To help with this, there are several interfaces to
+ creating and maintaining <BibTeX/> files, such as
+ <productname>tkbibtex</productname> (see <xref
+ linkend="tkbibtex"/>), or
+ <productname>pybliographic</productname>.</para>
+ <figure id="tkbibtex">
+ <title>tk<BibTeX/>, one of several graphical interfaces to
+ <BibTeX/> databases</title>
+ <graphic fileref="tkbibtex" width="75%"/>
+ </figure>
+ </sect3>
+ <sect3 id="bibstyle">
+ <title>Changing the layout</title>
+ <para>To change the title printed over the reference
+ listing, just change the value of
+ <command>refname</command> (articles) or
+ <command>bibname</command> (books and reports) by adding a
+ line like this in your preamble:</para>
+ <programlisting>
+\renewcommand{\bibname}{Reading List}
+ </programlisting>
+ <para>The formatting specifications (<BibTeX/> styles) are
+ based on standard settings for journals and books from
+ dozens of publishers: you just pick the one you want by
+ name. The <filename>texmf/bib/bst</filename> subdirectory
+ of your installation contains the ones installed by
+ default, and you can search on <acronym ref="CTAN"></acronym>
+ for others (look for <filename>.bst</filename> files).
+ Many of them are named after university press styles
+ (&eg; <productname>harvard</productname>,
+ <productname>oxford</productname>) or the publisher or
+ journal which specified them (&eg;
+ <productname>elsevier</productname>,
+ <productname>kluwer</productname>, &etc;).</para>
+ <para>Some of them have an accompanying package
+ (<filename>.sty</filename>) file which
+ you need to include with the normal
+ <command>usepackage</command> command in your preamble. In
+ this case the format may be distributed as
+ <filename>.dtx</filename> and <filename>.ins</filename>
+ files and will need installing in the same way as any
+ other package (see <xref linkend="pkginst"/>). Always read
+ the documentation, because most of the formats are very
+ specific to the journal they were designed for, and may have
+ fairly absolute requirements.</para>
+ <warning>
+ <para>If you are writing for a specific publisher, you
+ should remember that the rules or formats are laid down
+ by the typographic designer of that journal or
+ publisher: you cannot arbitrarily change the format just
+ because you don&apos;t happen to like it: it&apos;s not
+ your choice!</para>
+ </warning>
+ <para>It is also possible to write your own <BibTeX/>
+ (<filename>.bst</filename>) style files, although it uses
+ a language of its own which really needs a computer
+ science background to understand. However, this is
+ rendered unnecessary in most cases: there is an extensive
+ program (actually written in <LaTeX/>) called
+ <productname>makebst</productname>, which makes
+ <filename>.bst</filename> files by asking you a (long)
+ series of questions about exactly how you want your
+ citations formatted. Just type
+ <literal>latex makebst</literal> in a command window, but
+ give it a dummy run first, because some of the questions
+ are very detailed, so you need to have thought through how
+ you want your citations to appear before you start.</para>
+ </sect3>
+ <sect3 id="othercite">
+ <title>Other modes of citation</title>
+ <para>The method of citing a work by numeric reference is
+ common in the Natural Sciences but is not used in Law or
+ the Humanities. In these fields, citations are usually
+ done with short references (author/short-title/year) in a
+ numbered footnote. Sometimes they are actually called
+ <wordasword>footnotes</wordasword> to the exclusion of
+ ordinary footnotes, although they are really citations
+ which happen by convention to be
+ <emphasis>displayed</emphasis> as footnotes: an important
+ distinction rarely appreciated by authors until they come
+ to need a normal footnote.</para>
+ <para>For these fields, the bibliography at the back of the
+ document is printed <emphasis>unnumbered</emphasis> in
+ alphabetic order of author, or perhaps chronologically if
+ the time-frame is very large. This unnumbered format is
+ why it is conventionally called
+ <wordasword>References</wordasword> rather than
+ <wordasword>Bibliography</wordasword>: a sufficient working
+ citation has already been provided in the footnote, and
+ the list at the back is for reference purposes only;
+ whereas in the Natural Sciences, the citation is just a
+ number, or possibly an author and year only, so the full
+ listing is called a Bibliography.</para>
+ <para>The <methodname>jurabib</methodname> package
+ (originally intended for German law articles but now
+ extended to other fields in the Humanities, and to other
+ languages) has extensive features for doing this style of
+ citation and is strongly recommended.</para>
+ </sect3>
+ </sect2>
+ </sect1>
+ <sect1 id="indexes">
+ <title>Indexes and glossaries</title>
+ <indexterm>
+ <primary>indexes</primary>
+ </indexterm><indexterm>
+ <primary>glossaries</primary>
+ </indexterm>
+ <para><LaTeX/> has a powerful, automated indexing facility which
+ uses the standard <productname>makeindex</productname>
+ program. To use indexing, use the package
+ <methodname>makeidx</methodname> and include the
+ <command>makeindex</command> command in your preamble:</para>
+ <programlisting>
+\usepackage{makeidx}
+\makeindex
+ </programlisting>
+ <para>When you want to index something, using the command
+ <command>index</command> followed by the entry in curly
+ braces, as you want it to appear in the index, using one of
+ the following formats:</para>
+ <variablelist>
+ <varlistentry>
+ <term>Plain entry</term>
+ <listitem>
+ <para>Typing <literal>\index{beer}</literal> will create
+ an entry for <wordasword>beer</wordasword> with the
+ current page
+ number.<indexterm><primary>beer</primary></indexterm></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Subindex entry</term>
+ <listitem>
+ <para>For an entry with a subentry use an exclamation mark
+ to separate them:
+ <literal>\index{beer!lite}</literal>.<indexterm>
+ <primary>beer</primary>
+ <secondary>lite</secondary>
+ </indexterm> Subsubentries like
+ <literal>\index{beer!lite!American}</literal> work to
+ another level deep.<indexterm>
+ <primary>beer</primary>
+ <secondary>lite</secondary>
+ <tertiary>American</tertiary>
+ </indexterm></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Cross-references</term>
+ <listitem>
+ <para><wordasword>See</wordasword> entries are done with
+ the vertical bar (one of the rare times it does
+ <emphasis>not</emphasis> get interpreted as a math
+ character):
+ <literal>\index{Microbrew|see{beer}}</literal><indexterm>
+ <primary>Microbrew</primary>
+ <see>beer</see>
+ </indexterm></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="indextypo">
+ <term>Font changes</term>
+ <listitem>
+ <para>To change the style of an entry, use the @-sign
+ followed by a font change command:</para>
+ <programlisting>
+\index{beer!Rogue!Chocolate
+ Stout@\textit{Chocolate Stout}}
+ </programlisting>
+ <para role="cont">This example<indexterm>
+ <primary remap="\textit">Chocolate Stout</primary>
+ </indexterm> indexes <wordasword><productname>Chocolate
+ Stout</productname></wordasword> and italicises it
+ at the same time. Any of the standard
+ <literal>\text...</literal> font-change commands work
+ here: see <xref linkend="fontcmds"/> for details.</para>
+ <para>You can also change the font of the index number on
+ its own, as for first-usage references, by using the
+ vertical bar in a similar way to the
+ <wordasword>see</wordasword> entries above, but
+ substituting a font-change command name
+ (<emphasis>without</emphasis> a backslash) such as
+ <literal>textbf</literal> for bold-face text (see the
+ index)<indexterm
+ significance="preferred">
+ <primary>Chocolate Stout</primary>
+ </indexterm>:</para>
+ <programlisting>
+\index{beer!Rogue!Chocolate Stout|textbf}
+ </programlisting>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Out of sequence</term>
+ <listitem>
+ <para>The same method can be used as for font changes,
+ but using the alternate index word instead of the font
+ command name, so
+ <literal>\index{Oregon Brewing Company@Rogue}</literal>
+ <indexterm>
+ <primary sortas="Oregon Brewing
+ Company">Rogue</primary>
+ </indexterm> will add an entry for
+ <wordasword>Rogue</wordasword> in the
+ <wordasword>O</wordasword> section of the index, as if
+ it was spelled <wordasword>Oregon Brewing
+ Company</wordasword>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>When the document has been processed through <LaTeX/> it
+ will have created a <filename>.idx</filename> file, which you
+ run through the <productname>makeindex</productname> program
+ by typing (for example):</para>
+ <programlisting>
+makeindex&nbsp;mythesis
+ </programlisting>
+ <para>Some editors may have a button or menu entry for this. The
+ program will look for the <filename>.idx</filename> file and
+ output a <filename>.ind</filename> file. This gets used by the
+ command <command>printindex</command> which you put at the end
+ of your document, where you want the index printed. The
+ default index format is two columns.</para>
+ <para>Glossaries are done in a similar manner using the command
+ <command>makeglossary</command> in the preamble and the
+ command <command>glossary</command> in the same way as
+ <command>index</command>. There are some subtle differences in
+ the way glossaries are handled: both the books by <citetitle
+ ref="latexbook" show="both"></citetitle> and by <citetitle
+ show="both" ref="companion"></citetitle> duck the issue, but
+ there is some documentation on <filename>glotex</filename> on
+ <acronym ref="CTAN"></acronym>.</para>
+ </sect1>
+ <sect1 id="multicols">
+ <title>Multiple columns</title>
+ <indexterm>
+ <primary>columns</primary>
+ </indexterm>
+ <para>Use the <methodname>multicol</methodname> package: the
+ environment is called <modespec>multicols</modespec> (note the
+ plural form) and it takes the number of columns as a separate
+ argument in curly braces:</para>
+ <programlisting>
+\usepackage{multicol}
+...
+\begin{multicols}{3}
+...
+\end{multicols}
+ </programlisting>
+ <simplesect remap="multicols" xreflabel="3">
+ <title></title>
+ <literallayout
+ role="">\setlength{\parskip}{0pt}\footnotesize\noindent </literallayout>
+ <para><LaTeX/> has built-in support for two-column typesetting
+ via the <literal>twocolumn</literal> option in the standard
+ Document Class Declarations, but it is relatively inflexible
+ in that you cannot change from full-width to double-column
+ and back again on the same page, and the final page does not
+ balance the column heights. However, it does feature special
+ <modespec>figure*</modespec> and <modespec>table*</modespec>
+ environments which typeset full-width figures and tables
+ across a double-column setting.</para>
+ <para>The more extensive solution is the
+ <methodname>multicol</methodname> package, which will set up
+ to 10 columns, and allows the number of columns to be
+ changed or reset to one in mid-page, so that full-width
+ graphics can still be used. It also balances the height of
+ the final page so that all columns are the same
+ height&mdash;if possible: it's not always
+ achievable&mdash;and you can control the width of the gutter
+ by setting the <command>columnsep</command> length to a new
+ dimension.</para>
+ <para>Multi-column work needs some skill in typographic
+ layout, though: the narrowness of the columns makes
+ typesetting less likely to fit smoothly because it&apos;s hard to
+ hyphenate and justify well when there is little space to
+ man&oelig;uvre in.</para>
+ </simplesect>
+ </sect1>
+ </chapter>
+ <chapter id="typo">
+ <title>Fonts and layouts</title>
+ <indexterm>
+ <primary>typographics</primary>
+ </indexterm>
+ <para>This is the chapter that most users want first, because they
+ come to structured documents from a wordprocessing environment
+ where the <emphasis>only</emphasis> way to convey different
+ types of information is to fiddle with the font and size
+ drop-down menus.</para>
+ <para>As I hope you have seen, this is normally completely
+ unnecessary in <LaTeX/>, which does most of the hard work for you
+ automatically. However, there are occasions when you need to
+ make manual typographic changes, and this chapter is about how
+ to do them.</para>
+ <sect1 id="layouts">
+ <title>Changing layout</title>
+ <para>The design of the page can be a very subjective matter,
+ and also rather a subtle one. Many organisations large and
+ small pay considerable sums to designers to come up with page
+ layouts to suit their purposes. Styles in page layouts change
+ with the years, as do fashions in everything else, so what may
+ have looked attractive in 1991 may look rather dated in
+ 2011.</para>
+ <para>As with most aspects of typography, making the document
+ readable involves making it consistent, so the reader is not
+ interrupted or distracted too much by apparently random
+ changes in margins, widths, or placement of objects. However,
+ there are a number of different occasions where the layout
+ usually <emphasis>does</emphasis> change, related to the
+ frequency with which the format appears.</para>
+ <itemizedlist>
+ <listitem>
+ <para>The title page, the half-title, copyright page,
+ dedication, and other one-page preliminaries (if you use
+ them) are usually designed individually, as the information
+ on it only occurs once in that format anywhere in the
+ document.</para>
+ </listitem>
+ <listitem>
+ <para>The table of contents and other related lists like
+ figures and tables all need to share one
+ design.</para>
+ </listitem>
+ <listitem>
+ <para>The prelims like Foreword, Introduction, and Preface
+ should likewise follow the same format between
+ them.</para>
+ </listitem>
+ <listitem>
+ <para>Chapter and Appendix start pages usually share a
+ layout.</para>
+ </listitem>
+ <listitem>
+ <para>Other (normal) pages have a single layout, but it may
+ specify individual variations to handle tables, lists,
+ figures, sidebars, exercises, footnotes, &etc;</para>
+ </listitem>
+ </itemizedlist>
+ <para>If you are going to design a whole document, it&apos;s
+ probably a good idea to read a couple of books on layout
+ design first, to get a feel for the conventions which
+ contribute to making the reader comfortable reading.</para>
+ <para>While unusual or radical layouts have an important role in
+ attention-grabbing, or in making a socio-political statement
+ (<citetitle ref="wired"></citetitle> magazine is an obvious
+ recent example), they are usually out of place in business
+ reports, white papers, books, theses, and journals. In
+ ephemera, on the other hand, as in advertising, they are
+ probably critical.</para>
+ <sect2 id="spacing">
+ <title>Spacing</title>
+ <indexterm>
+ <primary>page size</primary>
+ <secondary>margins</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>margins</primary>
+ </indexterm>
+ <para>We mentioned in <xref linkend="marginals"/> and
+ elsewhere the existence of the
+ <methodname>geometry</methodname> package which lets you
+ change margins. It also lets you set the text-area height
+ and width and a lot of other layout settings: read the
+ documentation for details (see <xref
+ linkend="packagedoc"/> for how to read package
+ documentation).</para>
+ <programlisting>
+\usepackage[left=2cm,top=1cm,bottom=2cm,right=3cm,
+ nohead,nofoot]{geometry}
+ </programlisting>
+ <para>The spacing around the individual textual components
+ (headings, paragraphs, lists, footnotes, &etc;)&nbsp;can
+ also be changed on a document-wide basis, as we saw with
+ paragraph spacing and indentation in <xref
+ linkend="paraspace"/>.</para>
+ <para>Changing the spacing of section headings for the whole
+ document can be done with the
+ <methodname>sectsty</methodname> package, designed to let
+ you adjust section-head spacing without having to know about
+ the internal <LaTeX/> coding, which is quite complex.</para>
+ <para>The spacing for lists can be adjusted with the
+ <methodname>mdwlist</methodname> package. In both cases the
+ user with highly specific requirements such as a
+ publisher&apos;s Compositor&apos;s Specification should read
+ the relevant sections in the <citetitle
+ ref="companion"></citetitle> or ask for expert help, as
+ there are many internal settings which can also be changed
+ to fine-tune your design, but which need some knowledge of
+ <LaTeX/>&apos;s internals.</para>
+ <para>All the above are for automating changes so that they
+ occur every time in a consistent manner. You can also make
+ manual changes whenever you need:</para>
+ <indexterm>
+ <primary>space</primary>
+ <see>white-space</see>
+ </indexterm>
+ <variablelist>
+ <varlistentry>
+ <term>Flexible vertical space</term>
+ <listitem>
+ <indexterm>
+ <primary>white-space</primary>
+ <secondary>vertical</secondary>
+ <tertiary>flexible</tertiary>
+ </indexterm>
+ <para>There are three commands
+ <command>smallskip</command>,
+ <command>medskip</command>, and
+ <command>bigskip</command>. These output flexible
+ (dynamic, or <wordasword>rubber</wordasword>) space,
+ approximately 3pt, 6pt, and 12pt high respectively,
+ and they will automatically compress or expand a
+ little, depending on the demands of the rest of the
+ page (for example to allow one extra line to fit, or a
+ heading to be moved to the next page without anyone
+ except a typographer noticing the change). These
+ commands can only be used after a paragraph break (a
+ blank line or the command
+ <command>par</command>).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Fixed vertical space</term>
+ <listitem>
+ <indexterm>
+ <primary>white-space</primary>
+ <secondary>vertical</secondary>
+ <tertiary>fixed</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>white-space</primary>
+ <secondary>vertical</secondary>
+ <tertiary>disappearing</tertiary>
+ </indexterm>
+ <para>For a fixed-height space which will
+ <emphasis>not</emphasis> stretch or shrink, use the
+ command <command>vspace</command> followed by a length
+ in curly braces, &eg; <literal>\vspace{18pt}</literal>
+ (again, this has to be after a paragraph break). Bear
+ in mind that extra space which ends up at a page-break
+ when the document is formatted <emphasis>will get
+ discarded entirely</emphasis> to make the bottom and
+ top lines fall in the correct places. To force a
+ vertical space to remain and be taken into account
+ even after a page break (very rare), use the starred
+ variant <command>vspace*</command>, &eg;
+ <literal>\vspace*{19pt}</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Double spacing</term>
+ <listitem>
+ <indexterm>
+ <primary>white-space</primary>
+ <secondary>double-spacing</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>double-spacing</primary>
+ </indexterm>
+ <para>Double-spacing normal lines of text is usually a
+ bad idea, as it looks very ugly. It is still
+ unfortunately a requirement in some universities for
+ thesis submission, a historical relic from the days of
+ typewriters. Nowadays, 1&frac13; or 1&frac12; line
+ spacing is considered acceptable, according to your
+ font size. If your institution still thinks they
+ should have double line spacing, they are probably
+ wrong, and just don&apos;t understand that the world has
+ moved on since the typewriter. Show them this
+ paragraph and explain that they need to enter the 21st
+ century and adapt to the features of computer
+ typesetting. If they still insist, use the
+ <methodname>setspace</methodname> package,which has
+ commands for double line-spacing and one-and-a-half
+ line spacing, but be prepared for some very ugly
+ output (so warn your supervisor and extern).</para>
+ <para>The space between lines is defined by the value of
+ the length variable <varname
+ role="dimension">baselineskip</varname> multiplied
+ by the value of the <command>baselinestretch</command>
+ command. In general, <emphasis>don&apos;t meddle with
+ <varname role="dimension">baselineskip</varname> at
+ all</emphasis>, and with
+ <command>baselinestretch</command> only if you know
+ what you are doing. (Both can, however, safely be used
+ as reference values in commands like
+ <literal>\vspace{\baselineskip}</literal> to leave a
+ whole line space.)</para>
+ <indexterm>
+ <primary>spacing</primary>
+ <see>white-space</see>
+ </indexterm>
+ <para>The value of <varname
+ role="dimension">baselineskip</varname> changes with
+ the font size (see <xref
+ linkend="fontsize"/>) but is conventionally set to
+ 1.2 times the current nominal font size. This is a
+ value derived from long experience: only change it if
+ you understand what it means and what effect it will
+ have.</para>
+ <para>Quite separately, there are some perfectly genuine
+ and normal reasons for wanting wide line spacing,
+ <indexterm>
+ <primary>spacing</primary>
+ <see>double-spacing</see>
+ </indexterm> for example when typesetting a proof of a
+ critical or variorum edition, where editors and
+ contributors are going to want to add notes manually
+ by writing between the lines, or where the text is
+ going to be overprinted by something else like
+ Braille, or in advertising or display text for special
+ effects.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Horizontal space</term>
+ <listitem>
+ <indexterm>
+ <primary>white-space</primary>
+ <secondary>horizontal</secondary>
+ </indexterm>
+ <para>There is a horizontal equivalent to the
+ <command>vspace</command> command:
+ <command>hspace</command>, which works in the same
+ way, so I can force a 1&inch; space like
+ this<literallayout remap="whitespace"
+ width="72">\hspace*{1in}</literallayout>in
+ mid-paragraph. There are also some predefined
+ (shorter) spaces available:</para>
+ <itemizedlist>
+ <listitem>
+ <para><command>thinspace</command>&nbsp;(&frac16;em),
+ which we saw between single and double quotes in
+ <xref linkend="thinspace"/>. It&apos;s also
+ sometimes used between the full point after
+ abbreviations and a following number, as in page
+ references like p.&thinsp;199, where a word space
+ would look too big, and setting it solid would
+ look too tight.</para>
+ </listitem>
+ <listitem>
+ <para><command>enspace</command>&nbsp;(&frac12;em).
+ There is no direct equivalent predefined in
+ <LaTeX/> for mid and thick spaces as used by metal
+ typesetters, although it would be possible to
+ define them. The en as a unit is often used as the
+ width of a single digit in some fonts, as a
+ convenience so that tables of figures are easy to
+ line up.</para>
+ </listitem>
+ <listitem>
+ <para><command>quad</command>&nbsp;(1em).</para>
+ </listitem>
+ <listitem>
+ <para><command>qquad</command>&nbsp;(2em).</para>
+ </listitem>
+ </itemizedlist>
+ <para>Beyond this, all horizontal space within
+ paragraphs is automatically flexible,
+ <indexterm>
+ <primary>tracking</primary>
+ <see>letterspacing</see>
+ </indexterm>
+ <indexterm>
+ <primary>letterspacing</primary>
+ </indexterm> as this is what
+ <LaTeX/> uses to achieve justification. Never be
+ tempted to try and change the spacing between letters
+ unless you have some professional training in
+ typography. Some systems use letterspacing
+ (incorrectly called <quote>tracking</quote>) as an aid
+ to justification and it is almost always wrong to do
+ so (and looks it). While it <emphasis>is</emphasis>
+ possible to change letterspacing (with the
+ <methodname>soul</methodname> package), it should only
+ be done by a typographer, and then only very rarely,
+ as the settings are very subtle and beyond the scope
+ of this book.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+ <sect2 id="runningheads">
+ <title>Headers and footers</title>
+ <para><LaTeX/> has built-in settings to control the page style
+ of its default page layouts. These are implemented with the
+ <command>pagestyle</command> command, which can take one of
+ the following arguments.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>plain</option></term>
+ <listitem>
+ <para>for a page number centered at the bottom;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>empty</option></term>
+ <listitem>
+ <para>for nothing at all, not even a page number;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>headings</option></term>
+ <listitem>
+ <para>for running heads based on the current chapter and
+ section;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>myheadings</option></term>
+ <listitem>
+ <para>which lets you use your own reprogrammed
+ definitions of how <command>markright</command> and
+ <command>markboth</command> commands, which control
+ how chapter and section titles get into page
+ headers.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>The command <command>thispagestyle</command> (taking the
+ same arguments) can be used to force a specific style for
+ the current page only.</para>
+ <para>However, the easiest way is to use the
+ <methodname>fancyhdr</methodname> package, which lets you
+ redefine the left-hand, centre, and right-hand page headers
+ and footers for both odd and even pages (twelve objects in
+ all). These areas can contain a page number, fixed text,
+ variable text (like the current chapter or section title, or
+ the catch-words of a dictionary), or even a small image.
+ They can also be used to do page backgrounds and frames, by
+ making one of them the top corner of an invisible box which
+ <quote>hangs</quote> text or images down over the whole
+ page.</para>
+ <para>The settings for the downloadable version of this
+ document can be used as an example: for the whole story you
+ have to read the documentation.</para>
+ <programlisting>
+\pagestyle{fancy}\fancyhead{}
+\renewcommand\headrulewidth{.1pt}
+\fancyhead[LO,RE]{\footnotesize\sffamily\lite\leftmark}
+\fancyhead[LE,RO]{\footnotesize\sffamily\lite\itshape
+ \rightmark}
+\fancyfoot[C]{}
+\fancyfoot[LE,RO]{\setlength{\fboxsep}{2pt}\ovalbox%
+ {\footnotesize\sffamily\thepage}}
+\fancyfoot[LO,RE]{\footnotesize\sffamily\lite\@title}
+\fancypagestyle{plain}{\fancyhf{}
+ \fancyfoot[R]{\setlength{\fboxsep}{2pt}\ovalbox{%
+ \footnotesize\sffamily\thepage}}
+ \fancyfoot[L]{\footnotesize\sffamily\lite\@title}
+ \renewcommand{\headrulewidth}{0pt}}
+ </programlisting>
+ <para>This is probably more complex than most documents, but
+ it illustrates some common requirements:</para>
+ <orderedlist>
+ <listitem>
+ <para>Settings are prefixed by making the
+ <command>pagestyle</command>&nbsp;<quote>fancy</quote>
+ and setting the <command>fancyhead</command> to
+ null to zap any predefined values.</para>
+ </listitem>
+ <listitem>
+ <para>The thickness of the rule at the top of the page can
+ be changed (or set to 0pt to make it disappear).</para>
+ </listitem>
+ <listitem>
+ <para>The header and footer settings are specified with L,
+ C, and R for left, centre, and right; and with O and E
+ for Odd and Even numbered pages. In each setting, the
+ typeface style, size, and font can be specified along
+ with macros which implement various dynamic texts (here,
+ the current chapter and section titles, which <LaTeX/>
+ stores in <command>rightmark</command> and
+ <command>leftmark</command>).</para>
+ </listitem>
+ <listitem>
+ <para>The <quote>plain</quote> variant is used for chapter
+ starts, and resets some of the parameters
+ accordingly.</para>
+ </listitem>
+ </orderedlist>
+ </sect2>
+ </sect1>
+ <sect1 id="fontuse">
+ <title>Using fonts</title>
+ <indexterm>
+ <primary>fonts</primary>
+ <secondary>in general</secondary>
+ </indexterm>
+ <para>The default typeface in <LaTeX/> is <acronym
+ id="CM">Computer Modern</acronym>. This typeface was
+ designed by Knuth for use with <TeX/> because it is a book
+ face, and he designed <TeX/> originally for typesetting books.
+ Because it is one of the very few book typefaces with a
+ comprehensive set of fonts, including a full suite of
+ mathematics, it has remained the default, rather than the
+ Times you find in wordprocessors, because until recently the
+ mathematical symbols for Times were a commercial product often
+ unavailable to users of free software.</para>
+ <para><indexterm>
+ <primary>fonts</primary>
+ <secondary>&metafont;</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>fonts</primary>
+ <secondary>Computer Modern</secondary>
+ </indexterm><format fontencoding="OT1" fontfamily="cmr"
+ fontsize="12pt" image="cmr">Computer Modern is based on
+ a 19th-century book typeface from Monotype, which is why it
+ looks a little like an old-fashioned school book. This
+ paragraph is set in Computer Modern so you can see what it
+ looks like. The typeface was designed using &metafont;, the
+ font-drawing program made by Knuth to accompany <TeX/>
+ systems, but it is now also available in Type&nbsp;1 and
+ TrueType formats.</format></para>
+ <warning>
+ <para>If you are reading this in a web browser, the above
+ paragraph is only a low-resolution copy because browsers
+ don&apos;t usually have the Computer Modern font available.
+ All the rest of this document is set in &rmfont;, with
+ &sffont; for some of the headings and &ttfont; for the
+ fixed-width type.</para>
+ </warning>
+ <para>In addition to <acronym ref="CM"></acronym>, there are
+ many other &metafont; fonts which can be downloaded from
+ <acronym ref="CTAN"></acronym>, including a large collection
+ of historical, symbol, initial, and non-Latin fonts. <LaTeX/>
+ also comes with the <wordasword>Adobe 35</wordasword>
+ typefaces which are built into laser printers and other
+ <acronym ref="DTP"></acronym> systems, and some more fonts
+ donated by the X&nbsp;Consortium. Plus, of course, standard
+ <LaTeX/> can use any of the thousands of
+ Type&nbsp;1 fonts available, and
+ <productname>pdf<LaTeX/></productname> can use any of the
+ thousands of TrueType fonts as well.</para>
+ <para>In the following lists, if there is a package available,
+ its name is given in parentheses after the name of the
+ typeface. The font-family name is shown on the right-hand
+ side. If a non-standard font-encoding is needed, its name is
+ shown before the font-family name.</para>
+ <indexterm>
+ <primary>fonts</primary>
+ <secondary>TrueType</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>fonts</primary>
+ <secondary sortas="metafont">&metafont;</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>fonts</primary>
+ <secondary>PostScript</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>fonts</primary>
+ <secondary>Type&nbsp;1</secondary>
+ </indexterm>
+ <informaltable floatstyle="b" id="fontable-mf">
+ <blockinfo>
+ <title>Latin-alphabet typefaces (&metafont;)</title>
+ </blockinfo>
+ <mediaobject xreflabel="Computer Modern Roman" userlevel="*">
+ <textobject xreflabel="cmr" altfilename="p70-01">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Computer Modern Sans">
+ <textobject xreflabel="cmss" altfilename="p70-02">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Computer Modern Typewriter">
+ <textobject xreflabel="cmtt" altfilename="p70-03">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Pandora">
+ <textobject id="pandora" xreflabel="panr" altfilename="p70-04">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Pandora Sans">
+ <textobject xreflabel="pss" altfilename="p70-05">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Pandora Typewriter">
+ <textobject xreflabel="pntt" altfilename="p70-05">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Universal">
+ <textobject xreflabel="uni" altfilename="p70-06">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Concrete" userlevel="*">
+ <textobject id="ccr" xreflabel="ccr" altfilename="p70-07">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="É&inodot;reannach">
+ <textobject id="eiad" xreflabel="eiad" altfilename="p70-10">
+ <phrase>&ie.alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Rustic">
+ <textobject xreflabel="rust" altfilename="p70-15">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Uncial">
+ <textobject xreflabel="uncl" altfilename="p70-17">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Dürer">
+ <textobject xreflabel="zdu" altfilename="p70-18">
+ <phrase>&uc.alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Fraktur">
+ <textobject xreflabel="yfrak" arch="U" altfilename="p70-19">
+ <phrase>&de.alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Gothic">
+ <textobject xreflabel="ygoth" arch="U" altfilename="p70-20">
+ <phrase>If it plese any man spirituel or temporel</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Schwäbische">
+ <textobject xreflabel="yswab" arch="U" altfilename="p70-21">
+ <phrase>&de.alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ </informaltable>
+ <informaltable floatstyle="t" id="fontable-adobe">
+ <blockinfo>
+ <title>Latin-alphabet typefaces (PostScript Type 1) from
+ Adobe</title>
+ </blockinfo>
+ <mediaobject xreflabel="Avant Garde">
+ <textobject id="avant" xreflabel="pag" altfilename="p70-26">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Bookman">
+ <textobject id="bookman" xreflabel="pbk" altfilename="p70-22">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ <caption>Uses Avant Garde as the sans-serif and Courier for
+ monospace.</caption>
+ </mediaobject>
+ <mediaobject xreflabel="Courier">
+ <textobject id="courier" xreflabel="pcr" altfilename="p70-29">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Helvetica">
+ <textobject id="helvet" xreflabel="phv" altfilename="p70-27">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="New Century Schoolbook">
+ <textobject id="newcent" xreflabel="pnc" altfilename="p70-23">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ <caption>Uses Helvetica as the sans-serif font and Courier
+ for monospace.</caption>
+ </mediaobject>
+ <mediaobject xreflabel="Palatino">
+ <textobject id="palatino" xreflabel="ppl" altfilename="p70-24">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ <caption>Uses Avant Garde as the sans-serif and Courier for
+ monospace.</caption>
+ </mediaobject>
+ <mediaobject xreflabel="Symbol">
+ <textobject xreflabel="psy" arch="U" altfilename="p70-31">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Times New Roman" userlevel="*">
+ <textobject id="times" xreflabel="ptm" altfilename="p70-25">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ <caption>Uses Helvetica as the sans-serif font and Courier
+ for monospace. Mathematical symbols for Times are
+ available both free and commercially.</caption>
+ </mediaobject>
+ <mediaobject xreflabel="Zapf Chancery">
+ <textobject id="zapfchan" xreflabel="pzc"
+ role="\itshape" altfilename="p70-28">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Zapf Dingbats">
+ <textobject id="pifont" xreflabel="pzd" arch="U"
+ altfilename="p70-30">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ </informaltable>
+<?LaTeX \par\medskip ?>
+ <para>As mentioned in <xref linkend="print"/>, the
+ <wordasword>Adobe 35</wordasword> fonts can be used with any
+ printer, not just a laser printer or typesetter. The
+ <productname>Ghostscript</productname> interpreter and the
+ <productname>GSview</productname> viewer come with a large set
+ of printer drivers, so you just create PostScript output and
+ print from <productname>GSview</productname>.</para>
+ <para>Incidentally, the 35 refers to the total number of fonts
+ for the 10 typefaces, including their bold, italic, and
+ bold-italic variants.</para>
+ <para>Postscript Type 1 fonts have been the mainstay of the
+ graphic arts industries for many years, as they allow much
+ better definition of variance
+ (<wordasword>hinting</wordasword>) than most other formats.
+ However, the font format remains proprietary to Adobe, even
+ though they have released it for public use, which means they
+ could change it without warning. A new format called
+ <wordasword>OpenType</wordasword> is designed to overcome
+ this, and some versions of <TeX/> are
+ already able to use OpenType fonts.</para>
+ <informaltable floatstyle="b" id="fontable-x">
+ <blockinfo>
+ <title>Latin-alphabet fonts (PostScript Type 1) from the X
+ Consortium</title>
+ </blockinfo>
+ <mediaobject xreflabel="Charter">
+ <textobject id="charter" xreflabel="bch" altfilename="p70-32">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Nimbus Roman">
+ <textobject xreflabel="unm" altfilename="p70-33">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Nimbus Sans">
+ <textobject xreflabel="unms" altfilename="p70-34">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="URW Antiqua">
+ <textobject xreflabel="uaq" altfilename="p70-35">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="URW Grotesk">
+ <textobject xreflabel="ugq" role="\bfseries" altfilename="p70-36">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Utopia">
+ <textobject id="utopia" xreflabel="put" altfilename="p70-37">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ <caption>Removed from recent distributions as it is not
+ free.</caption>
+ </mediaobject>
+ </informaltable>
+<?LaTeX \par\medskip ?>
+ <informaltable floatstyle="p" id="fontable-nonlat">
+ <blockinfo>
+ <title>Non-Latin-alphabet typefaces (&metafont;)</title>
+ </blockinfo>
+ <mediaobject xreflabel="BB Dingbats">
+ <textobject xreflabel="ding" arch="U" altfilename="p70-08">
+ <phrase wordsize="9">&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Cypriot">
+ <textobject xreflabel="cypr" altfilename="p70-09">
+ <phrase wordsize="8">&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Etruscan">
+ <textobject xreflabel="etr" altfilename="p70-11">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Linear `B'">
+ <textobject xreflabel="linb" altfilename="p70-12">
+ <phrase wordsize="9">&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Phoenician">
+ <textobject xreflabel="phnc" altfilename="p70-13">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Runic">
+ <textobject xreflabel="fut" altfilename="p70-14">
+ <phrase>&uc.alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ <mediaobject xreflabel="Bard">
+ <textobject xreflabel="zba" arch="U" altfilename="p70-16">
+ <phrase>&alphabet;</phrase>
+ </textobject>
+ </mediaobject>
+ </informaltable>
+ <warning>
+ <para>Just to make it clear: standard <LaTeX/> uses only
+ &metafont; and <trademark>PostScript</trademark> Type&nbsp;1
+ fonts. <productname>pdf<LaTeX/></productname> can use TrueType
+ fonts as well.</para>
+ </warning>
+ <sect2>
+ <title>Changing the default font family</title>
+ <indexterm>
+ <primary>fonts</primary>
+ <secondary>changing the default</secondary>
+ </indexterm>
+ <para><LaTeX/> expects to work with three font families as
+ defaults:</para>
+ <indexterm>
+ <primary>fonts</primary>
+ <secondary>families</secondary>
+ </indexterm>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec align="left"/>
+ <colspec role="\ttfamily" align="left"/>
+ <thead>
+ <row>
+ <entry>Font family</entry>
+ <entry>Code</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Roman (serif, with tails on the uprights), the
+ default</entry>
+ <entry>rm</entry>
+ </row>
+ <row>
+ <entry role="\sffamily{}">Sans-serif, with no tails on
+ the uprights</entry>
+ <entry>sf</entry>
+ </row>
+ <row>
+ <entry role="\ttfamily{}">Monospace (fixed-width or
+ typewriter)</entry>
+ <entry>tt</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>The start-up default for <LaTeX/> equates the
+ <literal>rm</literal> default with the
+ <varname>cmr</varname> font-family (Computer Modern Roman),
+ <literal>sf</literal> with <varname>cmss</varname>, and
+ <literal>tt</literal> with <varname>cmtt</varname>. If you
+ use one of the packages listed in <xref
+ endterm="fontable-nonlat" linkend="fontable-mf"/>, it will
+ replace the defaults of the same type: for example,
+ <literal>\usepackage{bookman}</literal> makes the default
+ <literal>rm</literal> font-family Bookman
+ (<varname>pbk</varname>), but leaves the sans-serif
+ (<literal>sf</literal>) and monospace
+ (<literal>tt</literal>) families untouched. Equally,
+ <literal>\usepackage{helvet}</literal> changes the default
+ sans-serif family to Helvetica but leaves the serif (Roman)
+ and monospace families untouched. Using both commands will
+ change both defaults because they operate
+ independently.</para>
+ <para><emphasis>However</emphasis>&hellip;as it is common to
+ want to change all three defaults at the same time, some of
+ the most common <wordasword>suites</wordasword> of typefaces
+ are provided as packages:</para>
+ <variablelist>
+ <varlistentry>
+ <term><methodname>times</methodname></term>
+ <listitem>
+ <para>changes to Times/Helvetica/Courier.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><methodname>pslatex</methodname></term>
+ <listitem>
+ <para>same as <methodname>times</methodname> but uses a
+ specially narrowed Courier to save space (normal
+ Courier is rather inelegantly wide). This is the
+ preferred setting if you want Times.<footnote>
+ <para>The <methodname>pslatex</methodname> package
+ is also said to be outdated by some experts
+ because it implements rather long-windedly what
+ can now be done in three commands. However, until
+ these replace the current version, I recommend
+ continuing to use <methodname>pslatex</methodname>
+ when you want Times with Helvetica and narrow
+ Courier.</para>
+ </footnote></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><methodname>newcent</methodname></term>
+ <listitem>
+ <para>changes to New Century
+ Schoolbook/Helvetica/Courier.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><methodname>palatino</methodname></term>
+ <listitem>
+ <para>changes to Palatino/Avant Garde/Courier.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><methodname>palatcm</methodname></term>
+ <listitem>
+ <para>changes the roman to Palatino only, but with
+ <acronym ref="CM"></acronym> mathematics</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>Where no package name is given in <xref
+ endterm="fontable-nonlat" linkend="fontable-mf"/>, it means the
+ font is rarely used as a default by itself except in special
+ cases like users&apos; own homebrew packages. To use such a
+ font you have to specify it manually, or make a little macro
+ for yourself if you use it more than once.</para>
+ </sect2>
+ <sect2 id="fontfam">
+ <title>Changing the font-family temporarily</title>
+ <indexterm><primary>fonts</primary>
+ <secondary>changing temporarily</secondary>
+ </indexterm>
+ <para>To shift to another font family on a temporary basis,
+ use the commands <command>fontencoding</command> (if
+ needed), <command>fontfamily</command>, and
+ <command>selectfont</command>, and <emphasis>enclose the
+ commands <emphasis>and</emphasis> the text in curly
+ braces</emphasis>. Note that this is a
+ <emphasis>different</emphasis> way of using curly braces to
+ how we have used them before: it limits the effect of a
+ change to the material inside the braces.</para>
+ <informalexample>
+ <programlisting>
+{\fontfamily{phv}\selectfont
+Helvetica looks like this}:
+{\fontencoding{OT1}\fontfamily{bch}\selectfont
+Charter looks like this}.
+ </programlisting>
+ <para><format fontfamily="phv">Helvetica
+ looks like this</format>: <format fontencoding="OT1"
+ fontfamily="bch">Charter looks like
+ this</format>.</para>
+ </informalexample>
+ <para>In this example, the <command>fontencoding</command>
+ command has been used to ensure that the typeface will work
+ even if the sentence is used in the middle of something
+ typeset in a different encoding (like this
+ document).<footnote>
+ <para>Test for the observant reader: in what typeface will
+ the colon (:) in the example be set?</para>
+ </footnote></para>
+ <sidebar id="grouping">
+ <title>Grouping</title>
+ <indexterm><primary>grouping</primary></indexterm>
+ <para>Note carefully this use of curly braces to restrict
+ the scope of a change rather than delimit the argument to
+ a command. This is called
+ <wordasword>grouping</wordasword> and it makes the effect
+ any changes made <emphasis>inside</emphasis> the braces
+ local, so that they do not interfere with the text
+ following. Any changes to fonts or other values made
+ within the curly braces cease when the closing curly brace
+ is processed.</para>
+ </sidebar>
+ <para>In a normal document, of course, random typeface changes
+ like this are rather rare. You select your typeface[s] once
+ at the start of the document, and stick with them.</para>
+ <para>Most cases where people want to do unusual typeface
+ changes involve things like special symbols on a repetitive
+ basis, and <LaTeX/> provides much easier programmable ways
+ to make these changes into shorthand commands (called
+ macros: see <xref linkend="macros"/>). You could, for
+ example, make a macro called <command>product</command>
+ which would let you typeset product names in a distinct
+ typeface:</para>
+ <programlisting>
+Andlinger, Inc., has replaced \product{Splosh} with
+\product{SuperSplosh}.
+ </programlisting>
+ <para>This is one of <LaTeX/>&apos;s most powerful features.
+ It means that if you needed to change your
+ <command>product</command> command at some later stage to
+ use a different font, you only have to change three
+ characters in the macro (the font-family name), and
+ you don&apos;t need to edit your document text at all!
+ What&apos;s more, a macro could do other things at the same time,
+ like add an entry to an index of products.</para>
+ <para>However, vastly more common are changes to type
+ <emphasis>style</emphasis>, while staying with the same
+ font-family.</para>
+ </sect2>
+ <sect2>
+ <title>Changing font style</title>
+ <indexterm><primary>fonts</primary>
+ <secondary>styles</secondary>
+ </indexterm>
+ <para>Within each typeface or font family there are usually
+ several different <wordasword>looks</wordasword> to the type
+ design. <LaTeX/> distinguishes between font <firstterm
+ id="family">family</firstterm>, font <firstterm
+ id="shape">shape</firstterm>, and font <firstterm
+ id="series">series</firstterm>:</para>
+ <informaltable>
+ <tgroup cols="3">
+ <colspec colsep="flush" align="left"/>
+ <colspec role="\ttfamily" align="left"/>
+ <colspec align="left" colsep="flush"/>
+ <thead>
+ <row>
+ <entry>Type style</entry>
+ <entry>Command</entry>
+ <entry>Example (using Computer Modern)</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Upright</entry>
+ <entry><command>upshape</command>*</entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ image="p71-01">The quick brown fox jumps over the
+ lazy d</format></entry>
+ </row>
+ <row>
+ <entry>Italic</entry>
+ <entry><command>itshape</command></entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontshape="it"
+ image="p71-02"><literallayout>\font\foo=cmti10
+ \foo The quick brown fox jumps over the lazy
+ dog</literallayout></format></entry>
+ </row>
+ <row>
+ <entry>Slanted</entry>
+ <entry><command>slshape</command>*</entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontshape="sl" image="p71-03">The quick brown fox
+ jumps over the lazy d</format></entry>
+ </row>
+ <row>
+ <entry>Small Capitals</entry>
+ <entry><command>scshape</command>*</entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontshape="sc" image="p71-04">The quick brown fox
+ jumps over the</format></entry>
+ </row>
+ <row>
+ <entry>Bold</entry>
+ <entry><command>bfseries</command>*</entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontseries="b" image="p71-05">The quick brown fox
+ jumps over the lazy d</format></entry>
+ </row>
+ <row>
+ <entry>Bold Extended</entry>
+ <entry><command>bfseries</command>&dagger;</entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontseries="bx"
+ image="p71-06"><literallayout>\font\foo=cmbx10
+ \foo The quick brown fox jumps over the
+ lazy</literallayout></format></entry>
+ </row>
+ <row>
+ <entry>Sans-serif</entry>
+ <entry><command>sffamily</command></entry>
+ <entry><format fontencoding="OT1" fontfamily="cmss"
+ image="p71-07">The quick brown fox jumps over the
+ lazy dog</format></entry>
+ </row>
+ <row>
+ <entry>Monospace</entry>
+ <entry><command>ttfamily</command></entry>
+ <entry><format fontencoding="OT1" fontfamily="cmtt"
+ image="p71-08">The quick brown fox jumps over the
+ laz</format></entry>
+ </row>
+ </tbody>
+ <simplelist>
+ <member xreflabel="*">Not all typefaces have all
+ variants! Some only have bold and italics.</member>
+ <member xreflabel="&dagger;">Some typefaces do not have
+ both bold and bold extended: by default <LaTeX/> uses
+ <command>bfseries</command> for bold
+ extended.</member>
+ </simplelist>
+ </tgroup>
+ </informaltable>
+ <para>These <wordasword>shape</wordasword>,
+ <wordasword>series</wordasword>, and
+ <wordasword>family</wordasword> commands are <firstterm
+ id="commutative">commutative</firstterm>, so you can
+ combine a shape with a series and/or a family, without the
+ need to use <command>selectfont</command>:</para>
+ <programlisting>
+This gives you {\bfseries\itshape\sffamily bold
+italic sans-serif type}, but beware
+ </programlisting>
+ <para>This gives you <format fontdefault="sf" fontseries="b"
+ fontshape="it">bold italic sans-serif type</format>, but
+ beware of pushing your fonts beyond their limits unless you
+ are a typographer. It is not normally meaningful to combine
+ one shape or series class with another of the same class,
+ such as trying to get slanted-italics. It&apos;s an
+ impossibility to combine one family with another (such as a
+ seriffed sans-serif typeface!). Slanted plus italics, for
+ example, doesn&apos;t make sense, as italics are already
+ slanted (although it is technically possible); and while
+ some typefaces may well possess italic small caps, they are
+ not in common use. Sans-serif and monospace (typewriter) are
+ different fonts, and often different typeface families
+ entirely.<footnote>
+ <para>Although if you&apos;re a typographer wanting to
+ experiment with typewriter typefaces with and without
+ serifs, you can use &metafont; to do exactly this kind
+ of thing. But that&apos;s way outside the scope of this
+ document.</para>
+ </footnote></para>
+ <para>There is an alternative syntax for the most common type
+ shape and series commands which uses curly braces in the
+ normal <wordasword>argument</wordasword> manner:</para>
+ <informaltable id="fontcmds">
+ <tgroup cols="3">
+ <colspec align="left" colsep="flush"/>
+ <colspec role="\ttfamily" align="left"/>
+ <colspec colsep="flush" align="left"/>
+ <thead>
+ <row>
+ <entry>Type style</entry>
+ <entry>Command</entry>
+ <entry>Example</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Italic</entry>
+ <entry><literal>\textit{text}</literal></entry>
+ <entry>puts <format fontshape="it">text</format>
+ into italics</entry>
+ </row>
+ <row>
+ <entry>Slanted</entry>
+ <entry><literal>\textsl{text}</literal></entry>
+ <entry>puts <format fontencoding="OT1"
+ fontfamily="cmr" fontshape="sl">text</format> into
+ slanted type*</entry>
+ </row>
+ <row>
+ <entry>Small Capitals</entry>
+ <entry><literal>\textsc{text}</literal></entry>
+ <entry>puts <format fontshape="sc">text</format> into
+ small caps</entry>
+ </row>
+ <row>
+ <entry>Bold</entry>
+ <entry><literal>\textbf{text}</literal></entry>
+ <entry>puts <format fontseries="b">text</format> into
+ bold type</entry>
+ </row>
+ <row>
+ <entry>Sans-serif</entry>
+ <entry><literal>\textsf{text}</literal></entry>
+ <entry>puts <format fontdefault="sf">text</format>
+ into sans-serif type</entry>
+ </row>
+ <row>
+ <entry>Monospace</entry>
+ <entry><literal>\texttt{text}</literal></entry>
+ <entry>puts <format fontdefault="tt">text</format> into
+ typewriter type</entry>
+ </row>
+ </tbody>
+ <simplelist>
+ <member xreflabel="*">If slanted is available separately
+ from italics.</member>
+ </simplelist>
+ </tgroup>
+ </informaltable>
+ <para>You can nest these inside one another too:</para>
+ <programlisting>
+...\textbf{\itshape\textsf{bold italic
+sans-serif type}}...
+ </programlisting>
+ <para id="uline">Underlining isn&apos;t a font, and it is extremely
+ rare in typography except for special purposes. If you think
+ you need it, use the <methodname>ulem</methodname> package
+ with the <literal>normalem</literal> option, and the
+ <command>uline</command> command.</para>
+ </sect2>
+ <sect2 id="fontsize">
+ <title>Font sizes</title>
+ <indexterm>
+ <primary>fonts</primary>
+ <secondary>sizes</secondary>
+ </indexterm>
+ <para><LaTeX/> has built into its defaults a set of predefined
+ font size steps corresponding more or less to the
+ traditional sizes available to metal typesetters. This is
+ deliberate, as these sizes have grown up over 500 years of
+ printing as those which go best together for book-work,
+ which is where <TeX/> originated.</para>
+ <para>These sizes are also reflected in the size steps at
+ which Computer Modern was designed. It often comes as a
+ surprise to new users that many typefaces are not designed
+ as a single font and just scaled up or down, but specially
+ drawn at different sizes to make them more legible.</para>
+ <para>As an example, <format fontencoding="OT1"
+ fontfamily="cmr" fontsize="12" image="cmr12-12"
+ condition="LaTeX">here&apos;s 12pt Computer
+ Modern</format>, and <literallayout
+ remap="cmr5-12">{\font\cmbig=cmr5 at12pt\cmbig here&apos;s
+ 5pt Computer Modern scaled up to 12pt}</literallayout>, and
+ <literallayout remap="cmr17-12">{\font\cmsmall=cmr17
+ at12pt\cmsmall here&apos;s 17pt Computer Modern scaled down
+ to 12pt}</literallayout> so you can see there really is a
+ significant difference. In general, you probably don&apos;t
+ want to go scaling fonts too much beyond their design size
+ because they will start to look very odd.</para>
+ <para>The default sizes (and the commands that operate them)
+ are based on the use of a 10pt font, which is the normal
+ size for most texts. Using the larger defaults (11pt and
+ 12pt) for the body font will use 11pt and 12pt designs, with
+ other sizes (eg headings) resized to match. The exact sizes
+ used are listed in the macros in the Class Option files
+ <filename>size10.clo</filename>,
+ <filename>size11.clo</filename> and
+ <filename>size12.clo</filename>. <TeX/>&apos;s default fonts
+ above 10pt are in fact scaled by a factor of 1.2, as shown
+ in the fourth column of the table below.</para>
+ <informaltable>
+ <tgroup cols="3">
+ <colspec align="left" colsep="flush"/>
+ <colspec align="left"/>
+ <colspec align="right"/>
+ <colspec align="right" colsep="flush"/>
+ <thead>
+ <row>
+ <entry>Command</entry>
+ <entry>Example</entry>
+ <entry align="justify" colwidth=".6in">Nominal point
+ size</entry>
+ <entry align="justify" colwidth=".5in">Exact point
+ size</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><command>tiny</command></entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontstep="tiny" fontsize="5">The quick brown fox
+ jumps over the lazy dog</format></entry>
+ <entry>5</entry>
+ <entry>5</entry>
+ </row>
+ <row>
+ <entry><command>scriptsize</command></entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontstep="scriptsize" fontsize="7">The quick brown
+ fox jumps over the laz</format></entry>
+ <entry>7</entry>
+ <entry>7</entry>
+ </row>
+ <row>
+ <entry><command>footnotesize</command></entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontstep="footnotesize" fontsize="8">The quick
+ brown fox jumps over the l</format></entry>
+ <entry>8</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry><command>small</command></entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontstep="small" fontsize="9">The quick brown fox
+ jumps over th</format></entry>
+ <entry>9</entry>
+ <entry>9</entry>
+ </row>
+ <row>
+ <entry><command>normalsize</command></entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontstep="normalsize" fontsize="10">The quick
+ brown fox jumps over</format></entry>
+ <entry>10</entry>
+ <entry>10</entry>
+ </row>
+ <row>
+ <entry><command>large</command></entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontstep="large" fontsize="12">The quick brown fox
+ jumps</format></entry>
+ <entry>12</entry>
+ <entry>12</entry>
+ </row>
+ <row>
+ <entry><command>Large</command></entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontstep="Large" fontsize="14">The quick brown fox
+ ju</format></entry>
+ <entry>14</entry>
+ <entry>14.40</entry>
+ </row>
+ <row>
+ <entry><command>LARGE</command></entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontstep="LARGE" fontsize="18">The quick brown
+ fo</format></entry>
+ <entry>18</entry>
+ <entry>17.28</entry>
+ </row>
+ <row>
+ <entry><command>huge</command></entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontstep="huge" fontsize="20">The quick
+ brown</format></entry>
+ <entry>20</entry>
+ <entry>20.74</entry>
+ </row>
+ <row>
+ <entry>
+ <command>Huge</command></entry>
+ <entry><format fontencoding="OT1" fontfamily="cmr"
+ fontstep="Huge" fontsize="24">The quick
+ bro</format></entry>
+ <entry>24</entry>
+ <entry>24.88</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>While these <wordasword>shorthand</wordasword> commands
+ relieve the beginner of having to worry about the
+ <wordasword>right</wordasword> size for a given task, when
+ you need a specific size there is the
+ <command>fontsize</command> command:</para>
+ <programlisting>
+\fontsize{22}{28}\selectfont This is 22pt
+type 6pt leaded
+ </programlisting>
+ <para><quote>Leading</quote> comes from the old metal-type
+ practice of adding a lead strip between lines to increase the
+ spacing.</para>
+ <para>The <command>fontsize</command> command takes two
+ arguments: the point size and the baseline distance. The
+ above example gives you 22pt type on a 28pt baseline
+ (&ie;&nbsp;with 6pt extra space or
+ <wordasword>leading</wordasword> between the lines).</para>
+ <warning>
+ <para>Computer Modern fonts (the default) come fixed at the
+ named size steps shown in the table, and if you try to use
+ an odd size in between, <LaTeX/> will pick the closest
+ step instead. If you really need to use <acronym
+ ref="CM"></acronym> at arbitrary sizes there is a
+ package <methodname>type1cm</methodname> which lets you
+ override the default steps. If you use
+ <trademark>PostScript</trademark> (Type&nbsp;1) fonts, the
+ step sizes do not apply and the font scaling is infinitely
+ variable.</para>
+ </warning>
+ </sect2>
+ <sect2>
+ <title>Logical markup</title>
+ <para>All this playing around with fonts is very pretty but
+ you normally only do it for a reason, even if that reason is
+ just to be decorative. Italics, for example, are used for
+ many things:</para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec align="left"/>
+ <colspec role="\itshape" align="left"/>
+ <thead>
+ <row>
+ <entry>Cause</entry>
+ <entry>Effect</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Foreign words</entry>
+ <entry>ex officio</entry>
+ </row>
+ <row>
+ <entry>Scientific names</entry>
+ <entry>Ranunculus ficaria</entry>
+ </row>
+ <row>
+ <entry>Emphasis</entry>
+ <entry>must not</entry>
+ </row>
+ <row>
+ <entry>Titles of documents</entry>
+ <entry>The <LaTeX/> Companion</entry>
+ </row>
+ <row>
+ <entry>Product names</entry>
+ <entry><literallayout role="Corel's">{\upshape
+ Corel&apos;s}</literallayout> WordPerfect</entry>
+ </row>
+ <row>
+ <entry>Variables in maths</entry>
+ <entry><inlineequation>
+ <m:mtext>E=mc</m:mtext>
+ <m:msup>
+ <m:mtext>2</m:mtext>
+ </m:msup>
+ </inlineequation></entry>
+ </row>
+ <row>
+ <entry>Subtitles or headings</entry>
+ <entry>How to get started</entry>
+ </row>
+ <row>
+ <entry>Decoration</entry>
+ <entry>FREE UPGRADE!!!</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>Humans usually have no problem telling the difference
+ between these reasons, because they can read and understand
+ the meaning and context. Computers cannot (yet), so it has
+ become conventional to use descriptive names which make the
+ distinction explicit, even though the appearance may be the
+ same.</para>
+ <para><LaTeX/> has some of these built in, like
+ <command>emph</command>, which provides
+ <emphasis>emphasis</emphasis>. This has a special feature
+ because <format fontshape="it">when the surrounding text is
+ already italic, <emphasis>emphasis</emphasis>
+ automatically reverts to <emphasis>upright
+ type</emphasis></format>, which is the normal practice
+ for typesetting.</para>
+ <programlisting>
+This has a special feature because {\itshape when the
+surrounding text is already italic, \emph{emphasis}
+automatically reverts to upright type, which is the
+ </programlisting>
+ <para id="emph">This sensitivity to logic is programmed into
+ the definition of <command>emph</command> and it&apos;s not
+ hard to make up other commands of your own which could do
+ the same, such as <command>foreign</command> or
+ <command>product</command>.</para>
+ <para>But why would you bother? In a short document it&apos;s
+ probably not important, but if you&apos;re writing a long
+ report, or a formal document like an article, a book, or a
+ thesis, it makes writing and editing hugely easier if you
+ can control whole groups of special effects with a single
+ command, such as italicising, indexing, or cross-referencing
+ to a glossary. If a format needs changing, you only have to
+ change the definition, and every occurrence automatically
+ follows suit.</para>
+ <warning>
+ <para>Beware of this <quote>vaine conceipt of simple men,
+ which judge things by ther effects, and not by ther
+ causes</quote>. (Edmund Spenser, 1633) &nbsp;It&apos;s hugely
+ more efficient to have control of the cause than the
+ effect.</para>
+ </warning>
+ <para>It also makes it possible to find and act on groups of
+ meanings&mdash;such as making an index of scientific names
+ or product names (as in this document)&mdash;if they are
+ identified with a special command. Otherwise you&apos;d
+ spend weeks hunting manually through every
+ <command>textit</command> command to find the ones you
+ wanted. This is the importance of automation: it can save
+ you time and money.</para>
+ <para>In <xref linkend="macros"/> we will see how to make your
+ own simple commands like this.</para>
+ </sect2>
+ <sect2>
+ <title>Colour</title>
+ <indexterm><primary>colour</primary></indexterm>
+ <indexterm><primary>fonts</primary>
+ <secondary>colour</secondary>
+ </indexterm>
+ <para>You can typeset anything in <LaTeX/> in any colour you
+ want using the <methodname>color</methodname> package.
+ First, you need to add the command
+ <literal>\usepackage{color}</literal> to your preamble (note
+ the US spelling of color!). This makes available a default
+ palette of primary colours: <format
+ colour="red">red</format>, <format
+ colour="green">green</format>, and <format
+ colour="blue">blue</format> for the <acronym
+ ref="RGB"></acronym> colour model used for emitted light
+ (television screens), and <format
+ colour="cyan">cyan</format>, <format
+ colour="magenta">magenta</format>, <format
+ colour="yellow">yellow</format>, and black for the
+ <acronym ref="CMYK"></acronym> colour model used for
+ reflected light (printing).</para>
+ <para>For the occasional word or phrase in colour, use the
+ command <command>textcolor</command> with two arguments, the
+ colour name and the text: <literal>\textcolor{red}{like
+ this}</literal>. There is a <command>color</command>
+ command as well, for use within groups:</para>
+ <programlisting>
+...{\color{blue}some text in blue}...
+ </programlisting>
+ <para>If you have the <trademark>PostScript</trademark>
+ printer driver <productname>dvips</productname> installed,
+ you also get a separate 64-colour palette of predefined
+ <firstterm id="colornames">color names</firstterm>. These
+ represent approximately the colours in the big box of
+ <productname>Crayola</productname> colouring pencils much
+ favoured by artists and designers. This adds a new colour
+ model called <quote><literal>named</literal></quote>, so if
+ you want the <productname>Crayola</productname> colour
+ <format colourmodel="named" colourcode="FF00DD"
+ colour="RubineRed">RubineRed</format>, you can use the
+ <command>color</command> or <command>textcolor</command>
+ commands with a preceding optional argument
+ <quote><option>named</option></quote>:</para>
+ <programlisting>
+\color[named]{RubineRed}
+\textcolor[named]{RubineRed}{some red text}
+</programlisting>
+ <para>As some of the <quote><literal>named</literal></quote>
+ colour names are quite long, you can create a short name of
+ your own for colours you use frequently, using the
+ <command>definecolor</command> command:</para>
+ <programlisting>
+\definecolor{mb}{named}{MidnightBlue}
+ </programlisting>
+ <para>The <command>definecolor</command> command needs three
+ arguments: your shorthand name, the name of the colour model,
+ and the colour specification. In the case of the
+ <quote><literal>named</literal></quote> model, the last
+ argument is one of the 64 colour names. To
+ use these names with <productname>pdf<LaTeX/></productname>,
+ you need to use the <option>pdftex</option> option to the
+ <methodname>color</methodname> package.</para>
+ <para>Using the <command>definecolor</command> command, you
+ can define any colour you want by giving it a name,
+ specifying which colour model, and providing the <acronym
+ id="RGB">Red-Green-Blue</acronym> or <acronym
+ id="CMYK">Cyan-Magenta-Yellow-Black</acronym> colour
+ values expressed as decimals, separated by commas. For
+ example, an <acronym ref="RGB"></acronym> shade given as
+ (37,125,224) in decimal (&hash;250FE0 in hexadecimal as used
+ on the Web) can be given as<programlisting>
+\definecolor{midblue}{rgb}{0.145,0.490,0.882}
+ </programlisting> (divide each value by 255, the maximum for
+ each of the hues in the Red-Green-Blue colour model). You
+ can then use <command>textcolor</command> with your new
+ colour name: <format colour="midblue">the midblue looks like
+ this if you&apos;re reading in colour.</format></para>
+ <para>The <methodname>color</methodname> package also provides
+ a colour version of <command>fbox</command> (see <xref
+ linkend="fbox"/>) called
+ <command>colorbox</command>:</para>
+ <programlisting>
+\colorbox{midblue}{\color{magenta}Magenta on midblue}
+ </programlisting>
+ <para><literallayout
+ role="">\colorbox{midblue}{\color{magenta}Magenta
+ on midblue}</literallayout><format
+ condition="HTML" colour="magenta"
+ background="257DE2">Magenta on midblue</format>: you can
+ see how careful you need to be with colours!</para>
+ </sect2>
+ </sect1>
+ <sect1 id="instfonts">
+ <title>Installing new fonts</title>
+ <indexterm>
+ <primary>fonts</primary>
+ <secondary>installing</secondary>
+ </indexterm>
+ <para>Different fonts come in a variety of packagings: the three
+ most common used with <TeX/> systems are
+ <trademark>PostScript</trademark> fonts, TrueType fonts, and
+ &metafont; fonts. How you install them and where they go
+ depends on how you installed <LaTeX/>: all I can deal with here
+ are the standard locations within the <acronym
+ ref="TDS"></acronym>.</para>
+ <para>Typefaces come supplied as one or more font
+ <wordasword>outline</wordasword> files and a number of
+ ancillary files:</para>
+ <variablelist>
+ <varlistentry>
+ <term>&metafont; typefaces</term>
+ <listitem>
+ <para>have a number of <filename>.mf</filename> source
+ (outline) files, possibly also some
+ <filename>.fd</filename> (font definition) files and a
+ <filename>.sty</filename> (style) file. The
+ <filename>.tfm</filename> (<TeX/> font metric) files are
+ not needed, as they can be generated from the
+ outlines.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PostScript typefaces</term>
+ <listitem>
+ <para>come as a pair of files: a <filename>.pfb</filename>
+ (PostScript font binary) or <filename>.pfa</filename>
+ (PostScript font <acronym ref="ASCII"></acronym>)
+ outline, and an <filename>.afm</filename> (Adobe font
+ metric) file. There may also be
+ <filename>.inf</filename> and other files but these are
+ not needed for use with <TeX/> systems.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TrueType typefaces</term>
+ <listitem>
+ <para>are a single <filename>.ttf</filename> file, which
+ combines outline and metrics in one.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>The instructions here assume the use of the <acronym
+ id="NFSS">New Font Selection Scheme</acronym> used in
+ <LaTeXe/>. If you are running the obsolete <LaTeX/> 2.09,
+ upgrade it now.</para>
+ <sect2 id="mffonts">
+ <title>Installing &metafont; fonts</title>
+ <para>This is the simplest installation. When you download
+ &metafont; fonts from <acronym ref="CTAN"></acronym>,
+ you&apos;ll usually find a large number of outline files
+ (<filename>.mf</filename> files) and maybe some other types
+ as well (see below).</para>
+ <figure id="mkfontdir">
+ <title>Creating a new subdirectory for a font</title>
+ <graphic fileref="public" width="75%"/>
+ </figure>
+ <procedure>
+ <step id="newsub">
+ <para>Create a new subdirectory named after the typeface
+ you&apos;re installing in
+ <filename>texmf-local/fonts/source/public/</filename>:</para>
+ </step>
+ <step>
+ <para>Copy all the <filename>.mf</filename>
+ files to this directory.</para>
+ </step>
+ <step>
+ <para>Copy the <filename>.fd</filename> (Font Definition)
+ file[s] and the <filename>.sty</filename> (style) file
+ to your <filename>texmf/tex/latex/mfnfss</filename>
+ directory.</para>
+ </step>
+ <step>
+ <para>Run your <TeX/> indexer program (see <xref
+ linkend="texindex"/>).</para>
+ </step>
+ </procedure>
+ <para>That&apos;s it. Unlike <trademark>PostScript</trademark>
+ fonts, &metafont; fonts can be used to generate the font
+ metric file (<filename>.tfm</filename> files) automatically
+ on-the-fly the first time the typeface is used, so there
+ should be nothing else to install.</para>
+ <para>Now you can put a <command>usepackage</command> command
+ in your preamble with whatever name the
+ <literal>.sty</literal> file was called, and read the
+ documentation to see what commands it gives to use the font
+ (refer to <xref linkend="packinst"/> and <xref
+ linkend="dtxdoc"/>).</para>
+ <para>If the font came <emphasis>without</emphasis>
+ <filename>.fd</filename> or <filename>.sty</filename> files,
+ you&apos;ll need to find someone who can make them for you
+ (or follow the outline in <xref linkend="psfonts"/>, <xref
+ linkend="fdfiles"/>).</para>
+ <sect3>
+ <title>Pre-generated metrics (optional)</title>
+ <para>Some &metafont; fonts come with pre-generated
+ <filename>.tfm</filename> files which you can install if
+ your system is slow at generating them itself:</para>
+ <procedure condition="cont">
+ <step>
+ <para>Create a new subdirectory within
+ <filename>texmf-local/fonts/tfm/public/</filename>
+ named the same as the one you created for the
+ <filename>.mf</filename> files above.</para>
+ </step>
+ <step>
+ <para>Copy all the <filename>.tfm</filename> files into
+ this subdirectory.</para>
+ </step>
+ <step>
+ <para>Run your <TeX/> indexer program (see <xref
+ linkend="texindex"/>).</para>
+ </step>
+ </procedure>
+ </sect3>
+ <sect3>
+ <title>Pre-generated bitmaps (optional)</title>
+ <para>In some rare cases, pre-generated packed bitmap fonts
+ (<filename>.pk</filename> files) are also available from
+ <acronym ref="CTAN"></acronym> (normally your previewer
+ and print driver creates these automatically, but you can
+ use the pre-generated ones if you have a very slow
+ system). If you really want to install these, it&apos;s a
+ similar procedure to the <filename>.tfm</filename>
+ files:</para>
+ <procedure condition="cont">
+ <step>
+ <para>Create a new subdirectory within
+ <filename>texmf-local/fonts/pk/modeless/</filename>
+ named the same as the one you created for the
+ <filename>.mf</filename> and <filename>.tfm</filename>
+ files above.</para>
+ </step>
+ <step>
+ <para>Copy all the <filename>.nnnpk</filename> files
+ into this subdirectory (<parameter>nnn</parameter> is
+ a number reflecting the dot-density of the bitmap). On
+ Microsoft systems the files may just end in
+ <filename>.pk</filename> and be kept in subdirectories
+ named after the dot-density, &eg;
+ <filename>dpi360</filename>.</para>
+ </step>
+ <step>
+ <para>Run your <TeX/> indexer program (see <xref
+ linkend="texindex"/>).</para>
+ </step>
+ </procedure>
+ </sect3>
+ </sect2>
+ <sect2 id="psfonts">
+ <title>Installing PostScript fonts</title>
+ <indexterm><primary>fonts</primary>
+ <secondary>PostScript</secondary>
+ </indexterm>
+ <para>Lots of people will tell you that
+ <trademark>PostScript</trademark> fonts and PostScript
+ output are dead and that TrueType or OpenType fonts and PDF
+ output are the way to go. While this is true for many cases,
+ standard <LaTeX/> does not work with TrueType fonts and does
+ not produce <acronym ref="PDF"></acronym> directly. Only
+ <productname>pdf<LaTeX/></productname> does that, and there are
+ still many printers whose typesetters and platemakers use
+ <trademark>PostScript</trademark> rather than <acronym
+ ref="PDF"></acronym>. In addition, operating system
+ support for scalable fonts is still very poor on Unix
+ systems (including Linux), despite the advances in recent
+ years, so in many cases it still makes sense to use
+ <TeX/>&apos;s built-in support for PostScript.</para>
+ <para>Two files are needed for each font: the
+ <filename>.afm</filename> <acronym id="AFM">Adobe Font
+ Metric</acronym> and the <filename>.pfb</filename>
+ <acronym id="PFB">PostScript Font Binary</acronym> files.
+ <emphasis>You must have both for each font before you
+ start.</emphasis> If you only have the near-obsolete
+ <filename>.pfa</filename> <acronym id="PFA">PostScript Font
+ ASCII</acronym> files, it may be possible to generate the
+ <filename>.pfb</filename> files using the
+ <productname>t1binary</productname> program from the
+ <productname>t1utils</productname> suite (see <ulink
+ url="http://gnuwin32.sourceforge.net/packages/t1utils.htm"></ulink>)
+ or the excellent <productname>PFAedit</productname> font
+ editor (from <ulink
+ url="http://pfaedit.sourceforge.net"></ulink>). There are
+ unfortunately still some companies distributing Type&nbsp;1
+ fonts in <filename>.pfa</filename> format (Mathematica is
+ one reported recently).</para>
+ <warning>
+ <para>The installation method I described in earlier
+ editions has worked perfectly for me for years, but I have
+ updated it here to use the facilities of the
+ <productname>updmap</productname> program (which comes
+ with your <TeX/> installation). This removes the need for
+ one of the steps I gave before, which required editing the
+ <filename>psfonts.map</filename> file, as this is now
+ recreated by <productname>updmap</productname>. The
+ procedure below is <emphasis>not</emphasis> the official
+ way (that&apos;s <productname>fontinst</productname>), but
+ it is the basis for a script I am working on called
+ <productname>Gutta-Percha</productname><footnote>
+ <para>Yes, as in rubber.</para>
+ </footnote>, which automates the whole process.</para>
+ </warning>
+ <para>I&apos;ll repeat this: before you start, make sure you
+ have all the <filename>.afm</filename> and
+ <filename>.pfb</filename> files for the typeface you want.
+ In the example below, I&apos;m going to use a single font
+ from an imaginary typeface called Foo, so I have
+ <literal>foo.afm</literal> and
+ <literal>foo.pfb</literal> files.</para>
+ <procedure>
+ <step>
+ <title>Put the files in your temporary directory</title>
+ <para>This is <filename>/tmp</filename> on Linux, and
+ should be <filename>C:\tmp</filename> or
+ <filename>C:\temp</filename> or even
+ <filename>C:\Windows\temp</filename> on Microsoft
+ Windows.</para>
+ </step>
+ <step>
+ <title>Decide on the short font name to use
+ inside <LaTeX/>.</title>
+ <para>This is <emphasis>not</emphasis> the full
+ descriptive name (&eg;&nbsp;Baskerville Italic Bold
+ Extended) but an encoded font name in the format
+ <literal>fnnsseec</literal>, devised by <personname
+ remap="berry">
+ <firstname>Karl</firstname>
+ <surname>Berry</surname>
+ </personname>, which stores the same information in no
+ more than eight characters for compatibility with
+ systems which cannot handle long filenames. The letters
+ in the format above have the following meanings (see the
+ <productname>fontname</productname> documentation on
+ your computer for more details):</para>
+ <informaltable pgwide="left">
+ <tgroup cols="3">
+ <colspec align="left" colsep="flush"/>
+ <colspec align="left"/>
+ <colspec align="left" colsep="flush"/>
+ <thead>
+ <row>
+ <entry>Letter</entry>
+ <entry>Meaning</entry>
+ <entry>Examples</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>f</literal></entry>
+ <entry>foundry</entry>
+ <entry><literal>b</literal>=Bitstream,
+ <literal>m</literal>=Monotype,
+ <literal>p</literal>=Adobe</entry>
+ </row>
+ <row>
+ <entry><literal>nn</literal></entry>
+ <entry>typeface</entry>
+ <entry><literal>ba</literal>=Baskerville,
+ <literal>tm</literal>=Times,
+ <literal>pl</literal>=Palatino</entry>
+ </row>
+ <row>
+ <entry><literal>ss</literal></entry>
+ <entry>series/shape</entry>
+ <entry><literal>r</literal>=roman,
+ <literal>bi</literal>=bold italic, etc.</entry>
+ </row>
+ <row>
+ <entry><literal>ee</literal></entry>
+ <entry>encoding</entry>
+ <entry><literal>8a</literal>=default 8-bit ANSI,
+ <literal>ly</literal>=Y&ampers;Y&apos;s
+ <TeX/>&apos;n&apos;ANSI</entry>
+ </row>
+ <row>
+ <entry><format
+ fontseries="b"><literal>c</literal></format></entry>
+
+ <entry>[small]caps</entry>
+ <entry>(this is a literal
+ <wordasword>c</wordasword> character, used only
+ if needed)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>The <filename>texmf/fontname</filename> directory in
+ your installation of <LaTeX/> has files for several
+ foundries giving fully-formed names like these for
+ common fonts (&eg; <literal>ptmr8a</literal> is [Adobe]
+ <abbrev>P</abbrev>ost&shy;Script
+ <abbrev>T</abbrev>i<abbrev>m</abbrev>es
+ <abbrev>R</abbrev>oman in an
+ <abbrev>8</abbrev>&ndash;bit <abbrev>A</abbrev>NSI
+ encoding;
+ <literal>bgslly</literal> is <abbrev>B</abbrev>itstream
+ <abbrev>G</abbrev>ill <abbrev>S</abbrev>ans
+ <abbrev>L</abbrev>ight in Y&ampers;Y&apos;s
+ <TeX/>&apos;n&apos;ANSI encoding
+ [<abbrev>LY</abbrev>1]).<footnote>
+ <para>Confusingly, Bitstream fonts (and others from
+ similar sources) mostly have different names from
+ the original fonts, so what they call Humanist 521
+ is actually Gill Sans. Until recently, US law only
+ allowed the <emphasis>names</emphasis> of typefaces
+ to be copyrighted, not the font designs themselves,
+ leading to widespread piracy.</para>
+ </footnote> Read the documentation in <citetitle
+ ref="fontname"></citetitle> to find out how to make up
+ your own short names if the foundry and font you want is
+ not shown in the <filename>fontname</filename>
+ directory.</para>
+ <para>In this example we&apos;ll call our mythical example
+ typeface <wordasword>zork</wordasword> (standing for
+ <abbrev>Z</abbrev>fonts <abbrev>Or</abbrev>dinary
+ Boo<abbrev>k</abbrev>face, because
+ <systemitem>k</systemitem> is the letter used for Book
+ fonts, <systemitem>b</systemitem> being already the code
+ for bold) and we&apos;ll assume the font comes in the two
+ files <filename>foo.afm</filename> and
+ <filename>foo.pfb</filename> that I mentioned
+ above.</para>
+ <para>While the <productname>fontname</productname>
+ directories have ready-made lists of these names for
+ popular collections of typefaces, making them up
+ requires some knowledge of typographic terms and a
+ careful reading of the
+ <productname>fontname</productname>
+ documentation.</para>
+ </step>
+ <step>
+ <title>Decide on your encoding</title>
+ <para>This is what tripped me up the first few times until
+ someone pointed me at Y&ampers;Y&apos;s<footnote>
+ <para>Sadly, Y&ampers;Y, Inc has ceased trading and
+ their <TeX/> distribution is not longer available,
+ although there is email support at <ulink
+ url="http://lists.ucc.ie/lists/archives/yandytex.html"></ulink>,
+ and their encoding files continue to be used.</para>
+ </footnote>
+ <TeX/>&apos;n&apos;ANSI encoding which (to me) seems to
+ be the only one that includes the glyphs I want where I
+ want them.<footnote>
+ <para>The only one I still have problems with is
+ <wordasword>ø</wordasword>, which for some weird
+ reason isn&apos;t catered for in this encoding.</para>
+ </footnote><indexterm>
+ <primary>fonts</primary>
+ <secondary>encoding</secondary>
+ </indexterm> Your mileage may vary. This encoding is
+ referred to as <literal>LY1</literal> within <LaTeX/> and
+ the encoding file is in
+ <filename>texmf/dvips/base/texnansi.enc</filename>.
+ Encoding is needed because Adobe fonts store their
+ characters in different places to the <TeX/>
+ standard.</para>
+ <para>Copy this encoding file to the temporary directory
+ where you&apos;re doing all this stuff. If you&apos;re
+ using the 8a or 8r encoding (or some other encoding),
+ then copy that file instead
+ (<filename>8a.enc</filename>,
+ <filename>8r.enc</filename>).</para>
+ </step>
+ <step id="idfile">
+ <title>Convert <filename>.afm</filename> files to
+ <filename>.tfm</filename></title>
+ <para>The <productname>afm2tfm</productname> program is a
+ standard utility in the <filename>bin</filename>
+ directory of your <TeX/> installation. If it&apos;s not,
+ update your installation.</para>
+ <para>In a command window, type:</para>
+ <programlisting width="footnotesize">
+afm2tfm foo.afm -v zorkly.vpl -p texnansi.enc \
+rzorkly.tfm >zork.id
+ </programlisting>
+ <para>(Here and elsewhere I have sometimes had to break
+ the line to fit it on the printed page. It&apos;s actually
+ all typed as one long line if you omit the
+ backslash.)</para>
+ <para>This creates a special <wordasword>raw</wordasword>
+ <TeX/> Font Metric file (hence the special
+ <literal>r</literal> prefix) that <LaTeX/> can use, with
+ a list of all its properties encoded with LY1 (the
+ <filename>.vpl</filename> or Virtual Property List
+ file). Many people will tell you that virtual fonts are
+ dead and that this is the wrong way to do it, but no-one
+ has ever shown me an alternative that works, so I stick
+ with it.</para>
+ </step>
+ <step id="sc">
+ <title>Small caps (optional)</title>
+ <para>If you want a small caps variant faked up (perhaps
+ because the typeface family doesn&apos;t have a special
+ small-caps font), repeat the medicine like this:</para>
+ <programlisting width="footnotesize">
+afm2tfm foo.afm -V zorklyc.vpl -p texnansi.enc \
+rzorkly.tfm >>zork.id
+ </programlisting>
+ <para>Note the capital <literal>V</literal> option here.
+ Yes, it <emphasis>does</emphasis> overwrite the
+ <filename>rzorkly.tfm</filename> created in the first
+ command. Let it. And those are <emphasis>two</emphasis>
+ of the <wordasword>greater-than</wordasword> signs
+ before the <filename>zork.id</filename> filename because
+ we want to append to it, not overwrite it.</para>
+ </step>
+ <step>
+ <title>Create the virtual font</title>
+ <para>Turn the <filename>.vpl</filename> files into
+ <filename>.vf</filename> and <filename>.tfm</filename>
+ pairs. <LaTeX/> uses these to convert from Adobe&apos;s
+ encoding to its own. </para>
+ <programlisting>
+vptovf zorkly.vpl zorkly.vf zorkly.tfm
+vptovf zorklyc.vpl zorklyc.vf zorklyc.tfm
+ </programlisting>
+ <para>Again, the <filename>vptovf</filename> program is a
+ standard part of your <TeX/> distribution.</para>
+ </step>
+ <step>
+ <title>Make directories to hold the files</title>
+ <figure id="mksubdir">
+ <title>Making subdirectories to hold the files</title>
+ <graphic fileref="fonts" width="75%"/>
+ </figure>
+ <para>Under your <filename>texmf-local</filename>
+ directory there should be a <filename>fonts</filename>
+ directory, and in there there should be
+ <filename>afm</filename>, <filename>tfm</filename>,
+ <filename>type1</filename>, and <filename>vf</filename>
+ directories. Create them if they do not already
+ exist.</para>
+ <para>In each of these four, create a directory for the
+ foundry, and within them create a directory for the
+ typeface (using a human-readable typeface name, not the
+ short <personname remap="kb">
+ <firstname>Karl</firstname>
+ <surname> Berry</surname>
+ </personname> fontname). In our example, this
+ means:</para>
+ <programlisting>
+cd /usr/TeX/texmf-local/fonts
+mkdir -p afm/zfonts/ordinary
+mkdir -p tfm/zfonts/ordinary
+mkdir -p type1/zfonts/ordinary
+mkdir -p vf/zfonts/ordinary
+cd /tmp
+ </programlisting>
+ <para>Or if you&apos;re lazy like me:</para>
+ <programlisting>
+(cd /usr/TeX/texmf-local/fonts;\
+for d in afm tfm type1 vf;\
+do mkdir -p $d/zfonts/ordinary;done)
+ </programlisting>
+ <para>For Microsoft Windows users, the path before
+ <filename>texmf-local</filename> may look something like
+ <literal>C:\Program Files\TeXLive\</literal>, depending
+ on how and where you have installed your <TeX/>
+ system.</para>
+ <para>The <literal>-p</literal> is a Unix feature: it
+ automatically creates any missing intervening
+ subdirectories. If your directory-making command
+ doesn&apos;t do this, you&apos;ll have to make the
+ intervening directories by hand first.</para>
+ </step>
+ <step>
+ <title>Copy the files to their rightful places</title>
+ <para>Copy the four groups of files to the four new
+ directories:</para>
+ <programlisting>
+cp *.afm /usr/TeX/texmf/fonts/afm/zfonts/ordinary/
+cp *.tfm /usr/TeX/texmf/fonts/tfm/zfonts/ordinary/
+cp *.pfb /usr/TeX/texmf/fonts/type1/zfonts/ordinary/
+cp *.vf /usr/TeX/texmf/fonts/vf/zfonts/ordinary/
+ </programlisting>
+ <para>You can of course do all this with a directory
+ window and mouse if you find it easier.</para>
+ </step>
+ <step>
+ <title>Create a font map</title>
+ <para>The font map is what tells
+ <productname>dvips</productname> which <acronym
+ ref="PFB"></acronym> file to use for which font. The
+ configuration file for <productname>dvips</productname>
+ is <filename>texmf/dvips/config/config.ps</filename> and
+ it gets its entries from the program
+ <productname>updmap</productname> which reads map files
+ for each typeface. The configuration file for
+ <productname>updmap</productname> is
+ <filename>texmf-var/web2c/updmap.cfg</filename><footnote>
+ <para>There is another one of these at
+ <filename>texmf/web2c/updmap.cfg</filename>, but
+ that contains the map references for the fonts which
+ came with your distribution of <TeX/>, so you should
+ not interfere with it.</para>
+ </footnote>, so it needs an entry for our new font,
+ using the three-letter font family abbreviation (the
+ first three letters of the Berry fontname (here
+ <quote><literal>zor</literal></quote>):</para>
+ <programlisting>
+Map zor.map
+ </programlisting>
+ <para>We also have to create this map file
+ (<filename>zor.map</filename>) in a subdirectory of
+ <filename>texmf-local/dvips/config/</filename> named
+ after the foundry, so we need to create
+ <filename>texmf-local/dvips/config/zfonts</filename> as
+ well.</para>
+ <procedure>
+ <step>
+ <para>Open
+ <filename>/usr/TeX/texmf-var/web2c/updmap.cfg</filename>
+ in your editor.</para>
+ </step>
+ <step>
+ <para>At the bottom, add the line:
+ <literal remap="`">Map zor.map</literal></para>
+ </step>
+ <step>
+ <para>Save and close the file.</para>
+ </step>
+ </procedure>
+ <para>The font entries in our
+ <literal>zor.map</literal> will be on a
+ <emphasis>single</emphasis> line each, with no
+ line-wrapping. Each entry gives the short name of the
+ font, the long (Adobe) name, the
+ <trademark>PostScript</trademark> encoding parameters
+ (in quotes), and then two filenames prefixed by input
+ redirects (less-than signs): the encoding file and the
+ <trademark>PostScript</trademark> outline file.</para>
+ <procedure>
+ <step>
+ <para>First create the directory if it doesn&apos;t already
+ exist:</para>
+ <programlisting>
+mkdir -p /usr/TeX/texmf-local/dvips/config/zfonts
+ </programlisting>
+ </step>
+ <step>
+ <para>Use your editor to open (create) the file
+ <filename>/usr/TeX/texmf-local/dvips/config/zfonts/zor.map</filename>.</para>
+ </step>
+ <step id="fullname">
+ <para>Insert the line:</para>
+ <programlisting width="scriptsize" colwidth="left"><![CDATA[
+rzorkly Ordinary-Blackface "TeXnANSIEncoding ReEncodeFont" <texnansi.enc <foo.pfb
+ ]]></programlisting>
+ </step>
+ <step>
+ <para>Save and close the file.</para>
+ </step>
+ </procedure>
+ <para>You get the full font name (here,
+ <wordasword>Ordinary-Blackface</wordasword>) from the
+ <literal>zork.id</literal> which was created back in
+ <xref linkend="idfile"/> when we ran
+ <productname>afm2tfm</productname>. You must get this
+ exactly right, because it&apos;s the
+ <wordasword>official</wordasword> full name of the font,
+ and <trademark>PostScript</trademark> files using this
+ font need to match it.</para>
+ </step>
+ <step>
+ <title>Create a style file</title>
+ <para><LaTeX/> needs a style file to implement the
+ interface to the font. Call it after the typeface or
+ something related; in this example we&apos;ll call it
+ <filename>foozork.sty</filename>. In it go some details
+ of the name and date we did this, what version of
+ <LaTeX/> it needs, and any other command necessary to
+ operate the font, like the font encoding and whether it
+ is to supersede the current default Roman font.</para>
+ <procedure>
+ <step>
+ <para>Use your editor to open (create)
+ <filename>foozork.sty</filename> in your
+ <filename>texmf-local/tex/latex/psnfss</filename>
+ directory.</para>
+ </step>
+ <step>
+ <para>Insert the following lines:</para>
+ <programlisting>
+% foozork - created from foo for Zork
+\def\fileversion{1.0}
+\def\filedate{2002/12/03}
+\def\docdate{2002/12/03}
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{foozork}
+ [\filedate\space\fileversion\space
+ Zfonts Ordinary PSNFSS2e package]
+\RequirePackage[LY1]{fontenc}
+\renewcommand{\rmdefault}{zor}
+\endinput
+ </programlisting>
+ <para>Note the following:</para>
+ <itemizedlist>
+ <listitem>
+ <para>The first argument to
+ <command>ProvidesPackage</command>&nbsp;
+ <emphasis>must</emphasis> be the same as this
+ style file name; and that the font family is
+ referred to as <literal>zor</literal>, being the
+ foundry letter plus the fontname abbreviation.
+ This acts as a prefix for any/all font variants
+ (bold, italic, &etc;).</para>
+ </listitem>
+ <listitem>
+ <para>If you are not using Y&ampers;Y encoding,
+ omit the line referring to LY1 font
+ encoding.</para>
+ </listitem>
+ <listitem>
+ <para>If this is a typewriter font, make the
+ renewed command <command>rmdefault</command>
+ into <command>ttdefault</command>.</para>
+ </listitem>
+ <listitem>
+ <para>If it&apos;s a sans-serif font, make it
+ <command>sfdefault</command> instead.</para>
+ </listitem>
+ <listitem>
+ <para>Omit the command completely if you
+ don&apos;t want the style file to supersede the
+ current defaults but simply to make the font
+ available. If you do this, you probably want to
+ write a new command or two to use it, typically
+ one for grouped use and one for argument
+ use:</para>
+ </listitem>
+ </itemizedlist>
+ <programlisting width="footnotesize">
+\newcommand{\zorkfamily}{\fontencoding{LY1}%
+ \fontfamily{zor}\selectfont}
+\newcommand{\textzork}[1]{{\zorkfamily#1}}
+ </programlisting>
+ </step>
+ <step>
+ <para>Save and close the file.</para>
+ </step>
+ </procedure>
+ </step>
+ <step id="fdfiles">
+ <title>Create the Font Definition file</title>
+ <para>The last file to create is the <firstterm
+ id="fontdef">font definition</firstterm>
+ (<filename>.fd</filename>) file. This is named
+ following the pattern <literal>eeefnn.fd</literal>,
+ using the same conventions as before, by prepending the
+ (lowercase) encoding abbreviation to the foundry letter
+ and fontname abbreviation, so our example would be
+ <literal>ly1zor.fd</literal> for the LY1 encoding and
+ the <literal>zor</literal> short font name.</para>
+ <procedure>
+ <step>
+ <para>Use your editor to open (create)
+ <filename>texmf-local/tex/latex/psnfss/ly1zor.fd</filename></para>
+ </step>
+ <step>
+ <para>Enter the following lines:</para>
+ <programlisting><![CDATA[
+\ProvidesFile{ly1zor.fd}[2002/03/03 v0.1 manual
+ font definitions for LY1/zor.]
+
+\DeclareFontFamily{LY1}{zor}{}
+
+\DeclareFontShape{LY1}{zor}{k}{n}{<-> zorkly}{}
+\DeclareFontShape{LY1}{zor}{k}{sc}{<-> zorklyc}{}
+ ]]></programlisting>
+ </step>
+ <step>
+ <para>Save and close the file.</para>
+ </step>
+ </procedure>
+ <para>FD files typically use one
+ <command>DeclareFontFamily</command> command which
+ specifies the encoding and the short font name. Then as
+ many pairs of <command>DeclareFontShape</command>
+ commands as you converted fonts (assuming you did both
+ normal and small caps for each font: see
+ <xref linkend="sc"/>; if you didn&apos;t, then only one
+ such command per font is needed here). The arguments to
+ the <command>DeclareFontShape</command> command to watch
+ are the 3rd (weight/width), 4th (shape), and 5th (font
+ outline name): the rest are static for each
+ <filename>.fd</filename> file and simply identify the
+ encoding and the font family.</para>
+ <para>The codes to use are given on
+ pages&nbsp;414&ndash;15 of the <citetitle
+ ref="companion"></citetitle> and should also be in
+ your copies of
+ <filename>texmf/fontnames/weight.map</filename> and
+ <filename>texmf/fontnames/width.map</filename>. The
+ rules for combining weight and width need care: <acronym
+ ref="RTFM"></acronym> for
+ <methodname>fontname</methodname>. There is no
+ <filename>shape.map</filename> in
+ <methodname>fontname</methodname> because it&apos;s not
+ part of font file names, it&apos;s purely a <LaTeX/>
+ creation, so here&apos;s what the same book says:</para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec align="left"/>
+ <colspec align="left"/>
+ <thead>
+ <row>
+ <entry>Character</entry>
+ <entry>Meaning</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>n</literal></entry>
+ <entry>normal (upright)</entry>
+ </row>
+ <row>
+ <entry><literal>it</literal></entry>
+ <entry>italic</entry>
+ </row>
+ <row>
+ <entry><literal>sl</literal></entry>
+ <entry>slanted</entry>
+ </row>
+ <row>
+ <entry><literal>sc</literal></entry>
+ <entry>small caps</entry>
+ </row>
+ <row>
+ <entry><literal>ui</literal></entry>
+ <entry>upright italic</entry>
+ </row>
+ <row>
+ <entry><literal>ol</literal></entry>
+ <entry>outline</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>Add your own for other oddities, but be consistent:
+ I use <literal>cu</literal> for cursive (scripts), for
+ example, and <literal>k</literal> for blackletter faces
+ (not to be confused with <literal>k</literal> as a
+ <emphasis>width</emphasis> for
+ <wordasword>book</wordasword>).</para>
+ <para>The default fontspec
+ <literal><![CDATA[<->]]></literal> in the 5th argument
+ in the <command>DeclareFontShape</command> command means
+ that all sizes are to come from the same font outline
+ (remember if this was a &metafont; font with different
+ design sizes like <acronym ref="CM"></acronym> it would
+ be much more complex).</para>
+ <para>If the face has only a few variants, you can create
+ any other entries for bold, italic, slanted, &etc; with
+ the relevant weight and width and shape values pointing
+ at the relevant outline file.</para>
+ <para>If you want one font to substitute for a missing one
+ (for example italics to substitute for slanted in a
+ typeface which has no slanted variant of its own) give
+ the
+ <literal>ssub</literal> (<wordasword>silent
+ substitution</wordasword>) command in the fontspec:
+ for example to make all references to
+ <literal>sl</literal> (slanted) type use an existing
+ italic font, make the 5th argument like this:</para>
+ <programlisting><![CDATA[
+{<-> ssub * zor/m/it}
+ ]]></programlisting>
+ <para>If you find the x-height of a font too big or too
+ small to sort well with another font you are using, you
+ can specify an <literal>s</literal>
+ (<wordasword>scale</wordasword>) factor in this argument
+ instead: this example will shrink the result to
+ 80&percnt; of normal:</para>
+ <programlisting><![CDATA[
+{<-> s * [0.8] zorkly}
+ ]]></programlisting>
+ </step>
+ <step>
+ <title>Update the index and the map files</title>
+ <para>Run your <TeX/> indexer program (see <xref
+ linkend="texindex"/>) so that
+ <productname>updmap</productname> can find the files it
+ needs.</para>
+ <para>Then run <productname>updmap</productname> (just
+ type <systemitem>updmap</systemitem>). This updates the
+ maps and runs the <TeX/> indexer program again
+ automatically.</para>
+ </step>
+ </procedure>
+ <para>Now you can <literal>\usepackage{foozork}</literal> in
+ your <LaTeX/> file to make it the default font. To use the
+ font incidentally instead of as the default, you can
+ say:</para>
+ <programlisting>
+This is {\zorkfamily ZORK} or \textzork{ZORK}
+ </programlisting>
+ </sect2>
+ <sect2 id="type1cm">
+ <title>Installing the Type&nbsp;1 Computer Modern
+ fonts</title>
+ <para>Most new distributions of <LaTeX/> use the
+ <trademark>PostScript</trademark> Type&nbsp;1 versions of
+ the Computer Modern fonts. If your <LaTeX/> installation
+ uses the &metafont; (bitmap) versions of <acronym
+ ref="CM"></acronym>, you may want to switch to the
+ Type&nbsp;1 version, especially if you are going to be using
+ <productname>pdf<LaTeX/></productname> instead of standard
+ <LaTeX/>, because Acrobat Reader makes such a hames of
+ displaying Type3 fonts. <productname>GSview</productname>
+ and <productname>pdfview</productname> handle them
+ correctly.</para>
+ <para>To do this, install one of the sets of <acronym
+ ref="CM"></acronym> PostScript fonts. There are several
+ available:</para>
+ <itemizedlist>
+ <listitem>
+ <para>The fonts from BlueSky Research at <ulink
+ url="http://www.ctan.org/tex-archive/fonts/cm/ps-type1/bluesky/"></ulink></para>
+ </listitem>
+ <listitem>
+ <para><personname id="bkm">
+ <firstname>Basil&nbsp;K.</firstname>
+ <surname>Malyshev</surname>
+ </personname>&apos;s <wordasword>BaKoMa</wordasword>
+ fonts at <ulink
+ url="http://www.ctan.org/tex-archive/fonts/cm/ps-type1/bakoma/"></ulink></para>
+ </listitem>
+ <listitem>
+ <para><personname id="vv">
+ <firstname>Vladimir</firstname>
+ <surname>Volovich</surname>
+ </personname>&apos;s CM-Super at <ulink
+ url="http://www.ctan.org/tex-archive/fonts/ps-type1/cm-super/"></ulink></para>
+ </listitem>
+ <listitem>
+ <para><personname id="bj">
+ <firstname>Bogus&lstrok;aw</firstname>
+ <surname>Jackowski</surname>
+ </personname>&apos;s Latin Modern at <ulink
+ url="ftp://cam.ctan.org/tex-archive/fonts/ps-type1/lm.tar.gz"></ulink></para>
+ </listitem>
+ </itemizedlist>
+ <para>The BaKoMa fonts include the <acronym id="AMS">American
+ Mathematical Society</acronym> fonts for extended
+ mathematics, but are more complex to install because they
+ come with a special set of TFM files.</para>
+ <para>The BlueSky fonts are just <acronym ref="PFB"></acronym>
+ and AFM files, and are a drop-in replacement requiring no
+ further changes, as they use the same TFM files as the
+ &metafont; version. Follow the <filename>README</filename>
+ file in the downloadable archive for installation
+ instructions.</para>
+ <para>The Latin Modern and CM-Super fonts are new and I
+ haven&apos;t tested them but they are well spoken of.
+ Feedback on this is very welcome.</para>
+ <para>The <TeX/> Live and <TeX/> Collection distributions use
+ Type&nbsp;1 versions of Computer Modern by default. There
+ are more details in the FAQ at <ulink
+ url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=uselmfonts"></ulink>&thinsp;.</para>
+ </sect2>
+ </sect1>
+ </chapter>
+ <chapter id="macros">
+ <title>Programmability (macros)</title>
+ <indexterm>
+ <primary>macros</primary>
+ </indexterm>
+ <para>We&apos;ve touched several times on the ability of <LaTeX/>
+ to be reprogrammed. This is one of its central features, and one
+ that still, after nearly a quarter of a century, puts it well
+ above many other typesetting systems, even those with macro
+ systems of their own. It&apos;s also the one that needs most
+ foreknowledge, which is why this chapter is in this
+ position.</para>
+ <para><LaTeX/> is in fact itself just a collection of
+ macros&mdash;rather a big collection&mdash;written in
+ <TeX/>&apos;s internal typesetting language. These <firstterm
+ id="macs">macros</firstterm> are little program-like sets of
+ instructions with a name which can be used as shorthand for an
+ operation you wish to perform more than once.</para>
+ <para>Macros can be arbitrarily complex. Many of the ones used in
+ the standard <LaTeX/> packages are several pages long, but as we
+ will see, even short ones can very simply automate otherwise
+ tedious chores and allow the author to concentrate on
+ <emphasis>writing</emphasis>.</para>
+ <sect1 id="replacement">
+ <title>Simple replacement macros</title>
+ <para>In its simplest form, a <LaTeX/> macro can just be a
+ straightforward text replacement of a phrase to avoid
+ misspelling something each time you need it, &eg;</para>
+ <programlisting>
+\newcommand{\ef}{European Foundation for the
+ Improvement of Living and Working Conditions}
+ </programlisting>
+ <para>Put this in your preamble, and you can then use
+ <command>ef</command> in your document and it will typeset it
+ as the full text. Remember that after a command ending in a
+ letter you need to leave a space to avoid the next word
+ getting gobbled up as part of the command (see
+ <xref linkend="swallow"/>). And when you want to force a space
+ to be printed, use a backslash followed by a space,
+ &eg;</para>
+ <programlisting>
+The \ef\ is an institution of the Commission of the
+ European Union.
+ </programlisting>
+ <para>As you can see from this example, the
+ <command>newcommand</command> command takes two arguments:
+ <orderedlist>
+ <listitem>
+ <para>the name you want to give the new command</para>
+ </listitem>
+ <listitem>
+ <para>the expansion to be performed when you use it</para>
+ </listitem>
+ </orderedlist>, so there are always two sets of curly braces
+ after <command>newcommand</command>.</para>
+ </sect1>
+ <sect1 id="macinf">
+ <title>Macros using information gathered previously</title>
+ <para>A more complex example is the macro
+ <command>maketitle</command> which is used in almost every
+ formal document to format the title block. In the basic
+ document classes (book, report, and article) it performs small
+ variations on the layout of a centred block with the title
+ followed by the author followed by the date, as we saw in
+ <xref linkend="titling"/>.</para>
+ <para>If you inspect one of these document class files, such as
+ <filename>texmf/tex/latex/base/report.cls</filename> you will
+ see <command>maketitle</command> defined (and several variants
+ called <command>@maketitle</command> for use in different
+ circumstances). It uses the values for the title, author, and
+ date which are assumed already to have been stored in the
+ internal macros <command>@title</command>,
+ <command>@author</command>, and <command>@date</command> by
+ the author using the matching <command>title</command>,
+ <command>author</command>, and <command>date</command>
+ commands in the document.</para>
+ <para>This use of one command to store the information in
+ another is a common way of gathering the information from the
+ user. The use of macros containing the
+ <literal>@</literal> character prevents their accidental
+ misuse by the user: in fact to use them in your preamble we
+ have to allow the <literal>@</literal> sign to become a
+ <wordasword>letter</wordasword> so it can be recognised in a
+ command name, and remember to turn it off again afterwards
+ (see <xref linkend="makeat"/> below).</para>
+ <programlisting id="newtitle">
+\makeatletter
+\renewcommand{\maketitle}{%
+ \begin{flushleft}%
+ \sffamily
+ {\Large\bfseries\color{red}\@title\par}%
+ \medskip
+ {\large\color{blue}\@author\par}%
+ \medskip
+ {\itshape\color{green}\@date\par}%
+ \bigskip\hrule\vspace*{2pc}%
+ \end{flushleft}%
+}
+\makeatother
+ </programlisting>
+ <para>Insert this in the sample file on <xref linkend="oldtitle"
+ role="page"/> immediately before the
+ <literal>\begin{document}</literal> and remove the
+ <literal>\color{...}</literal> commands from the title,
+ author, and date. Re-run the file through <LaTeX/>, and you
+ should get something like this:</para>
+ <graphic fileref="newtitle" width="75%" contentwidth="1cm"/>
+ <para>In this redefinition of <command>maketitle</command>,
+ we&apos;ve done the following:</para>
+ <orderedlist>
+ <listitem id="makeat">
+ <para>Enclosed the changes in
+ <command>makeatletter</command> and
+ <command>makeatother</command> to allow us to use the
+ <literal>@</literal> sign in command names;<footnote>
+ <para>If you move all this preamble into a style file of
+ your own, you don&apos;t need these commands: the use
+ of <literal>@</literal> signs in command names is
+ allowed in style and class files.</para>
+ </footnote></para>
+ </listitem>
+ <listitem>
+ <para>Used <command>renewcommand</command> and put
+ <command>maketitle</command> in curly braces after
+ it;</para>
+ </listitem>
+ <listitem>
+ <para>Opened a pair of curly braces to hold the new
+ definition. The closing curly brace is immediately before
+ the <command>makeatother</command>;</para>
+ </listitem>
+ <listitem>
+ <para>Inserted a <modespec>flushleft</modespec> environment
+ so the whole title block is left-aligned;</para>
+ </listitem>
+ <listitem>
+ <para>Used <command>sffamily</command> so the whole title
+ block is in the defined sans-serif typeface;</para>
+ </listitem>
+ <listitem>
+ <para>For each of <command>@title</command>,
+ <command>@author</command>, and <command>@date</command>,
+ we have used some font variation and colour, and enclosed
+ each one in curly braces to restrict the changes just to
+ each command. The closing <command>par</command> makes
+ sure that multiline title and authors and dates get
+ typeset with the relevant line-spacing;</para>
+ </listitem>
+ <listitem>
+ <para>Added some flexible space between the lines, and
+ around the <command>hrule</command> (horizontal rule) at
+ the end;</para>
+ </listitem>
+ </orderedlist>
+ <para>Note the <literal>%</literal> signs after any line ending
+ in a curly brace, to make sure no intrusive white-space find
+ its way into the output. These aren&apos;t needed after simple
+ commands where there is no curly brace because excess
+ white-space gets gobbled up there anyway.</para>
+ </sect1>
+ <sect1 id="macargs">
+ <title>Macros with arguments</title>
+ <para>But macros are not limited to text expansion. They can
+ take arguments of their own, so you can define a command to do
+ something with specific text you give it. This makes them much
+ more powerful and generic, as you can write a macro to do
+ something a certain way, and then use it hundreds of times
+ with a different value each time.</para>
+ <para>We looked earlier (<xref linkend="emph"/>) at making new
+ commands to put specific classes of words into certain fonts,
+ such as product names into italics, keywords into bold, and so
+ on. Here&apos;s an example for a command
+ <command>product</command>, which also indexes the product
+ name and adds a trademark sign:</para>
+ <programlisting>
+\newcommand{\product}[1]{%
+ \textit{#1}\texttrademark%
+ \index{#1@\textit{#1}}%
+}
+ </programlisting>
+ <para>If I now type <literal>\tmproduct{Velcro}</literal> then I
+ get <productname>Velcro</productname>&trade; typeset, and if
+ you look in the index, you&apos;ll find this page referenced
+ under <wordasword><format
+ fontshape="it">Velcro</format></wordasword>. Let&apos;s
+ examine what this does:</para>
+ <orderedlist>
+ <listitem>
+ <para>The macro is specified as having one argument
+ (that&apos;s the <literal>[1]</literal> in the
+ definition). This will
+ be the product name you type in curly braces when you use
+ <command>product</command>. Macros can have up to nine
+ arguments.</para>
+ </listitem>
+ <listitem>
+ <para>The expansion of the macro is contained in the second
+ set of curly braces, spread over several lines (see <xref
+ linkend="macrolines" remap="item"/> for why).</para>
+ </listitem>
+ <listitem>
+ <para>It prints the value of the first argument (that&apos;s
+ the <literal>#1</literal>) in italics, which is
+ conventional for product names, and adds the
+ <command>texttrademark</command> command.</para>
+ </listitem>
+ <listitem>
+ <para>Finally, it creates an index entry using the same
+ value (<literal>#1</literal>), making sure that it&apos;s
+ italicised in the index (see <xref
+ linkend="indextypo"/> to remind yourself of how indexing
+ something in a different font works).</para>
+ </listitem>
+ <listitem id="macrolines">
+ <para>Typing this macro over several lines makes it easier
+ for humans to read. I could just as easily have
+ typed</para>
+ <programlisting colwidth="left" width="footnotesize">
+\newcommand{\product}[1]{\textit{#1}\index{#1@\textit{#1}}}
+ </programlisting>
+ <para>but it wouldn&apos;t have been as clear what I was
+ doing.</para>
+ <para>One thing to notice is that to prevent unwanted spaces
+ creeping into the output when <LaTeX/> reads the macro, I
+ ended each line with a comment character
+ (<systemitem>%</systemitem>). <LaTeX/> normally treats
+ newlines as spaces when formatting (remember <xref
+ linkend="comment"/>), so this stops the end of line
+ being turned into an unwanted space when the macro is
+ used. <LaTeX/> always ignores spaces at the
+ <emphasis>start</emphasis> of macro lines anyway, so
+ indenting lines for readability is fine.</para>
+ </listitem>
+ </orderedlist>
+ <para>In <link linkend="hyph"></link> we mentioned the problem
+ of frequent use of unbreakable text leading to poor
+ justification or to hyphenation problems. A solution is to
+ make a macro which puts the argument into an
+ <command>mbox</command> with the appropriate font change, but
+ precedes it all with a conditional
+ <command>linebreak</command> which will make it more
+ attractive to <TeX/> to start a new line.</para>
+ <programlisting>
+\newcommand{\var}[1]{\linebreak[3]\mbox{\ttfamily#1}}
+ </programlisting>
+ <para>This only works effectively if you have a reasonably wide
+ setting and paragraphs long enough for the differences in
+ spacing elsewhere to get hidden. If you have to do this in
+ narrow journal columns, you may have to adjust wording and
+ spacing by hand occasionally.</para>
+ </sect1>
+ <sect1 id="macnest">
+ <title>Nested macros</title>
+ <para>Here&apos;s a slightly more complex example, where one
+ macro calls another. It&apos;s common in normal text to refer
+ to people by their forename and surname (in that order), for
+ example <personname remap="dk">
+ <firstname>Don</firstname>
+ <surname> Knuth</surname>
+ </personname>, but to have them indexed as <emphasis>surname,
+ forename</emphasis>. This pair of macros,
+ <command>person</command> and <command>reindex</command>,
+ automates that process to minimize typing and indexing.</para>
+ <programlisting>
+\newcommand{\person}[1]{#1\reindex #1\sentinel}
+\def\reindex #1 #2\sentinel{\index{#2, #1}}
+ </programlisting>
+ <orderedlist>
+ <listitem>
+ <para>The digit 1 in square brackets means that
+ <command>person</command> has one argument, so you put the
+ whole name in a single set of curly braces, &eg;
+ <literal>\person{Don Knuth}</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>The first thing the macro does is output
+ <literal>#1</literal>, which is the value of what you typed,
+ just as it stands, so the whole name gets typeset exactly
+ as you typed it.</para>
+ </listitem>
+ <listitem>
+ <para>But then it uses a special feature of Plain <TeX/>
+ macros (which use <command>def</command> instead of
+ <LaTeX/>&apos;s <command>newcommand</command><footnote>
+ <para>Don&apos;t try this at home alone, children! This
+ one is safe enough, but you should strictly avoid
+ <command>def</command> for a couple of years. Stick to
+ <command>newcommand</command> for now.</para>
+ </footnote>): they too can have multiple arguments but you
+ can separate them with other characters (here a space) to
+ form a pattern which <TeX/> will recognise when reading the
+ arguments.</para>
+ <para>In this example (<command>reindex</command>) it&apos;s
+ expecting to see a string of characters
+ (<literal>#1</literal>) followed by a space, followed by
+ another string of characters (<literal>#2</literal>)
+ followed by a dummy command (<command>sentinel</command>).
+ In effect this makes it a device for splitting a name into
+ two halves on the space between them, so the two halves
+ can be handled separately. The <command>reindex</command>
+ command can now read the two halves of the name
+ separately.</para>
+ </listitem>
+ <listitem>
+ <para>The <command>person</command> command invokes
+ <command>reindex</command> and follows it with the name
+ you typed plus the dummy command
+ <command>sentinel</command> (which is just there to signal
+ the end of the name). Because <command>reindex</command>
+ is expecting two arguments separated by a space and
+ terminated by a <command>sentinel</command>, it sees
+ <wordasword><literal>Don</literal> and
+ <literal>Knuth</literal></wordasword> as two separate
+ arguments.</para>
+ <para>It can therefore output them using
+ <command>index</command> in reverse order, which is
+ exactly what we want.</para>
+ </listitem>
+ </orderedlist>
+ <para>A book or report with a large number of personal names to
+ print and index could make significant use of this to allow
+ them to be typed as
+ <literal>\person{Leslie Lamport}</literal> and printed as
+ <personname id="ll">
+ <firstname>Leslie</firstname>
+ <surname>Lamport</surname>
+ </personname>, but have them indexed as
+ <quote>Lamport,&nbsp;Leslie</quote> with virtually no effort
+ on the author&apos;s part at all.</para>
+ <example>
+ <title>Other names</title>
+ <para>Try to work out how to make this
+ <command>person</command> feature work with names
+ like:</para>
+ <simplelist>
+ <member>Blanca Maria Bartosova de Paul</member>
+ <member>Patricia Maria Soria de Miguel</member>
+ <member>Arnaud de la Villèsbrunne</member>
+ <member>Prince</member>
+ <member>Pope John Paul II</member>
+ </simplelist>
+ <para>Hints: the command <command>space</command> produces a
+ normal space, and one way around <LaTeX/>&apos;s requirements
+ on spaces after command names ending with a letter is to
+ follow such commands with an empty set of curly braces
+ <literal>{}</literal>.</para>
+ </example>
+ </sect1>
+ <sect1 id="macenv">
+ <title>Macros and environments</title>
+ <para>As mentioned in <xref linkend="fancybox"/>, it is possible
+ to define macros to capture text in an environment and reuse
+ it afterwards. This avoids any features of the subsequent use
+ affecting the formatting of the text.</para>
+ <para>One example of this uses the facilities of the
+ <methodname>fancybox</methodname> package, which defines a
+ variety of framed boxes to highlight your text, and a special
+ environment <modespec>Sbox</modespec> which
+ <quote>captures</quote> your text for use in these
+ boxes.</para>
+ <informalexample>
+ <programlisting>
+\begin{Sbox}
+\begin{minipage}{3in}
+This text is formatted to the specifications
+of the minipage environment in which it
+occurs.
+
+Having been typeset, it is held in the Sbox
+until it is needed, which is after the end
+of the minipage, where you can (for example)
+align it and put it in a special framed box.
+\end{minipage}
+\end{Sbox}
+\begin{flushright}
+\shadowbox{\theSbox}
+\end{flushright}
+ </programlisting>
+ <sidebar>
+ <para>This text is formatted to the specifications of the
+ minipage environment in which it occurs.</para>
+ <para>Having been typeset, it is held in the Sbox until it
+ is needed, which is after the end of the minipage, where
+ you can (for example) centre it and put it in a special
+ framed box.</para>
+ </sidebar>
+ </informalexample>
+ <para>By putting the text (here in a
+ <modespec>minipage</modespec> environment because we want to
+ change the width) inside the <modespec>Sbox</modespec>
+ environment, it is typeset into memory and stored in the macro
+ <command>theSbox</command>. It can then be used afterwards as
+ the argument of the <command>shadowbox</command> command (and
+ in this example it has also been centred).</para>
+ </sect1>
+ <sect1 id="reprog">
+ <title>Reprogramming <LaTeX/>&apos;s internals</title>
+ <para><LaTeX/>&apos;s internal macros can also be reprogrammed or
+ even rewritten entirely, although doing this can require a
+ considerable degree of expertise. Simple changes, however, are
+ easily done.</para>
+ <para>Recall that <LaTeX/>&apos;s default document structure for
+ the Report document class uses Chapters as the main unit of
+ text, whereas in reality most reports are divided into
+ Sections, not Chapters (<xref linkend="repchap"/>). The result
+ of this is that if you start off your report with
+ <literal>\section{Introduction}</literal>, it will print
+ as</para>
+ <para><format fontseries="b" fontstep="Large"
+ struts="vert">0.1&emsp;Introduction</format></para>
+ <para role="cont">which is not at all what you want. The zero is
+ caused by it not being part of any chapter. But this numbering
+ is controlled by macros, and you can redefine them. In this
+ case it&apos;s a macro called <literal>\thesection</literal>
+ which reproduces the current section number counter (see <xref
+
+ linkend="thecounter"/>). It&apos;s redefined afresh in each
+ document class file, using the command
+ <command>renewcommand</command> (in this case in
+ <filename>texmf/tex/latex/base/report.cls</filename>):</para>
+ <programlisting>
+\renewcommand \thesection
+ {\thechapter.\@arabic\c@section}
+ </programlisting>
+ <para>You can see it invokes <command>thechapter</command>
+ (which is defined elsewhere to reproduce the value of the
+ <varname role="counter">chapter</varname> counter), and it
+ then prints a dot, followed by the Arabic value of the counter
+ called <varname role="counter">section</varname> (that
+ <literal>\c@</literal> notation is <LaTeX/>&apos;s internal way
+ of referring to counters). You can redefine this in your
+ preamble to simply leave out the reference to chapters:</para>
+ <programlisting>
+\renewcommand{\thesection}{\arabic{section}}
+ </programlisting>
+ <para>I&apos;ve used the more formal method of enclosing the
+ command being redefined in curly braces. For largely
+ irrelevant historical reasons these braces are often omitted
+ in <LaTeX/>&apos;s internal code (as you may have noticed in
+ the example earlier). And I&apos;ve also used the
+ <wordasword>public</wordasword> macro
+ <command>arabic</command> to output the value of <varname
+ role="counter">section</varname> (<LaTeX/>&apos;s internals
+ use a <wordasword>private</wordasword> set of control
+ sequences containing <literal>@</literal>-signs, designed to
+ protect
+ them against being changed accidentally).</para>
+ <para>Now the introduction to your report will start
+ with:</para>
+ <para><format fontseries="b" fontstep="Large"
+ struts="vert">1&emsp;Introduction</format></para>
+ <para>What&apos;s important is that you <emphasis>don&apos;t
+ ever</emphasis> need to alter the original document class
+ file <filename>report.cls</filename>: you just copy the
+ command you need to change into your own document preamble,
+ and modify that instead. It will then override the
+ default.</para>
+ <sect2 id="bullets">
+ <title>Changing list item bullets</title>
+ <para>As mentioned <link linkend="labelitem">earlier</link>,
+ here&apos;s how to redefine a bullet for an itemized list,
+ with a slight tweak:</para>
+ <programlisting>
+\usepackage{bbding}
+\renewcommand{\labelitemi}{%
+ \raisebox{-.25ex}{\PencilRight}}
+ </programlisting>
+ <para>Here we use the <methodname>bbding</methodname> package
+ which has a large selection of
+ <wordasword>dingbats</wordasword> or little icons, and we
+ make the label for top-level itemized lists print a
+ right-pointing pencil (the names for the icons are in the
+ package documentation: see <xref linkend="packagedoc"/> for
+ how to get it).</para>
+ <para>In this case, we are using the
+ <command>raisebox</command> command within the redefinition
+ because it turns out that the symbols in this font are
+ positioned slightly too high for the typeface we&apos;re
+ using. The <command>raisebox</command> command takes two
+ arguments: the first is a dimension, how much to raise the
+ object by (and a negative value means
+ <wordasword>lower</wordasword>: there is no need for a
+ <literal>\lowerbox</literal> command); and the second is
+ the text you want to affect. Here, we are shifting the
+ symbol down by &frac14;ex (see <xref linkend="dimensions"/>
+ for a
+ list of dimensions <LaTeX/> can use).</para>
+ <para>There is a vast number of symbols available: see
+ <citetitle ref="symbol-list"></citetitle> for a
+ comprehensive list.</para>
+ </sect2>
+ </sect1>
+ </chapter>
+ <chapter id="compat">
+ <title>Compatibility with other systems</title>
+ <para>As we saw in <xref linkend="plaintext"/>, <LaTeX/> uses
+ plain-text files, so they can be read and written by any
+ standard application that can open text files. This helps
+ preserve your information over time, as the plain-text format
+ cannot be obsoleted or hijacked by any manufacturer or sectoral
+ interest, and it will always be readable on any computer, from
+ your handheld (yes, <LaTeX/> is available for some <acronym
+ ref="PDA"></acronym>s, see <xref linkend="zaurus"/>) to the
+ biggest supercomputer.</para>
+ <figure id="zaurus">
+ <title><LaTeX/> editing and processing on the Sharp Zaurus 5500
+ PDA</title>
+ <graphic fileref="zedit" width="30%"/>
+ <graphic fileref="zlatex" width="30%"/>
+ <graphic fileref="qpdf" width="30%"/>
+ </figure>
+ <para>However, <LaTeX/> is intended as the last stage of the
+ editorial process: formatting for print or display. If you have
+ a requirement to re-use the text in some other
+ environment&mdash;a database perhaps, or on the Web or a
+ <acronym ref="CD-ROM" condition="noid"></acronym> or <acronym
+ ref="DVD"></acronym>, or in Braille or voice output&mdash;then
+ it should probably be edited, stored, and maintained in
+ something neutral like the <acronym id="XML"
+ xreflabel="http://www.ucc.ie/xml/">Extensible Markup
+ Language</acronym>, and only converted to <LaTeX/> when a
+ typeset copy is needed.</para>
+ <para>Although <LaTeX/> has many structured-document features in
+ common with <acronym ref="SGML"></acronym> and <acronym
+ ref="XML"></acronym>, it can still only be processed by the
+ <LaTeX/> and <productname>pdf<LaTeX/></productname> programs.
+ Because its macro features make it almost infinitely
+ redefinable, processing it requires a program which can unravel
+ arbitrarily complex macros, and <LaTeX/> and its siblings are
+ the only programs which can do that effectively. Like other
+ typesetters and formatters (Quark
+ <productname>XPress</productname>,
+ <productname>PageMaker</productname>,
+ <productname>FrameMaker</productname>, Microsoft
+ <productname>Publisher</productname>, <productname
+ remap="3">3B2</productname> &etc;), <LaTeX/> is largely a
+ one-way street leading to typeset printing or display
+ formatting.</para>
+ <para>Converting <LaTeX/> to some other format therefore means you
+ will unavoidably lose some formatting, as <LaTeX/> has features
+ that others systems simply don&apos;t possess, so they cannot be
+ translated&mdash;although there are several ways to minimise
+ this loss. Similarly, converting other formats into <LaTeX/>
+ often means editing back the stuff the other formats omit
+ because they only store appearances, not structure.</para>
+ <para>However, there are at least two excellent systems for
+ converting <LaTeX/> directly to <acronym id="HTML">HyperText
+ Markup Language</acronym> so you can publish it on the web, as
+ we shall see in <xref
+ linkend="latexto"/>.</para>
+ <sect1 id="tolatex">
+ <title>Converting into <LaTeX/></title>
+ <para>There are several systems which will save their text in
+ <LaTeX/> format. The best known is probably the <LyX/> editor
+ (see <xref linkend="lyxwin"/>), which is a wordprocessor-like
+ interface to <LaTeX/> for Windows and Unix. Both the
+ <productname>AbiWord</productname> and
+ <productname>Kword</productname> wordprocessors on Linux
+ systems have a very good <function>Save
+ As</function>&hellip;<LaTeX/> output, so they can be used to
+ open Microsoft <productname>Word</productname> documents and
+ convert to
+ <LaTeX/>. Several maths packages like the
+ <productname>EuroMath</productname> editor, and the
+ <productname>Mathematica</productname> and
+ <productname>Maple</productname> analysis packages, can also
+ save material in <LaTeX/> format.</para>
+ <para>In general, most other wordprocessors and DTP systems
+ either don&apos;t have the level of internal markup
+ sophistication needed to create a <LaTeX/> file, or they lack
+ a suitable filter to enable them to output what they do have.
+ Often they are incapable of outputting any kind of structured
+ document, because they only store what the text looks like,
+ not why it&apos;s there or what role it fulfills. There are
+ two ways out of this:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Use the <guimenu>File</guimenu><guimenuitem>Save
+ As&hellip;</guimenuitem> menu item to save the
+ wordprocessor file as <acronym ref="HTML"></acronym>,
+ rationalise the <acronym ref="HTML"></acronym> using
+ <personname id="raggett">
+ <firstname>Dave</firstname>
+ <surname> Raggett</surname>
+ </personname>&apos;s <ulink
+ url="http://tidy.sourceforge.net/"><productname>HTML
+ Tidy</productname></ulink>, and convert the resulting
+ <acronym id="XHTML">Extensible HyperText Markup
+ Language</acronym> to <LaTeX/> with any of the standard
+ <acronym ref="XML"></acronym> tools (see below).</para>
+ </listitem>
+ <listitem>
+ <para>Use a specialist conversion tool like EBT&apos;s
+ <productname>DynaTag</productname> (supposedly available
+ from Enigma, if you can persuade them they have a copy to
+ sell you; or you may still be able to get it from <ulink
+ url="http://www.rbii.com/">Red Bridge
+ Interactive</ulink> in Providence, RI). It&apos;s
+ expensive and they don&apos;t advertise it, but for bulk
+ conversion of consistently-marked
+ <productname>Word</productname> files into XML it beats
+ everything else hands down. The
+ <productname>Word</productname> files
+ <emphasis>must</emphasis> be consistent, though, and must
+ use named styles from a stylesheet, otherwise no system on
+ earth is going to be able to guess what it means.</para>
+ </listitem>
+ </itemizedlist>
+ <para>There is of course a third way, suitable for large volumes
+ only: send it off to the Pacific Rim to be retyped into XML or
+ <LaTeX/>. There are hundreds of companies from India to
+ Polynesia who do this at high speed and low cost with very
+ high accuracy. It sounds crazy when the document is already in
+ electronic form, but it&apos;s a good example of the problem
+ of low quality of wordprocessor markup that this solution
+ exists at all.</para>
+ <para>You will have noticed that most of the solutions lead to
+ one place: <acronym ref="SGML"></acronym><footnote>
+ <para>The <acronym id="SGML">Standard Generalized Markup
+ Language</acronym> itself is little used now for new
+ projects, as the software support for its daughter
+ <acronym ref="XML"></acronym> is far greater, but there
+ are still hundreds of large document repositories in
+ <acronym ref="SGML"></acronym> still growing their
+ collection by adding documents.</para>
+ </footnote> or <acronym ref="XML"></acronym>. As explained
+ above and elsewhere, these formats are the only ones devised
+ so far capable of storing sufficient information in
+ machine-processable, publicly-accessible form to enable your
+ document to be recreated in multiple output formats. Once
+ your document is in <acronym ref="XML"></acronym>, there is a
+ large range of software available to turn it into other
+ formats, including <LaTeX/>. Processors in any of the common
+ <acronym ref="SGML"></acronym>/<acronym ref="XML"></acronym>
+ processing languages like the <acronym id="DSSSL">Document
+ Style Semantics and Specification Language</acronym>, the
+ <acronym id="XSLT">Extensible Stylesheet Language
+ [Transformations]</acronym>,
+ <productname>Omnimark</productname>,
+ <productname>Metamorphosis</productname>,
+ <productname>Balise</productname>, &etc; can easily be written
+ to output <LaTeX/>, and this approach is extremely
+ common.</para>
+ <para>Much of this will be simplified when wordprocessors
+ support native, arbitrary <acronym
+ ref="XML"></acronym>/<acronym ref="XSLT"></acronym> as a
+ standard feature, because <LaTeX/> output will become much
+ simpler to produce.</para>
+ <itemizedlist>
+ <listitem>
+ <para>Sun&apos;s <productname>Star Office</productname> and
+ its Open Source sister,
+ <productname>OpenOffice</productname>, have used XML as
+ their native file format for several years, and there is a
+ project at the <acronym id="OASIS">Organisation for the
+ Advancement of Structured Information Systems</acronym>
+ for developing a common <acronym ref="XML"></acronym>
+ office file format based on those used by these two
+ packages, which has been proposed to the <acronym
+ id="ISO">International Organization for
+ Standardization</acronym> in Geneva as a candidate for
+ an International Standard.</para>
+ </listitem>
+ <listitem>
+ <para><productname>WordPerfect</productname> has also had a
+ native <acronym ref="SGML"></acronym> (and now <acronym
+ ref="XML"></acronym>) editor for many years, which will
+ work with any <acronym id="DTD">Document Type
+ Definition</acronym> (but not a Schema; and at the time
+ of writing (2005) it still used a proprietary stylesheet
+ format).</para>
+ </listitem>
+ <listitem>
+ <para>Microsoft has had a half-hearted <wordasword>Save
+ As&hellip;XML</wordasword> for a while, using an
+ internal and formerly largely undocumented Schema
+ (recently published at last). The
+ <wordasword>Professional</wordasword> versions of
+ <productname>Word</productname> and
+ <productname>Excel</productname> in
+ <productname>Office&nbsp;11</productname> (Office 2003 for
+ XP) now have full support for arbitrary Schemas and a real
+ <acronym ref="XML"></acronym> editor, albeit with a rather
+ primitive interface, but there is no conversion to or from
+ <productname>Word</productname>'s
+ <filename>.doc</filename> format.<footnote>
+ <para>Which is silly, given that Microsoft used to make
+ one of the best
+ <productname>Word</productname>-to-<acronym
+ ref="SGML"></acronym> converters ever, which was
+ bi-directional (yes, it could round-trip
+ <productname>Word</productname> to <acronym
+ ref="SGML"></acronym> and back to
+ <productname>Word</productname> and back into <acronym
+ ref="SGML"></acronym>). But they dropped it on the
+ floor when <acronym ref="XML"></acronym>
+ arrived.</para>
+ </footnote></para>
+ <para>However, help comes in the shape of <personname
+ id="rd">
+ <firstname>Ruggero</firstname>
+ <surname>Dambra</surname>
+ </personname>&apos;s
+ <productname>WordML2<LaTeX/></productname>, which is an
+ <acronym ref="XSLT"></acronym> stylesheet to transform an
+ <acronym ref="XML"></acronym> document in this internal
+ Schema (WordML) into <LaTeXe/> format.
+ Download it from any <acronym ref="CTAN"></acronym> server
+ in <filename>/support/WordML2LaTeX</filename>.</para>
+ </listitem>
+ <listitem id="rtf2latex2e">
+ <para>Among the conversion programs on <acronym
+ ref="CTAN"></acronym> is <personname id="us">
+ <firstname>Ujwal</firstname>
+ <surname>Sath&shy;yam</surname>
+ </personname>&apos;s
+ <productname>rtf2latex2e</productname>, which converts
+ <acronym id="RTF">Rich Text Format</acronym> files (output
+ by many wordprocessors) to <LaTeXe/>. The package
+ description says it has support
+ for figures and tables, equations are read as figures, and
+ it can the handle the latest <acronym ref="RTF"></acronym>
+ versions from Microsoft Word 97/98/2000, StarOffice, and
+ other wordprocessors. It runs on Macs, Linux, other Unix
+ systems, and Windows.</para>
+ </listitem>
+ </itemizedlist>
+ <para>When these efforts coalesce into generalised support for
+ arbitrary <acronym ref="DTD"></acronym>s and Schemas, it will
+ mean a wider choice of editing interfaces, and when they
+ achieve the ability to run <acronym ref="XSLT"></acronym>
+ conversion into
+ <LaTeX/> from within these editors, such as is done at the
+ moment with <productname>Emacs</productname> or
+ <productname>XML Spy</productname>, we will have full
+ convertability.</para>
+ <sect2>
+ <title>Getting <LaTeX/> out of XML</title>
+ <para>Assuming you can get your document out of its
+ wordprocessor format into <acronym ref="XML"></acronym> by
+ some method, here is a very brief example of how to turn it
+ into <LaTeX/>.</para>
+ <para>You can of course buy and install a fully-fledged
+ commercial <acronym ref="XML"></acronym> editor with
+ <acronym ref="XSLT"></acronym> support, and run this
+ application within it. However, this is beyond the reach of
+ many users, so to do this unaided you just need to install
+ three pieces of software: <ulink
+ url="http://java.sun.com/j2se/1.4.2/download.html"><productname>Java</productname></ulink>,
+ <ulink
+ url="http://saxon.sourceforge.net/"><productname>Saxon</productname></ulink>
+ and the <ulink
+ url="http://www.docbook.org/xml/4.2/index.html">DocBook
+ 4.2 DTD</ulink> (<acronym ref="URI"></acronym>s are
+ correct at the time of writing). None of these has a visual
+ interface: they are run from the command-line in the same
+ way as is possible with <LaTeX/>.</para>
+ <para>As an example, let&apos;s take the above paragraph, as
+ typed or imported into <productname>AbiWord</productname>
+ (see
+ <xref linkend="abidoc"/>). This is stored as a single
+ paragraph with highlighting on the product names (italics),
+ and the names are also links to their Internet sources, just
+ as they are in this document. This is a convenient way to
+ store two pieces of information in the same place.</para>
+ <figure id="abidoc">
+ <title>Sample paragraph in
+ <productname>AbiWord</productname> converted to <acronym
+ ref="XML"></acronym></title>
+ <graphic fileref="abiword" width="100%"/>
+ </figure>
+ <para><productname>AbiWord</productname> can export in DocBook
+ format, which is an <acronym ref="XML"></acronym> vocabulary
+ for describing technical (computer)
+ documents&ndash;it&apos;s what I use for this book.
+ <productname>AbiWord</productname> can also export <LaTeX/>,
+ but we&apos;re going make our own
+ version, working from the <acronym ref="XML"></acronym>
+ (Brownie points for the reader who can guess why I&apos;m
+ not just accepting the <LaTeX/> conversion output).</para>
+ <para>Although <productname>AbiWord</productname>&apos;s
+ default is to output an <acronym
+ ref="XML"></acronym>&nbsp;<sgmltag>book</sgmltag> document
+ type, we&apos;ll convert it to a <LaTeX/> article document
+ class. Notice that <productname>AbiWord</productname> has
+ correctly output the expected section and title markup
+ empty, even though it&apos;s not used. Here&apos;s the
+ <acronym ref="XML"></acronym> output (I&apos;ve changed the
+ linebreaks to keep it within the bounds of this page
+ size):</para>
+ <programlisting width="tiny"><![CDATA[
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<book>
+<!-- ===================================================================== -->
+<!-- This DocBook file was created by AbiWord. -->
+<!-- AbiWord is a free, Open Source word processor. -->
+<!-- You may obtain more information about AbiWord at www.abisource.com -->
+<!-- ===================================================================== -->
+ <chapter>
+ <title></title>
+ <section role="unnumbered">
+ <title></title>
+ <para>You can of course buy and install a fully-fledged commercial XML
+editor with XSLT support, and run this application within it. However, this
+is beyond the reach of many users, so to do this unaided you just need to
+install three pieces of software: <ulink
+url="http://java.sun.com/j2se/1.4.2/download.html"><emphasis>Java</emphasis></ulink>,
+<ulink
+url="http://saxon.sourceforge.net"><emphasis>Saxon</emphasis></ulink>, and
+the <ulink url="http://www.docbook.org/xml/4.2/index.html">DocBook 4.2 DTD</ulink>
+(URIs are correct at the time of writing). None of these has a visual
+interface: they are run from the command-line in the same way as is possible
+with L<superscript>A</superscript>T<subscript>E</subscript>X.</para>
+ </section>
+ </chapter>
+</book>
+ ]]></programlisting>
+ <para>The <acronym ref="XSLT"></acronym> language lets us
+ create templates for each type of element in an <acronym
+ ref="XML"></acronym> document. In our example, there are
+ only three which need handling, as we did not create chapter
+ or section titles (DocBook requires them to be present, but
+ they don&apos;t have to be used).</para>
+ <itemizedlist>
+ <listitem>
+ <para><sgmltag>para</sgmltag>, for the
+ paragraph[s];</para>
+ </listitem>
+ <listitem>
+ <para><sgmltag>ulink</sgmltag>, for the URIs;</para>
+ </listitem>
+ <listitem>
+ <para><sgmltag>emphasis</sgmltag>, for the
+ italicisation.</para>
+ </listitem>
+ </itemizedlist>
+ <para>I&apos;m going to cheat over the superscripting and
+ subscripting of the letters in the <LaTeX/> logo, and use my
+ editor to replace the whole thing with the
+ <command>LaTeX</command> command. In the other three cases,
+ we already know how <LaTeX/> deals with these, so we can
+ write our templates (see <xref linkend="xslcode"/>).</para>
+ <figure id="xslcode">
+ <title><acronym ref="XSLT"></acronym> script to convert the
+ paragraph</title>
+ <programlisting width="footnotesize"><![CDATA[
+<?xml version="1.0" encoding="utf-8"?>
+<xsl:stylesheet
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0">
+ <xsl:output method="text"/>
+
+ <xsl:template match="/">
+ <xsl:text>\documentclass{article}
+\usepackage{url}</xsl:text>
+ <xsl:apply-templates/>
+ </xsl:template>
+
+ <xsl:template match="book">
+ <xsl:text>\begin{document}</xsl:text>
+ <xsl:apply-templates/>
+ <xsl:text>\end{document}</xsl:text>
+ </xsl:template>
+
+ <xsl:template match="para">
+ <xsl:apply-templates/>
+ <xsl:text>&#x000A;</xsl:text>
+ </xsl:template>
+
+ <xsl:template match="ulink">
+ <xsl:apply-templates/>
+ <xsl:text>\footnote{\url{</xsl:text>
+ <xsl:value-of select="@url"/>
+ <xsl:text>}}</xsl:text>
+ </xsl:template>
+
+ <xsl:template match="emphasis">
+ <xsl:text>\emph{</xsl:text>
+ <xsl:apply-templates/>
+ <xsl:text>}</xsl:text>
+ </xsl:template>
+
+</xsl:stylesheet>
+ ]]></programlisting>
+ </figure>
+ <para>If you run this through
+ <productname>Saxon</productname>, which is an <acronym
+ ref="XSLT"></acronym> processor, you can output a <LaTeX/>
+ file which you can process and view (see <xref
+ linkend="paraview"/>).</para>
+ <programlisting width="scriptsize"><![CDATA[
+$ java -jar /usr/local/saxonb8-0/saxon8.jar -o para.ltx \
+para.dbk para.xsl
+$ latex para.ltx
+This is TeX, Version 3.14159 (Web2C 7.3.7x)
+(./para.ltx
+LaTeX2e <2001/06/01>
+Loading CZ hyphenation patterns: Pavel Sevecek, v3, 1995
+Loading SK hyphenation patterns: Jana Chlebikova, 1992
+Babel <v3.7h> and hyphenation patterns for english,
+dumylang, nohyphenation, czech, slovak, german, ngerman,
+danish, spanish, catalan, finnish, french, ukenglish, greek,
+croatian, hungarian, italian, latin, mongolian, dutch,
+norwegian, polish, portuguese, russian, ukrainian,
+serbocroat, swedish, loaded.
+(/usr/TeX/texmf/tex/latex/base/article.cls
+Document Class: article 2001/04/21 v1.4e Standard LaTeX
+document class (/usr/TeX/texmf/tex/latex/base/size10.clo))
+(/usr/TeX/texmf/tex/latex/ltxmisc/url.sty) (./para.aux)
+[1] (./para.aux) )
+Output written on para.dvi (1 page, 1252 bytes).
+Transcript written on para.log.
+$ xdvi para &
+ ]]></programlisting>
+ <figure id="paraview">
+ <title>Displaying the typeset paragraph</title>
+ <graphic fileref="para" width="60%"/>
+ <programlisting width="scriptsize"><![CDATA[
+\documentclass{article}\usepackage{url}\begin{document}
+
+ You can of course buy and install a fully-fledged commercial
+XML editor with XSLT support, and run this application within it.
+However, this is beyond the reach of many users, so to do this
+unaided you just need to install three pieces of software:
+\emph{Java}\footnote{\url{http://java.sun.com/j2se/1.4.2/download.html}},
+\emph{Saxon}\footnote{\url{http://saxon.sourceforge.net}}, and the
+DocBook 4.2 DTD\footnote{\url{http://www.docbook.org/xml/4.2/index.html}}
+(URIs are correct at the time of writing). None of these has a visual
+interface: they are run from the command-line in the same way as is
+possible with \LaTeX.
+
+\end{document}
+ ]]></programlisting>
+ </figure>
+ <para>Writing <acronym ref="XSLT"></acronym> is not hard, but
+ requires a little learning. The output method here is
+ <literal>text</literal>, which is <LaTeX/>&apos;s file
+ format (<acronym ref="XSLT"></acronym> can also output
+ <acronym ref="HTML"></acronym> and other formats of
+ XML).</para>
+ <orderedlist>
+ <listitem>
+ <para>The first template matches
+ <wordasword><literal>/</literal></wordasword>, which is
+ the document root (before the <sgmltag>book</sgmltag>
+ start-tag). At this stage we output the text
+ <literal>\documentclass{article}</literal> and
+ <literal>\usepackage{url}</literal>. The
+ <wordasword><literal>apply-templates</literal></wordasword>
+ instructions tells the processor to carry on processing,
+ looking for more matches. <acronym ref="XML"></acronym>
+ comments get ignored, and any elements which don&apos;t
+ match a template simply have their contents passed
+ through until the next match occurs.</para>
+ </listitem>
+ <listitem>
+ <para>The <sgmltag>book</sgmltag> template outputs the
+ <literal>\begin{document}</literal> and the
+ <literal>\end{document}</literal> commands, and between
+ them to carry on processing.</para>
+ </listitem>
+ <listitem>
+ <para>The <sgmltag>para</sgmltag> template just outputs
+ its content, but follows it with a linebreak (using the
+ hexadecimal character code <literal>x000A</literal> (see
+ the <acronym ref="ASCII"></acronym> chart in <xref
+ linkend="asciicodes"/>).</para>
+ </listitem>
+ <listitem>
+ <para>The <sgmltag>ulink</sgmltag> template outputs its
+ content but follows it with a footnote using the
+ <command>url</command> command to output the value of
+ the <sgmltag>url</sgmltag> attribute.</para>
+ </listitem>
+ <listitem>
+ <para>The <sgmltag>emphasis</sgmltag> template surrounds
+ its content with <literal>\emph{</literal> and
+ <literal>}</literal>.</para>
+ </listitem>
+ </orderedlist>
+ <para>This is a relatively trivial example, but it serves to
+ show that it&apos;s not hard to output <LaTeX/> from
+ <acronym ref="XML"></acronym>. In fact there is a set of
+ templates already written to produce <LaTeX/> from a DocBook
+ file at
+ <ulink
+ url="http://www.dpawson.co.uk/docbook/tools.html#d4e2905"></ulink></para>
+ </sect2>
+ </sect1>
+ <sect1 id="latexto">
+ <title>Converting out of <LaTeX/></title>
+ <para>This is much harder to do comprehensively. As noted
+ earlier, the <LaTeX/> file format really requires the <LaTeX/>
+ program itself in order to process all the packages and
+ macros, because there is no telling what complexities authors
+ have added themselves (what a lot of this book is
+ about!).</para>
+ <para>Many authors and editors rely on custom-designed or
+ homebrew converters, often written in the standard shell
+ scripting languages (Unix shells, Perl, Python, Tcl, etc).
+ Although some of the packages presented here are also written
+ in the same languages, they have some advantages and
+ restrictions compared with private conversions:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Conversion done with the standard utilities (eg awk,
+ tr, sed, grep, detex, etc) can be faster for
+ <foreignphrase>ad hoc</foreignphrase> translations, but it
+ is easier to obtain consistency and a more sophisticated
+ final product using
+ <LaTeX/>2<acronym ref="HTML"></acronym> or
+ <TeX/>4ht&mdash;or one of the other systems
+ available.</para>
+ </listitem>
+ <listitem>
+ <para>Embedding additional non-standard control sequences in
+ <LaTeX/> source code may make it harder to edit and
+ maintain, and will definitely make it harder to port to
+ another system.</para>
+ </listitem>
+ <listitem>
+ <para>Both the above methods (and others) provide a fast and
+ reasonable reliable way to get documents authored in
+ <LaTeX/> onto the Web in an acceptable&mdash;if not
+ optimal&mdash;format.</para>
+ </listitem>
+ <listitem>
+ <para><LaTeX/>2<acronym ref="HTML"></acronym> was written to
+ solve the problem of getting <LaTeX/>-with-mathematics
+ onto the Web, in the days before MathML and math-capable
+ browsers.
+ <TeX/>4ht was written to turn <LaTeX/> documents into Web
+ hypertext&mdash;mathematics or not.</para>
+ </listitem>
+ </itemizedlist>
+ <sect2>
+ <title>Conversion to <productname>Word</productname></title>
+ <para>There are several programs on <acronym
+ ref="CTAN"></acronym> to do
+ <LaTeX/>-to-<productname>Word</productname> and similar
+ conversions, but they do not all handles everything <LaTeX/>
+ can throw at them, and some only handle a subset of the
+ built-in commands of default
+ <LaTeX/>. Two in particular, however, have a good
+ reputation, although I haven&apos;t used either of them (I
+ stay as far away from <productname>Word</productname> as
+ possible):</para>
+ <itemizedlist>
+ <listitem>
+ <para><productname>latex2rtf</productname> by <personname
+ id="wh">
+ <firstname>Wilfried</firstname>
+ <surname>Hennings</surname>
+ </personname>, <personname id="fd">
+ <firstname>Fernando</firstname>
+ <surname>Dorner</surname>
+ </personname>, and <personname id="ag">
+ <firstname>Andreas</firstname>
+ <surname>Granzer</surname>
+ </personname> translates
+ <LaTeX/> into <acronym ref="RTF"></acronym>&mdash;the
+ opposite of the <productname>rtf2latex2e</productname>
+ mentioned in <xref linkend="rtf2latex2e"/>. <acronym
+ ref="RTF"></acronym> can be read by most
+ wordprocessors, and this program preserves layout and
+ formatting for most <LaTeX/> documents using standard
+ built-in commands.</para>
+ </listitem>
+ <listitem>
+ <para><personname id="kac">
+ <firstname>Kirill</firstname>
+ <othername>A</othername>
+ <surname>Chikrii</surname>
+ </personname>&apos;s <productname
+ remap="tex2word"><TeX/>2Word</productname> for
+ Microsoft Windows is a converter plug-in for
+ <productname>Word</productname> to let it open <TeX/>
+ and <LaTeX/> documents. The author&apos;s company claims
+ that <quote>virtually any existing <TeX/>/<LaTeX/>
+ package can be supported by <productname
+ remap="tex2word"><TeX/>2Word</productname></quote>
+ because it is customisable.</para>
+ </listitem>
+ </itemizedlist>
+ <para>One easy route into wordprocessing, however, is the
+ reverse of the procedures suggested in the preceding
+ section: convert <LaTeX/> to <acronym ref="HTML"></acronym>,
+ which many wordprocessors read easily. The following
+ sections cover two packages for this.</para>
+ </sect2>
+ <sect2>
+ <title><productname
+ remap="latex2html"><LaTeX/>2HTML</productname></title>
+ <para>As its name suggests, <LaTeX/>2<acronym
+ ref="HTML"></acronym> is a system to convert <LaTeX/>
+ structured documents to <acronym ref="HTML"></acronym>. Its
+ main task is to reproduce the document structure as a set of
+ interconnected <acronym ref="HTML"></acronym> files. Despite
+ using Perl,
+ <LaTeX/>2<acronym ref="HTML"></acronym> relies very heavily
+ on standard Unix facilities like the
+ <productname>NetPBM</productname> graphics package and the
+ pipe syntax. Microsoft Windows is not well suited to this
+ kind of composite processing, although all the required
+ facilities are available for download in various forms and
+ should in theory allow the package to run&mdash;but reports
+ of problems are common.</para>
+ <itemizedlist>
+ <listitem>
+ <para>The sectional structure is preserved, and
+ navigational links are generated for the standard Next,
+ Previous, and Up directions.</para>
+ </listitem>
+ <listitem>
+ <para>Links are also used for the cross-references,
+ citations, footnotes, ToC, and lists of figures and
+ tables.</para>
+ </listitem>
+ <listitem>
+ <para>Conversion is direct for common elements like lists,
+ quotes, paragraph-breaks, type-styles, etc, where there
+ is an obvious <acronym ref="HTML"></acronym>
+ equivalent.</para>
+ </listitem>
+ <listitem>
+ <para>Heavily formatted objects such as math and diagrams
+ are converted to images.</para>
+ </listitem>
+ <listitem>
+ <para>There is no support for homebrew macros.</para>
+ </listitem>
+ </itemizedlist>
+ <para>There is, however, support for arbitrary hypertext
+ links, symbolic cross-references between <quote>evolving
+ remote documents</quote>, conditional text, and the
+ inclusion of raw <acronym ref="HTML"></acronym>. These are
+ extensions to
+ <LaTeX/>, implemented as new commands and
+ environments.</para>
+ <para><LaTeX/>2<acronym ref="HTML"></acronym> outputs a
+ directory named after the input filename, and all the output
+ files are put in that directory, so the output is
+ self-contained and can be uploaded to a server as it
+ stands.</para>
+ </sect2>
+ <sect2>
+ <title><productname
+ remap="tex4ht"><TeX/>4ht</productname></title>
+ <para><TeX/>4ht operates differently from
+ <LaTeX/>2<acronym ref="HTML"></acronym>: it uses the <TeX/>
+ program to process the file, and handles conversion in a set
+ of postprocessors for the common <LaTeX/> packages. It can
+ also output to <acronym ref="XML"></acronym>, including
+ <acronym id="TEI">Text Encoding Initiative</acronym> and
+ DocBook, and the OpenOffice and WordXML formats, and it can
+ create <TeX/>info format
+ manuals.</para>
+ <para>By default, documents retain the single-file structure
+ implied by the original, but there is again a set of
+ additional configuration directives to make use of the
+ features of hypertext and navigation, and to split files for
+ ease of use.</para>
+ </sect2>
+ <sect2>
+ <title>Extraction from PS and PDF</title>
+ <para>If you have the full version of Adobe
+ <productname>Acrobat</productname>, you can open a <acronym
+ ref="PDF"></acronym> file created by
+ <productname>pdf<LaTeX/></productname>, select and copy all
+ the text, and paste it into <productname>Word</productname>
+ and some other wordprocessors, and retain some common
+ formatting of headings, paragraphs, and lists. Both
+ solutions still require the wordprocessor text to be edited
+ into shape, but they preserve enough of the formatting to
+ make it worthwhile for short documents. Otherwise, use the
+ <productname>pdftotext</productname> program to extract
+ everything from the <acronym ref="PDF"></acronym> file as
+ plain (paragraph-formatted) text.</para>
+ </sect2>
+ <sect2>
+ <title>Last resort: strip the markup</title>
+ <para>At worst, the <productname>detex</productname> program
+ on <acronym ref="CTAN"></acronym> will strip a <LaTeX/> file
+ of all markup and leave just the raw unformatted text, which
+ can then be re-edited. There are also programs to extract
+ the raw text from <acronym ref="DVI"></acronym> and <acronym
+ id="PS">PostScript</acronym> files.</para>
+ </sect2>
+ </sect1>
+<!--
+ <sect1 id="beyondlatex">
+ <title>Going beyond <LaTeX/></title>
+ <para>The reader will have deduced by now that while <LaTeX/> is
+ possibly the best programmable formatter around, the <LaTeX/>
+ file format is not generally usable with anything except the
+ <LaTeX/> program. <LaTeX/> was originally written in the
+ mid-1980s, about the same time as the <acronym
+ id="SGML">Standard Generalized Markup Language</acronym>,
+ but the two projects were not related. However, <TeX/> and
+ <LaTeX/> have proved such useful tools for formatting <acronym
+ ref="SGML"></acronym> and more recently <acronym
+ ref="XML"></acronym> that many users chose this route for
+ their output, using conversions written in the languages
+ already mentioned in <xref linkend="latexto"/>.</para>
+ <para>Unfortunately, when the rise of the Web in the early 1990s
+ popularised <acronym ref="SGML"></acronym> using the <acronym
+ id="HTML">HyperText Markup Language</acronym>, browser
+ writers deliberately chose to encourage authors to ignore the
+ rules of <acronym ref="SGML"></acronym>. Robust auto-converted
+ formatting therefore became almost impossible except via the
+ browsers&apos; low-quality print routines.</para>
+ <para>It was not until 1997, when the <acronym
+ id="XML">Extensible Markup Language</acronym> was devised,
+ that it again became possible to provide the structural and
+ descriptive power of <acronym ref="SGML"></acronym> but
+ without the complex and rarely-used options which had made
+ standard <acronym ref="SGML"></acronym> so difficult to
+ program for.</para>
+ <para><acronym ref="XML"></acronym> is now becoming the
+ principal system of markup. Because it is based on the
+ international standard (<acronym ref="SGML"></acronym>), it is
+ not proprietary, so it has been implemented on most platforms,
+ and there is lots of free software supporting it as well as
+ many commercial packages. Like <acronym ref="SGML"></acronym>,
+ it is actually a meta-language to let you define your own
+ markup, so it is much more flexible than <acronym
+ ref="HTML"></acronym>. Implementations of the companion
+ <acronym id="XSL">Extensible Stylesheet Language</acronym>
+ provide a direct route to <acronym ref="PDF"></acronym> but at
+ the expense of reinventing most of the wheels which <LaTeX/>
+ already possesses, so the sibling <acronym
+ id="XSLT">Extensible Stylesheet Language:
+ Transformations</acronym> can be used instead to translate
+ to <LaTeX/> source code. This is usually much faster than
+ writing your own formatting from scratch in <acronym
+ ref="XSL"></acronym>, and it means that you can take full
+ advantage of the packages and sophistication of <LaTeX/>. A
+ similar system is used for the Linux Documentation Project,
+ which uses <acronym ref="SGML"></acronym> transformed by the
+ <acronym id="DSSSL">Document Style Semantics and Specification
+ Language</acronym> to <TeX/></para>
+ <para>The source code of this book, available online at
+ <ulink
+ url="http://www.ctan.org/tex-archive/info/beginlatex/src/"></ulink>
+ includes XSLT which does exactly this.</para>
+ <sect2 id="xml">
+ <title>Lightning tutorial on XML</title>
+ <para>To use XML for authoring (writing) you need a template
+ or description of the type of document you want to create.
+ This is called a <acronym id="DTD">Document Type
+ Description</acronym>, and there are lots of them
+ available to download for different types of document. Some
+ popular ones are:</para>
+ <informaltable>
+ <tgroup cols="3">
+ <colspec align="left"/>
+ <colspec align="left"/>
+ <colspec align="left"/>
+ <tbody>
+ <row>
+ <entry>DocBook</entry>
+ <entry>Computer documentation</entry>
+ <entry><ulink url="http://www.docbook.org/"></ulink></entry>
+ </row>
+ <row>
+ <entry><acronym id="TEI">Text Encoding
+ Initiative</acronym></entry>
+ <entry>Literary and historical texts</entry>
+ <entry><ulink url="http://www.tei-c.org/"></ulink></entry>
+ </row>
+ <row>
+ <entry><acronym ref="XHTML"></acronym></entry>
+ <entry>XML version of <acronym ref="HTML"></acronym></entry>
+ <entry><ulink url="http://www.w3.org/"></ulink></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>A newer format for document structure specification is a
+ the Schema, which performs a similar function to a DTD but
+ allows programs to carry out a higher level of
+ data-checking. DTDs are used to control document structure
+ rather than textual content. Schemas are thus better-suited
+ than DTDs for use in e-commerce document types like invoices,
+ bills of lading, and Web transactions, and in the internal
+ controls of computing like configuration files. W3C Schemas
+ are written in XML itself, so programmers can use them more
+ easily, whereas DTDs and the RelaxNG version of Schemas are
+ written in a slightly different syntax. Many DTDs are
+ available in Schema format as well, so in effect you can use
+ either.</para>
+ <sect3 id="xmled">
+ <title>Editors</title>
+ <para>A DTD or Schema is used with an XML editor to guide
+ the writing/editing process by specifying the document
+ <emphasis>structure</emphasis>&mdash;where things can
+ go&mdash;so you&apos;ll also need an XML editor.</para>
+ <para>There are many to choose from: I use
+ <productname>Emacs</productname>, same as I do for
+ <LaTeX/>, because it&apos;s free and very powerful, and
+ there are <wordasword>modes</wordasword> (plug-ins) like
+ <productname>psgml</productname> and
+ <productname>xxml</productname> which make it easy to
+ handle XML. Among other XML document editors are
+ <productname>XMetaL</productname> (formerly from SoftQuad,
+ now from Corel); <productname>EPIC</productname>
+ (ArborText); <productname>WordPerfect</productname> (also
+ Corel); <productname>epcEdit</productname> (epcEdit); and
+ most recently even Microsoft
+ <productname>Word-11</productname> (Professional version
+ only). Editors like <productname>OxyGen</productname>
+ (http://www.oxygenxml.com/) and <productname>XML
+ Spy</productname> (http://www.altova.com) are
+ more like <productname>Emacs</productname> with
+ programming development tools for <acronym
+ ref="XSLT"></acronym>.</para>
+ </sect3>
+ <sect3>
+ <title>XML principles</title>
+ <para>XML, like SGML before it, works by enclosing your text
+ in markup which identifies it. The markup is composed of
+ <firstterm id="element">elements</firstterm> made up of
+ <firstterm id="tag">tags</firstterm> in pointy brackets: a
+ start-tag at the start and an end-tag at the end. <LaTeX/>
+ users have no problem in recognising the principles
+ immediately, although the syntax differs a little. Those
+ familiar with <acronym ref="HTML"></acronym> will also recognise this method. Here
+ is the example from <xref
+ linkend="demodoc"/> expressed in XML using the DocBook
+ DTD</para>
+ <programlisting><![CDATA[
+<?xml version="1.0"?>
+<!DOCTYPE sect1 SYSTEM "/dtds/docbook/docbookx.dtd" [
+<!ENTITY LaTeX "\LaTeX{}">
+]>
+<sect1>
+ <title>My first document</title>
+ <para>This is a short example of a <LaTeX/> document I wrote on
+ <systemitem class="resource" lang="LaTeX">\today</systemitem>. It
+ shows a few simple features of automated typesetting,
+ including</para>
+ <itemizedlist>
+ <listitem>
+ <para>setting the default font size to 12pt;</para>
+ </listitem>
+ <listitem>
+ <para>specifying <methodname>article</methodname> type
+ formatting;</para>
+ </listitem>
+ <listitem>
+ <para>using the Palatino typeface;</para>
+ </listitem>
+ <listitem>
+ <para>adding special formatting for <acronym ref="URI"></acronym>s;</para>
+ </listitem>
+ <listitem>
+ <para>formatting a heading in <methodname>section</methodname>
+ style;</para>
+ </listitem>
+ <listitem>
+ <para>using the <LaTeX/> logo;</para>
+ </listitem>
+ <listitem>
+ <para>generating today&apos;s date;</para>
+ </listitem>
+ <listitem>
+ <para>formatting a list of items;</para>
+ </listitem>
+ <listitem>
+ <para>centering and italicizing;</para>
+ </listitem>
+ <listitem>
+ <para>autonumbering the pages.</para>
+ </listitem>
+ </itemizedlist>
+ <sect2>
+ <title>More information</title>
+ <para>This example was taken from <link linkend="fi"
+ remap="title"></link>, which you can download from <link
+ linkend="fi" remap="url"></link> and use as a teach-yourself
+ guide.</para>
+ <sidebar>
+ <para remap="\itshape">Have a nice day!</para>
+ </sidebar>
+ </sect2>
+ <bibliography>
+ <biblioentry id="fi">
+ <articleinfo>
+ <author>
+ <surname>Flynn</surname>
+ <firstname>Peter</firstname>
+ </author>
+ <title>Formatting Information</title>
+ </articleinfo>
+ <title>TUGboat</title>
+ <volumenum>23</volumenum>
+ <issuenum>2</issuenum>
+ <date>2002</date>
+ <artpagenums>115-250</artpagenums>
+ <address>http://www.ctan.org/tex-archive/info/beginlatex/</address>
+ </biblioentry>
+ </bibliography>
+</sect1>
+ ]]></programlisting>
+ </sect3>
+ </sect2>
+ <sect2 id="xslt">
+ <title>Brief tutorial on converting XML to <LaTeX/></title>
+ <para>[to be written]</para>
+ </sect>
+ </sect1>
+-->
+ </chapter>
+ <appendix id="cnf">
+ <title>Configuring <TeX/> search paths</title>
+ <para><TeX/> systems run on a huge variety of platforms, and are
+ typically made up of a large number of rather small files. Some
+ computer operating systems have problems with packages like
+ this, as their built-in methods for searching for a file when
+ needed are poor.</para>
+ <para>To get around this, <TeX/> uses a technique borrowed from the
+ Unix world, based on a simple hash index for each directory they
+ need to look in. This is known as the ls-R database, from the
+ Unix command (<literal>ls -R</literal>) which creates it. The
+ program which does this for <TeX/> is actually called after this
+ command: <productname>mktexlsr</productname>, although it may be
+ renamed <productname>texhash</productname> or something else on
+ your system. This is the program referred to in <xref
+ linkend="texindex"/>.</para>
+ <para>However, to know where to make these indexes, and thus where
+ to search, <TeX/> needs to be told about them. In a standard
+ <TeX/> installation this information is in
+ <filename>texmf/web2c/texmf.cnf</filename>. The file is similar
+ to a Unix shell script, but the only lines of significance for
+ the search paths are the following (this is how they appear in
+ the default Unix installation, omitting the comments):</para>
+ <programlisting>
+TEXMFMAIN = /usr/TeX/texmf
+TEXMFLOCAL = /usr/TeX/texmf-local
+HOMETEXMF = $HOME/texmf
+TEXMF = {$HOMETEXMF,!!$TEXMFLOCAL,!!$TEXMFMAIN}
+SYSTEXMF = $TEXMF
+VARTEXFONTS = /var/lib/texmf
+TEXMFDBS = $TEXMF;$VARTEXFONTS
+ </programlisting>
+ <para>As you can see, this defines where the main <TeX/>/&metafont;
+ directory is, where the local one is, and where the user&apos;s
+ personal (home) one is. It then defines the order in which they
+ are searched, and makes this the system-wide list. A temporary
+ directory for bitmap fonts is set up, and added to the list,
+ defining the places in which <productname>texhash</productname>
+ or <productname>mktexlsr</productname> creates its
+ databases.</para>
+ <para>In some installations, the local directory is set up in
+ <filename>/usr/local/share/texmf</filename> or
+ <filename>/usr/share/texmf.local</filename> or similar
+ variations, so you would substitute this name for
+ <filename>/usr/TeX/texmf-local</filename>. Under Microsoft
+ Windows, the names will be full paths such as
+ <filename>C:\Program Files\TeXLive\texmf</filename>. On an Apple
+ Mac, it might be <filename>Hard
+ Disk:TeX:texmf</filename>.</para>
+ <para>If you edit plain-text configuration files with anything
+ other than a plain-text editor (&eg;&nbsp;a wordprocessor), or
+ if you edit them with a plain-text editor which has been set to
+ word-wrap long lines, make sure you turn line-wrapping
+ <emphasis>off</emphasis> so that any long lines are preserved in
+ their correct format.</para>
+ </appendix>
+ <appendix id="tugform">
+ <title><TeX/> Users Group membership</title>
+ <para>The <acronym id="TUG"><TeX/> Users Group</acronym> was
+ founded in 1980 for educational and scientific purposes: to
+ provide an organization for those who have an interest in
+ typography and font design, and are users of the <TeX/>
+ typesetting system invented by Donald Knuth.
+ TUG is run by and for its members and represents the interests
+ of <TeX/> users worldwide.</para>
+ <section>
+ <title>TUG membership benefits</title>
+ <para>Members of TUG help to support and promote the use of
+ <TeX/>, &metafont;, and related systems worldwide. All members
+ receive <citetitle ref="tugboat" show="title"></citetitle>,
+ the journal of the <TeX/> Users Group, the <TeX/> Live software
+ distribution (a runnable <TeX/> system), and the <acronym
+ ref="CTAN"></acronym> software distribution (containing most
+ of the <acronym ref="CTAN"></acronym> archive).</para>
+ <para>In addition, TUG members vote in TUG elections, and
+ receive discounts on annual meeting fees, store purchases, and
+ TUG-sponsored courses. TUG membership (less benefits) is
+ tax-deductible, at least in the USA. See the TUG Web site for
+ details.</para>
+ </section>
+ <section>
+ <title>Becoming a TUG member</title>
+ <para>Please see the forms and information at <ulink
+ url="http://www.tug.org/join.html"></ulink>. You can join
+ online, or by filling out a paper form. The NTG (Dutch) and
+ UKTUG (United Kingdom) <TeX/> user groups have joint membership
+ agreements with TUG whereby you can receive a discount for
+ joining both user groups. To do this, please join via <ulink
+ url="http://www.ntg.nl/newmember.html"></ulink> (the NTG
+ membership page) or <ulink
+ url="http://uk.tug.org/Membership/"></ulink> (the UKTUG
+ page), respectively, and select the option for joint
+ membership.</para>
+ <para>Each year&apos;s membership entitles you to the software and
+ TUGboat produced for that year (even if it is produced in a
+ subsequent calendar year, as is currently the case with
+ TUGboat). You can order older issues of TUGboat and <TeX/>
+ memorabilia through the TUG store (<ulink
+ url="http://www.tug.org/store"></ulink>).</para>
+ <para>The current TUG membership fee is &dollar;65 (US) per year
+ for individuals and &dollar;35 for students and seniors. Add
+ &dollar;10 to the membership fee after May 31 to cover
+ additional shipping and processing costs. The current rate for
+ non-voting subscription memberships (for libraries, for
+ example) is &dollar;85. The current institutional rate is
+ &dollar;500, which includes up to seven individual
+ memberships.</para>
+ </section>
+ <section>
+ <title>Privacy</title>
+ <para>TUG uses your personal information only to mail you
+ products, publications, notices, and (for voting members)
+ official ballots. Also, if you give explicit agreement, we may
+ incorporate it into a membership directory which will be made
+ available only to TUG members.</para>
+ <para>TUG neither sells its membership list nor provides it to
+ anyone outside of its own membership.</para>
+ </section>
+ </appendix>
+ <appendix id="asciicharset">
+ <title>The ASCII character set</title>
+ <para>The American Standard Code for Information Interchange was
+ invented in 1963, and after some redevelopment settled down in
+ 1984 as standard X3.4 of <acronym id="ANSI">American National
+ Standards Institute</acronym>. It represents the 95 basic
+ codes for the unaccented printable characters and punctuation of
+ the Latin alphabet, plus 33 internal <quote>control
+ characters</quote> originally intended for the control of
+ computers, programs, and external devices like printers and
+ screens.</para>
+ <para>Many other character sets (strictly speaking,
+ <quote>character repertoires</quote>) have been standardised for
+ accented Latin characters and for all other non-Latin writing
+ systems, but these are intended for representing the symbols
+ people use when writing text on computers. Most programs and
+ computers use <acronym ref="ASCII"></acronym> internally for all
+ their coding, the exceptions being <acronym
+ ref="XML"></acronym>-based languages like <acronym
+ ref="XSLT"></acronym>, which are inherently designed to be
+ usable with any writing system, and a few specialist systems
+ like APL.</para>
+ <para>Although the <TeX/> and <LaTeX/> file formats can easily be
+ used with many other encoding systems (see the discussion of the
+ <methodname>inputenc</methodname> in <xref
+ linkend="accents"/>), they are based on <acronym
+ ref="ASCII"></acronym>. It is therefore important to know
+ where to find <emphasis>all</emphasis> 95 of the printable
+ characters, as some of them are not often used in other
+ text-formatting systems. The following table shows all 128
+ characters, with their decimal, octal (base-8), and hexadecimal
+ (base-16) code numbers.</para>
+ <table colsep="1mm" rowsep="1mm" id="asciicodes">
+ <title>The ASCII characters</title>
+ <tgroup cols="10">
+ <colspec charoff="$\enspace" role="$" align="right" colsep="flush"/>
+ <colspec colwidth="1cm" align="center" role="\ttfamily"/>
+ <colspec colwidth="1cm" align="center" role="\ttfamily"/>
+ <colspec colwidth="1cm" align="center" role="\ttfamily"/>
+ <colspec colwidth="1cm" align="center" role="\ttfamily"/>
+ <colspec colwidth="1cm" align="center" role="\ttfamily"/>
+ <colspec colwidth="1cm" align="center" role="\ttfamily"/>
+ <colspec colwidth="1cm" align="center" role="\ttfamily"/>
+ <colspec colwidth="1cm" align="center" role="\ttfamily"/>
+ <colspec charoff="$" role="\enspace$" align="left" colsep="flush"/>
+ <thead>
+ <row>
+ <entry condition="nomath">Oct</entry>
+ <entry>0</entry>
+ <entry>1</entry>
+ <entry>2</entry>
+ <entry>3</entry>
+ <entry>4</entry>
+ <entry>5</entry>
+ <entry>6</entry>
+ <entry>7</entry>
+ <entry condition="nomath">Hex</entry>
+ </row>
+ </thead>
+ <tfoot>
+ <row>
+ <entry></entry>
+ <entry>8</entry>
+ <entry>9</entry>
+ <entry>A</entry>
+ <entry>B</entry>
+ <entry>C</entry>
+ <entry>D</entry>
+ <entry>E</entry>
+ <entry>F</entry>
+ <entry></entry>
+ </row>
+ </tfoot>
+ <tbody>
+ <row>
+ <entry>'00&uarr;</entry>
+ <entry remap="The null character">NUL</entry>
+ <entry remap="Start of heading">SOH</entry>
+ <entry remap="Start of text">STX</entry>
+ <entry remap="End of text">ETX</entry>
+ <entry remap="End of transmission">EOT</entry>
+ <entry remap="Enquire">ENQ</entry>
+ <entry remap="Acknowledge">ACK</entry>
+ <entry remap="Bell">BEL</entry>
+ <entry>''0&uarr;</entry>
+ </row>
+ <row>
+ <entry>'01&uarr;</entry>
+ <entry remap="Backspace">BS</entry>
+ <entry remap="Horizontal TAB">HT</entry>
+ <entry remap="Line feed">LF</entry>
+ <entry remap="Vertical TAB">VT</entry>
+ <entry remap="Form feed">FF</entry>
+ <entry remap="Carriage return">CR</entry>
+ <entry remap="Shift out">SO</entry>
+ <entry remap="Shift in">SI</entry>
+ <entry>''0&darr;</entry>
+ </row>
+ <row>
+ <entry>'02&uarr;</entry>
+ <entry remap="Data link escape">DLE</entry>
+ <entry remap="Device control 1">DC1</entry>
+ <entry remap="Device control 2">DC2</entry>
+ <entry remap="Device control 3">DC3</entry>
+ <entry remap="Device control 4">DC4</entry>
+ <entry remap="Neg.\ acknowledge">NAK</entry>
+ <entry remap="Synchronize">SYN</entry>
+ <entry remap="End transmission block">ETB</entry>
+ <entry>''1&uarr;</entry>
+ </row>
+ <row>
+ <entry>'03&uarr;</entry>
+ <entry remap="Cancel">CAN</entry>
+ <entry remap="End of medium">EM</entry>
+ <entry remap="Substitute">SUB</entry>
+ <entry remap="Escape">ESC</entry>
+ <entry remap="File separator">FS</entry>
+ <entry remap="Group separator">GS</entry>
+ <entry remap="Record separator">RS</entry>
+ <entry remap="Unit separator">US</entry>
+ <entry>''1&darr;</entry>
+ </row>
+ <row>
+ <entry>'04&uarr;</entry>
+ <entry remap="Space"></entry>
+ <entry remap="Exclamation mark">!</entry>
+ <entry remap="Double quote">"</entry>
+ <entry remap="Hash (pound)">&hash;</entry>
+ <entry remap="Dollar">&dollar;</entry>
+ <entry remap="Percent">&percnt;</entry>
+ <entry remap="Ampersand">&ampers;</entry>
+ <entry remap="Apostrophe">'</entry>
+ <entry>''2&uarr;</entry>
+ </row>
+ <row>
+ <entry>'05&uarr;</entry>
+ <entry remap="Open parenthesis">(</entry>
+ <entry remap="Close parenthesis">)</entry>
+ <entry remap="Asterisk">*</entry>
+ <entry remap="Plus">+</entry>
+ <entry remap="Comma">,</entry>
+ <entry remap="Minus">-</entry>
+ <entry remap="Full point (period)">.</entry>
+ <entry remap="Slash">/</entry>
+ <entry>''2&darr;</entry>
+ </row>
+ <row>
+ <entry>'06&uarr;</entry>
+ <entry>0</entry>
+ <entry>1</entry>
+ <entry>2</entry>
+ <entry>3</entry>
+ <entry>4</entry>
+ <entry>5</entry>
+ <entry>6</entry>
+ <entry>7</entry>
+ <entry>''3&uarr;</entry>
+ </row>
+ <row>
+ <entry>'07&uarr;</entry>
+ <entry>8</entry>
+ <entry>9</entry>
+ <entry remap="Colon">:</entry>
+ <entry remap="Semicolon">;</entry>
+ <entry remap="Less than">&lessthan;</entry>
+ <entry remap="Equals">=</entry>
+ <entry remap="Greater than">&greaterthan;</entry>
+ <entry remap="Question mark">?</entry>
+ <entry>''3&darr;</entry>
+ </row>
+ <row>
+ <entry>'10&uarr;</entry>
+ <entry remap="At">@</entry>
+ <entry>A</entry>
+ <entry>B</entry>
+ <entry>C</entry>
+ <entry>D</entry>
+ <entry>E</entry>
+ <entry>F</entry>
+ <entry>G</entry>
+ <entry>''4&uarr;</entry>
+ </row>
+ <row>
+ <entry>'11&uarr;</entry>
+ <entry>H</entry>
+ <entry>I</entry>
+ <entry>J</entry>
+ <entry>K</entry>
+ <entry>L</entry>
+ <entry>M</entry>
+ <entry>N</entry>
+ <entry>O</entry>
+ <entry>''4&darr;</entry>
+ </row>
+ <row>
+ <entry>'12&uarr;</entry>
+ <entry>P</entry>
+ <entry>Q</entry>
+ <entry>R</entry>
+ <entry>S</entry>
+ <entry>T</entry>
+ <entry>U</entry>
+ <entry>V</entry>
+ <entry>W</entry>
+ <entry>''5&uarr;</entry>
+ </row>
+ <row>
+ <entry>'13&uarr;</entry>
+ <entry>X</entry>
+ <entry>Y</entry>
+ <entry>Z</entry>
+ <entry remap="Open bracket">[</entry>
+ <entry remap="Backslash">&bsol;</entry>
+ <entry remap="Close bracket">]</entry>
+ <entry remap="Caret">&caret;</entry>
+ <entry remap="Underscore">&uline;</entry>
+ <entry>''5&darr;</entry>
+ </row>
+ <row>
+ <entry>'14&uarr;</entry>
+ <entry remap="Grave accent">&grave;</entry>
+ <entry>a</entry>
+ <entry>b</entry>
+ <entry>c</entry>
+ <entry>d</entry>
+ <entry>e</entry>
+ <entry>f</entry>
+ <entry>g</entry>
+ <entry>''6&uarr;</entry>
+ </row>
+ <row>
+ <entry>'15&uarr;</entry>
+ <entry>h</entry>
+ <entry>i</entry>
+ <entry>j</entry>
+ <entry>k</entry>
+ <entry>l</entry>
+ <entry>m</entry>
+ <entry>n</entry>
+ <entry>o</entry>
+ <entry>''6&darr;</entry>
+ </row>
+ <row>
+ <entry>'16&uarr;</entry>
+ <entry>p</entry>
+ <entry>q</entry>
+ <entry>r</entry>
+ <entry>s</entry>
+ <entry>t</entry>
+ <entry>u</entry>
+ <entry>v</entry>
+ <entry>w</entry>
+ <entry>''7&uarr;</entry>
+ </row>
+ <row>
+ <entry>'17&uarr;</entry>
+ <entry>x</entry>
+ <entry>y</entry>
+ <entry>z</entry>
+ <entry remap="Open curly brace">&lbrace;</entry>
+ <entry remap="Vertical bar">&vbar;</entry>
+ <entry remap="Close curly brace">&rbrace;</entry>
+ <entry remap="Tilde">&tilde;</entry>
+ <entry remap="Delete">DEL</entry>
+ <entry>''7&darr;</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>The index numbers in the first and last columns are for
+ finding the octal (base-8) and hexadecimal (base-16) values
+ respectively. Replace the arrow with the number or letter from
+ the top of the column (if the arrow points up) from the bottom
+ of the column(if the arrow points down).</para>
+ <para>Example: The Escape character (ESC) is octal '033 (03 for
+ the row, 3 for the number at the top of the column because the
+ arrow points up) or hexadecimal "1B (1 for the row, B for the
+ letter at the bottom of the column because the arrow points
+ down).</para>
+ <para>For the decimal value, multiply the Octal row number by
+ eight and add the column number from the top line (that makes
+ ESC 27).</para>
+ </appendix>
+ <appendix id="gfdl" colwidth="yes">
+ <title>GNU Free Documentation License</title>
+ <subtitle>Version 1.2, November 2002</subtitle>
+ <blockquote id="fsf-copyright">
+ <para>Copyright (C) 2000,2001,2002 Free Software Foundation,
+ Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not
+ allowed.</para>
+ </blockquote>
+
+ <sect1 label="0" id="gfdl-0"><title>PREAMBLE</title>
+
+ <para>The purpose of this License is to make a manual, textbook,
+ or other functional and useful document <quote>free</quote> in
+ the sense of freedom: to assure everyone the effective freedom
+ to copy and redistribute it, with or without modifying it,
+ either commercially or noncommercially. Secondarily, this
+ License preserves for the author and publisher a way to get
+ credit for their work, while not being considered responsible
+ for modifications made by others.</para>
+
+ <para>This License is a kind of <quote>copyleft</quote>, which
+ means that derivative works of the document must themselves be
+ free in the same sense. It complements the GNU General Public
+ License, which is a copyleft license designed for free
+ software.</para>
+
+ <para>We have designed this License in order to use it for
+ manuals for free software, because free software needs free
+ documentation: a free program should come with manuals
+ providing the same freedoms that the software does. But this
+ License is not limited to software manuals; it can be used for
+ any textual work, regardless of subject matter or whether it
+ is published as a printed book. We recommend this License
+ principally for works whose purpose is instruction or
+ reference.</para>
+ </sect1>
+
+ <sect1 id="gfdl-1"><title>APPLICABILITY AND DEFINITIONS</title>
+
+ <para id="gfdl-doc">This License applies to any manual or other
+ work, in any medium, that contains a notice placed by the
+ copyright holder saying it can be distributed under the terms
+ of this License. Such a notice grants a world-wide,
+ royalty-free license, unlimited in duration, to use that work
+ under the conditions stated herein. The
+ <quote>Document</quote>, below, refers to any such manual or
+ work. Any member of the public is a licensee, and is
+ addressed as <quote>you</quote>. You accept the license if
+ you copy, modify or distribute the work in a way requiring
+ permission under copyright law.</para>
+
+ <para id="gfdl-mod-ver">A <quote>Modified Version</quote> of the
+ Document means any work containing the Document or a portion
+ of it, either copied verbatim, or with modifications and/or
+ translated into another language.</para>
+
+ <para id="gfdl-secnd-sect">A <quote>Secondary Section</quote> is
+ a named appendix or a front-matter section of the Document
+ that deals exclusively with the relationship of the publishers
+ or authors of the Document to the Document&apos;s overall
+ subject (or to related matters) and contains nothing that
+ could fall directly within that overall subject. (Thus, if
+ the Document is in part a textbook of mathematics, a Secondary
+ Section may not explain any mathematics.) The relationship
+ could be a matter of historical connection with the subject or
+ with related matters, or of legal, commercial, philosophical,
+ ethical or political position regarding them.</para>
+
+ <para id="gfdl-inv-sect">The <quote>Invariant Sections</quote>
+ are certain Secondary Sections whose titles are designated, as
+ being those of Invariant Sections, in the notice that says
+ that the Document is released under this License. If a
+ section does not fit the above definition of Secondary then it
+ is not allowed to be designated as Invariant. The Document
+ may contain zero Invariant Sections. If the Document does not
+ identify any Invariant Sections then there are none.</para>
+
+ <para id="gfdl-cov-text">The <quote>Cover Texts</quote> are
+ certain short passages of text that are listed, as Front-Cover
+ Texts or Back-Cover Texts, in the notice that says that the
+ Document is released under this License. A Front-Cover Text
+ may be at most 5 words, and a Back-Cover Text may be at most
+ 25 words.</para>
+
+ <para id="gfdl-transparent">A <quote>Transparent</quote> copy of
+ the Document means a machine-readable copy, represented in a
+ format whose specification is available to the general public,
+ that is suitable for revising the document straightforwardly
+ with generic text editors or (for images composed of pixels)
+ generic paint programs or (for drawings) some widely available
+ drawing editor, and that is suitable for input to text
+ formatters or for automatic translation to a variety of
+ formats suitable for input to text formatters. A copy made in
+ an otherwise Transparent file format whose markup, or absence
+ of markup, has been arranged to thwart or discourage
+ subsequent modification by readers is not Transparent. An
+ image format is not Transparent if used for any substantial
+ amount of text. A copy that is not <quote>Transparent</quote>
+ is called <quote>Opaque</quote>.</para>
+
+ <para>Examples of suitable formats for Transparent copies
+ include plain ASCII without markup, Texinfo input format,
+ LaTeX input format, SGML or XML using a publicly available
+ DTD, and standard-conforming simple <acronym ref="HTML"></acronym>,
+ <trademark>PostScript</trademark> or PDF designed for human
+ modification. Examples of transparent image formats include
+ PNG, XCF and JPG. Opaque formats include proprietary formats
+ that can be read and edited only by proprietary word
+ processors, SGML or XML for which the DTD and/or processing
+ tools are not generally available, and the machine-generated
+ <acronym ref="HTML"></acronym>, <trademark>PostScript</trademark> or PDF produced by
+ some word processors for output purposes only.</para>
+
+ <para id="gfdl-title-page">The <quote>Title Page</quote> means,
+ for a printed book, the title page itself, plus such following
+ pages as are needed to hold, legibly, the material this
+ License requires to appear in the title page. For works in
+ formats which do not have any title page as such, <quote>Title
+ Page</quote> means the text near the most prominent
+ appearance of the work&apos;s title, preceding the beginning
+ of the body of the text.</para>
+
+ <para id="gfdl-entitled">A section <quote>Entitled XYZ</quote>
+ means a named subunit of the Document whose title either is
+ precisely XYZ or contains XYZ in parentheses following text
+ that translates XYZ in another language. (Here XYZ stands for
+ a specific section name mentioned below, such as
+ <quote>Acknowledgements</quote>, <quote>Dedications</quote>,
+ <quote>Endorsements</quote>, or <quote>History</quote>.) To
+ <quote>Preserve the Title</quote> of such a section when you
+ modify the Document means that it remains a section
+ <quote>Entitled XYZ</quote> according to this
+ definition.</para>
+
+ <para>The Document may include Warranty Disclaimers next to the
+ notice which states that this License applies to the Document.
+ These Warranty Disclaimers are considered to be included by
+ reference in this License, but only as regards disclaiming
+ warranties: any other implication that these Warranty
+ Disclaimers may have is void and has no effect on the meaning
+ of this License.</para>
+ </sect1>
+
+ <sect1 id="gfdl-2"><title>VERBATIM COPYING</title>
+
+ <para>You may copy and distribute the Document in any medium,
+ either commercially or noncommercially, provided that this
+ License, the copyright notices, and the license notice saying
+ this License applies to the Document are reproduced in all
+ copies, and that you add no other conditions whatsoever to
+ those of this License. You may not use technical measures to
+ obstruct or control the reading or further copying of the
+ copies you make or distribute. However, you may accept
+ compensation in exchange for copies. If you distribute a
+ large enough number of copies you must also follow the
+ conditions in section 3.
+ </para>
+
+ <para>You may also lend copies, under the same conditions stated
+ above, and you may publicly display copies.</para>
+ </sect1>
+
+ <sect1 id="gfdl-3"><title>COPYING IN QUANTITY</title>
+
+ <para>If you publish printed copies (or copies in media that
+ commonly have printed covers) of the Document, numbering more
+ than 100, and the Document&apos;s license notice requires
+ Cover Texts, you must enclose the copies in covers that carry,
+ clearly and legibly, all these Cover Texts: Front-Cover Texts
+ on the front cover, and Back-Cover Texts on the back cover.
+ Both covers must also clearly and legibly identify you as the
+ publisher of these copies. The front cover must present the
+ full title with all words of the title equally prominent and
+ visible. You may add other material on the covers in
+ addition. Copying with changes limited to the covers, as long
+ as they preserve the title of the Document and satisfy these
+ conditions, can be treated as verbatim copying in other
+ respects.</para>
+
+ <para>If the required texts for either cover are too voluminous
+ to fit legibly, you should put the first ones listed (as many
+ as fit reasonably) on the actual cover, and continue the rest
+ onto adjacent pages.</para>
+
+ <para>If you publish or distribute Opaque copies of the Document
+ numbering more than 100, you must either include a
+ machine-readable Transparent copy along with each Opaque copy,
+ or state in or with each Opaque copy a computer-network
+ location from which the general network-using public has
+ access to download using public-standard network protocols a
+ complete Transparent copy of the Document, free of added
+ material. If you use the latter option, you must take
+ reasonably prudent steps, when you begin distribution of
+ Opaque copies in quantity, to ensure that this Transparent
+ copy will remain thus accessible at the stated location until
+ at least one year after the last time you distribute an Opaque
+ copy (directly or through your agents or retailers) of that
+ edition to the public.</para>
+
+ <para>It is requested, but not required, that you contact the
+ authors of the Document well before redistributing any large
+ number of copies, to give them a chance to provide you with an
+ updated version of the Document.</para>
+ </sect1>
+
+ <sect1 id="gfdl-4"><title>MODIFICATIONS</title>
+
+ <para>You may copy and distribute a Modified Version of the
+ Document under the conditions of sections 2 and 3 above,
+ provided that you release the Modified Version under precisely
+ this License, with the Modified Version filling the role of
+ the Document, thus licensing distribution and modification of
+ the Modified Version to whoever possesses a copy of it. In
+ addition, you must do these things in the Modified
+ Version:</para>
+
+ <orderedlist numeration="upperalpha" id="gfdl-modif-cond">
+ <listitem><simpara>Use in the Title Page (and on the covers,
+ if any) a title distinct from that of the Document, and
+ from those of previous versions (which should, if there
+ were any, be listed in the History section of the
+ Document). You may use the same title as a previous
+ version if the original publisher of that version gives
+ permission.
+ </simpara></listitem>
+ <listitem><simpara>List on the Title Page, as authors, one or
+ more persons or entities responsible for authorship of the
+ modifications in the Modified Version, together with at
+ least five of the principal authors of the Document (all
+ of its principal authors, if it has fewer than five),
+ unless they release you from this requirement.
+ </simpara></listitem>
+ <listitem><simpara>State on the Title page the name of the
+ publisher of the Modified Version, as the
+ publisher.</simpara></listitem>
+ <listitem><simpara>Preserve all the copyright notices of the
+ Document.
+ </simpara></listitem>
+ <listitem><simpara>Add an appropriate copyright notice for
+ your modifications adjacent to the other copyright
+ notices.
+ </simpara></listitem>
+ <listitem><simpara>Include, immediately after the copyright
+ notices, a license notice giving the public permission to
+ use the Modified Version under the terms of this License,
+ in the form shown in the <link
+ linkend="gfdl-addendum">Addendum</link> below.
+ </simpara></listitem>
+ <listitem><simpara>Preserve in that license notice the full
+ lists of Invariant Sections and required Cover Texts given
+ in the Document&apos;s license
+ notice.</simpara></listitem>
+ <listitem><simpara>Include an unaltered copy of this License.
+ </simpara></listitem>
+ <listitem><simpara>Preserve the section Entitled
+ <quote>History</quote>, Preserve its Title, and add to it
+ an item stating at least the title, year, new authors, and
+ publisher of the Modified Version as given on the Title
+ Page. If there is no section Entitled
+ <quote>History</quote> in the Document, create one stating
+ the title, year, authors, and publisher of the Document as
+ given on its Title Page, then add an item describing the
+ Modified Version as stated in the previous sentence.
+ </simpara></listitem>
+ <listitem><simpara>Preserve the network location, if any,
+ given in the Document for public access to a Transparent
+ copy of the Document, and likewise the network locations
+ given in the Document for previous versions it was based
+ on. These may be placed in the <quote>History</quote>
+ section. You may omit a network location for a work that
+ was published at least four years before the Document
+ itself, or if the original publisher of the version it
+ refers to gives permission.
+ </simpara></listitem>
+ <listitem><simpara>For any section Entitled
+ <quote>Acknowledgements</quote> or
+ <quote>Dedications</quote>, Preserve the Title of the
+ section, and preserve in the section all the substance and
+ tone of each of the contributor acknowledgements and/or
+ dedications given therein.
+ </simpara></listitem>
+ <listitem><simpara>Preserve all the Invariant Sections of the
+ Document, unaltered in their text and in their titles.
+ Section numbers or the equivalent are not considered part
+ of the section titles.
+ </simpara></listitem>
+ <listitem><simpara>Delete any section Entitled
+ <quote>Endorsements</quote>. Such a section may not be
+ included in the Modified Version.
+ </simpara></listitem>
+ <listitem><simpara>Do not retitle any existing section to be
+ Entitled <quote>Endorsements</quote> or to conflict in
+ title with any Invariant Section.
+ </simpara></listitem>
+ <listitem><simpara>Preserve any Warranty Disclaimers.
+ </simpara></listitem>
+ </orderedlist>
+
+ <para>If the Modified Version includes new front-matter sections
+ or appendices that qualify as Secondary Sections and contain
+ no material copied from the Document, you may at your option
+ designate some or all of these sections as invariant. To do
+ this, add their titles to the list of Invariant Sections in
+ the Modified Version&apos;s license notice. These titles must
+ be distinct from any other section titles.</para>
+
+ <para>You may add a section Entitled
+ <quote>Endorsements</quote>, provided it contains nothing but
+ endorsements of your Modified Version by various parties--for
+ example, statements of peer review or that the text has been
+ approved by an organization as the authoritative definition of
+ a standard.</para>
+
+ <para>You may add a passage of up to five words as a Front-Cover
+ Text, and a passage of up to 25 words as a Back-Cover Text, to
+ the end of the list of Cover Texts in the Modified Version.
+ Only one passage of Front-Cover Text and one of Back-Cover
+ Text may be added by (or through arrangements made by) any one
+ entity. If the Document already includes a cover text for the
+ same cover, previously added by you or by arrangement made by
+ the same entity you are acting on behalf of, you may not add
+ another; but you may replace the old one, on explicit
+ permission from the previous publisher that added the old
+ one.</para>
+
+ <para>The author(s) and publisher(s) of the Document do not by
+ this License give permission to use their names for publicity
+ for or to assert or imply endorsement of any Modified
+ Version.</para>
+ </sect1>
+
+ <sect1 id="gfdl-5"><title>COMBINING DOCUMENTS</title>
+
+ <para>You may combine the Document with other documents released
+ under this License, under the terms defined in <link
+ linkend="gfdl-4">section 4</link> above for modified
+ versions, provided that you include in the combination all of
+ the Invariant Sections of all of the original documents,
+ unmodified, and list them all as Invariant Sections of your
+ combined work in its license notice, and that you preserve all
+ their Warranty Disclaimers.</para>
+
+ <para>The combined work need only contain one copy of this
+ License, and multiple identical Invariant Sections may be
+ replaced with a single copy. If there are multiple Invariant
+ Sections with the same name but different contents, make the
+ title of each such section unique by adding at the end of it,
+ in parentheses, the name of the original author or publisher
+ of that section if known, or else a unique number. Make the
+ same adjustment to the section titles in the list of Invariant
+ Sections in the license notice of the combined work.</para>
+
+ <para>In the combination, you must combine any sections Entitled
+ <quote>History</quote> in the various original documents,
+ forming one section Entitled <quote>History</quote>; likewise
+ combine any sections Entitled <quote>Acknowledgements</quote>,
+ and any sections Entitled <quote>Dedications</quote>. You
+ must delete all sections Entitled
+ <quote>Endorsements</quote>.</para>
+ </sect1>
+
+ <sect1 id="gfdl-6"><title>COLLECTIONS OF DOCUMENTS</title>
+
+ <para>You may make a collection consisting of the Document and
+ other documents released under this License, and replace the
+ individual copies of this License in the various documents
+ with a single copy that is included in the collection,
+ provided that you follow the rules of this License for
+ verbatim copying of each of the documents in all other
+ respects.</para>
+
+ <para>You may extract a single document from such a collection,
+ and distribute it individually under this License, provided
+ you insert a copy of this License into the extracted document,
+ and follow this License in all other respects regarding
+ verbatim copying of that document.</para>
+ </sect1>
+
+ <sect1 id="gfdl-7"><title>AGGREGATION WITH INDEPENDENT
+ WORKS</title>
+
+ <para>A compilation of the Document or its derivatives with
+ other separate and independent documents or works, in or on a
+ volume of a storage or distribution medium, is called an
+ <quote>aggregate</quote> if the copyright resulting from the
+ compilation is not used to limit the legal rights of the
+ compilation&apos;s users beyond what the individual works
+ permit. When the Document is included an aggregate, this
+ License does not apply to the other works in the aggregate
+ which are not themselves derivative works of the
+ Document.</para>
+
+ <para>If the Cover Text requirement of section 3 is applicable
+ to these copies of the Document, then if the Document is less
+ than one half of the entire aggregate, the Document&apos;s
+ Cover Texts may be placed on covers that bracket the Document
+ within the aggregate, or the electronic equivalent of covers
+ if the Document is in electronic form. Otherwise they must
+ appear on printed covers that bracket the whole
+ aggregate.</para>
+ </sect1>
+
+ <sect1 id="gfdl-8"><title>TRANSLATION</title>
+
+ <para>Translation is considered a kind of modification, so you
+ may distribute translations of the Document under the terms of
+ section 4. Replacing Invariant Sections with translations
+ requires special permission from their copyright holders, but
+ you may include translations of some or all Invariant Sections
+ in addition to the original versions of these Invariant
+ Sections. You may include a translation of this License, and
+ all the license notices in the Document, and any Warranty
+ Disclaimers, provided that you also include the original
+ English version of this License and the original versions of
+ those notices and disclaimers. In case of a disagreement
+ between the translation and the original version of this
+ License or a notice or disclaimer, the original version will
+ prevail.</para>
+
+ <para>If a section in the Document is Entitled
+ <quote>Acknowledgements</quote>, <quote>Dedications</quote>,
+ or <quote>History</quote>, the requirement (section 4) to
+ Preserve its Title (section 1) will typically require changing
+ the actual title.</para>
+ </sect1>
+
+ <sect1 id="gfdl-9"><title>TERMINATION</title>
+
+ <para>You may not copy, modify, sublicense, or distribute the
+ Document except as expressly provided for under this License.
+ Any other attempt to copy, modify, sublicense or distribute
+ the Document is void, and will automatically terminate your
+ rights under this License. However, parties who have received
+ copies, or rights, from you under this License will not have
+ their licenses terminated so long as such parties remain in
+ full compliance.</para>
+ </sect1>
+
+ <sect1 id="gfdl-10"><title>FUTURE REVISIONS OF THIS
+ LICENSE</title>
+
+ <para>The Free Software Foundation may publish new, revised
+ versions of the GNU Free Documentation License from time to
+ time. Such new versions will be similar in spirit to the
+ present version, but may differ in detail to address new
+ problems or concerns. See
+ http://www.gnu.org/copyleft/.</para>
+
+ <para>Each version of the License is given a distinguishing
+ version number. If the Document specifies that a particular
+ numbered version of this License <quote>or any later
+ version</quote> applies to it, you have the option of
+ following the terms and conditions either of that specified
+ version or of any later version that has been published (not
+ as a draft) by the Free Software Foundation. If the Document
+ does not specify a version number of this License, you may
+ choose any version ever published (not as a draft) by the Free
+ Software Foundation.</para>
+ </sect1>
+
+ <sect1 id="gfdl-addendum"><title>ADDENDUM: How to use this License
+ for your documents</title>
+
+ <para>To use this License in a document you have written,
+ include a copy of the License in the document and put the
+ following copyright and license notices just after the title
+ page:</para>
+
+ <blockquote id="copyright-sample"><para>
+ Copyright (c) YEAR YOUR NAME. 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 <quote>GNU Free Documentation
+ License</quote>.
+ </para></blockquote>
+
+ <para>If you have Invariant Sections, Front-Cover Texts and
+ Back-Cover Texts, replace the
+ <quote>with&hellip;Texts.</quote> line with this:</para>
+
+ <blockquote id="inv-cover-sample"><para>
+ with the Invariant Sections being LIST THEIR TITLES, with
+ the Front-Cover Texts being LIST, and with the Back-Cover
+ Texts being LIST.
+ </para></blockquote>
+
+ <para>If you have Invariant Sections without Cover Texts, or
+ some other combination of the three, merge those two
+ alternatives to suit the situation.</para>
+
+ <para>If your document contains nontrivial examples of program
+ code, we recommend releasing these examples in parallel under
+ your choice of free software license, such as the GNU General
+ Public License, to permit their use in free software.</para>
+ </sect1>
+ </appendix>
+<!--
+ <appendix id="tugform">
+ <title><TeX/> Users Group Membership</title>
+ <para>If you have questions or encounter any problems with the
+ membership registration, please contact the TUG office.</para>
+ <section>
+ <title>Becoming a TUG member</title>
+ <variablelist>
+ <varlistentry>
+ <term>Online:</term>
+ <listitem>
+ <para>Fill out the secure online form and submit it (the
+ Submit button is at the bottom of the form).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Paper mail:</term>
+ <listitem>
+ <para>If you prefer to forgo electronic submittal, you
+ can alternatively print out the PDF membership form or
+ respectively renewal form and follow the instructions on
+ the form.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section>
+ <title>Membership fees</title>
+ <para>TUG membership for 2006 is &dollar;65 (US) a year for
+ individuals and &dollar;35 for students and seniors. Add
+ &dollar;10 to the membership fee after May 31, 2004 to cover
+ additional shipping and processing costs.</para>
+ <para>The 2006 rate for non-voting subscription memberships (for
+ libraries, for example) is &dollar;85. The 2006 institutional
+ rate is &dollar;500, which includes up to seven individual
+ memberships.</para>
+ </section>
+ <section>
+ <title>TUG membership benefits</title>
+ <para>Members of TUG help to support and promote the use of
+ <TeX/>, &metafont;, and related systems worldwide. All members
+ receive <citetitle ref="tugboat" show="title"></citetitle>,
+ the journal of
+ the <TeX/> Users Group; <TeX/> Live, the software <acronym
+ ref="CD-ROM"></acronym>; and the Dante <acronym
+ ref="CTAN"></acronym> archive on <acronym ref="CD-ROM"
+ condition="noid"></acronym>s or <acronym
+ ref="DVD"></acronym>. In addition, TUG members vote in TUG
+ elections, and receive discounts on annual meeting fees,
+ student membership rates, and TUG-sponsored courses. More
+ information is available on the Web site. TUG membership (less
+ benefits) is tax-deductible, at least in the USA: see the TUG
+ Web site for details.</para>
+ </section>
+ <section>
+ <title>Delivery of benefits</title>
+ <para>All benefits are sent as soon as they are available. The
+ <TeX/> Live <acronym ref="CD-ROM" condition="noid"></acronym>s
+ are usually produced in the summer, and the <acronym
+ ref="CTAN"></acronym> <acronym ref="CD-ROM"
+ condition="noid"></acronym>s in the autumn (in 2004 these
+ are done together on <acronym ref="DVD"></acronym>).
+ <citetitle condition="nocite" ref="tugboat"></citetitle> issue
+ production depends on the availability of material and is thus
+ less predictable.</para>
+ <para>In addition, if you will be a new TUG member this year
+ (welcome!), you may wish to order the previous year&apos;s
+ materials. See the Web site for details.</para>
+ <informaltable colsep="1em">
+ <tgroup cols="2">
+ <colspec align="left"/>
+ <colspec align="right"/>
+ <thead>
+ <row>
+ <entry>Item</entry>
+ <entry>Cost</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><TeX/> Live 7 (2002)</entry>
+ <entry>&dollar;5</entry>
+ </row>
+ <row>
+ <entry>Dante <acronym ref="CTAN"></acronym> <acronym
+ ref="CD-ROM" condition="noid"></acronym>s (2002)</entry>
+ <entry>&dollar;10</entry>
+ </row>
+ <row>
+ <entry><citetitle condition="nocite"
+ ref="tugboat"></citetitle> volume 23 (2002)</entry>
+ <entry>&dollar;45</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <graphic fileref="memberapp" width="39pc" align="left"
+ remap="noframe"/>
+ </section>
+ </appendix>
+-->
+ <bibliography id="biblio" remap="jurabib" role="beginlatex">
+ <title>References</title>
+ <biblioentry id="mathguide" type="book">
+ <author remap="AMS">
+ <othername>American Mathematical Society</othername>
+ </author>
+ <title>Short Math Guide for <LaTeX/></title>
+ <titleabbrev>Short Math Guide</titleabbrev>
+ <publisher>
+ <publishername>AMS</publishername>
+ <address>Providence, RI</address>
+ </publisher>
+ <releaseinfo>http://www.ams.org/tex/short-math-guide.html</releaseinfo>
+ <date YYYY-MM-DD="2001">2001</date>
+ </biblioentry>
+ <biblioentry id="fontname" type="techreport">
+ <author>
+ <surname>Berry</surname>
+ <firstname>Karl</firstname>
+ </author>
+ <title>Fontname</title>
+ <subtitle>Filenames for <TeX/> fonts</subtitle>
+ <releaseinfo>http://www.ctan.org/tex-archive/info/fontname/</releaseinfo>
+ <orgname><TeX/> Users Group</orgname>
+ <address>Portland, OR</address>
+ <date YYYY-MM-DD="2001-06">June 2001</date>
+ </biblioentry>
+ <biblioentry type="book" id="bull">
+ <author>
+ <surname>Bull</surname>
+ <firstname>RJ</firstname>
+ </author>
+ <title>Accounting in Business</title>
+ <publisher>
+ <publishername>Butterworths</publishername>
+ <address>London</address>
+ </publisher>
+ <date YYYY-MM-DD="1972">1972</date>
+ <isbn>0-406-70651-4</isbn>
+ </biblioentry>
+ <biblioentry id="teiguide" type="techreport">
+ <authorgroup>
+ <author>
+ <surname>Burnard</surname>
+ <firstname>Lou</firstname>
+ </author>
+ <author>
+ <surname>Sperberg-McQueen</surname>
+ <firstname>Michael</firstname>
+ </author>
+ </authorgroup>
+ <title>Guidelines for the Text Encoding Initiative</title>
+ <titleabbrev>TEI Guidelines</titleabbrev>
+ <orgname>OUP</orgname>
+ <address>Oxford</address>
+ <date YYYY-MM-DD="1995">1995</date>
+ </biblioentry>
+ <biblioentry id="davy" type="book">
+ <author>
+ <surname>Davy</surname>
+ <firstname>William</firstname>
+ </author>
+ <title>A System of Divinity</title>
+ <publisher>
+ <publishername>Published by the author</publishername>
+ <address>Lustleigh, Devon</address>
+ </publisher>
+ <date YYYY-MM-DD="1806">1806</date>
+ </biblioentry>
+ <biblioentry id="gentle" type="techreport">
+ <author>
+ <surname>Doob</surname>
+ <firstname>Michael</firstname>
+ <affiliation>
+ <orgname>University of Manitoba</orgname>
+ <address>Winnipeg, Manitoba, Canada</address>
+ </affiliation>
+ </author>
+ <title>A Gentle Introduction to <TeX/></title>
+ <subtitle>A Manual for Self-Study</subtitle>
+ <titleabbrev>Gentle Intro</titleabbrev>
+ <orgname><TeX/> Users Group</orgname>
+ <address>Portland, OR</address>
+ <date YYYY-MM-DD="1993-11-30">2002</date>
+ <releaseinfo>http://www.ctan.org/tex-archive/info/gentle/</releaseinfo>
+ </biblioentry>
+ <biblioentry id="bovary" type="book">
+ <author>
+ <surname>Flaubert</surname>
+ <firstname>Gustave</firstname>
+ </author>
+ <title>Madame Bovary</title>
+ <address>Paris</address>
+ <date YYYY-MM-DD="1857">1857</date>
+ </biblioentry>
+ <biblioentry id="htmlbook" type="book">
+ <author>
+ <surname>Flynn</surname>
+ <firstname>Peter</firstname>
+ </author>
+ <title>The HTML Handbook</title>
+ <titleabbrev>The HTML Handbook</titleabbrev>
+ <publisher>
+ <publishername>International Thompson Computer
+ Press</publishername>
+ <address>London</address>
+ </publisher>
+ <isbn>1-85032-205-8</isbn>
+ <date YYYY-MM-DD="1995">1995</date>
+ </biblioentry>
+ <biblioentry id="sgmltools" type="book">
+ <author>
+ <surname>Flynn</surname>
+ <firstname>Peter</firstname>
+ </author>
+ <title>Understanding SGML and XML Tools</title>
+ <titleabbrev>SGML &ampers; XML Tools</titleabbrev>
+ <publisher>
+ <publishername>Kluwer</publishername>
+ <address>Boston</address>
+ </publisher>
+ <isbn>0-7923-8169-6</isbn>
+ <date YYYY-MM-DD="1998">1998</date>
+ </biblioentry>
+ <biblioentry id="fg" type="book">
+ <author>
+ <surname>Fothergill</surname>
+ <firstname>John</firstname>
+ </author>
+ <title>An Innkeeper&apos;s Diary</title>
+ <publisher>
+ <publishername>Penguin</publishername>
+ <address>London</address>
+ </publisher>
+ <edition>3rd</edition>
+ <date YYYY-MM-DD="1929">1929</date>
+ </biblioentry>
+ <biblioentry id="companion" type="book">
+ <authorgroup>
+ <author>
+ <surname>Mittelbach</surname>
+ <firstname>Frank</firstname>
+ </author>
+ <author>
+ <surname>Goossens</surname>
+ <firstname>Michel</firstname>
+ </author>
+ <author>
+ <surname>Braams</surname>
+ <firstname>Johannes</firstname>
+ </author>
+ <author>
+ <surname>Carlisle</surname>
+ <firstname>David</firstname>
+ </author>
+ <author>
+ <surname>Rowley</surname>
+ <firstname>Chris</firstname>
+ </author>
+ </authorgroup>
+ <title>The <LaTeX/> Companion</title>
+ <titleabbrev>Companion</titleabbrev>
+ <publisher>
+ <publishername>Addison-Wesley/Pearson Education</publishername>
+ <address>Boston, MA</address>
+ </publisher>
+ <edition>2</edition>
+ <isbn>0-201-36299-6</isbn>
+ <date YYYY-MM-DD="2004">2004</date>
+ </biblioentry>
+ <biblioentry id="graphicscomp" type="book">
+ <authorgroup>
+ <author>
+ <surname>Goossens</surname>
+ <firstname>Michel</firstname>
+ </author>
+ <author>
+ <surname>Rahtz</surname>
+ <firstname>Sebastian</firstname>
+ </author>
+ <author>
+ <surname>Mittelbach</surname>
+ <firstname>Frank</firstname>
+ </author>
+ </authorgroup>
+ <title>The <LaTeX/> Graphics Companion</title>
+ <titleabbrev>Graphics Companion</titleabbrev>
+ <publisher>
+ <publishername>Addison-Wesley</publishername>
+ <address>Reading, MA</address>
+ </publisher>
+ <isbn>0-201-85469-4</isbn>
+ <date YYYY-MM-DD="1997">1997</date>
+ </biblioentry>
+ <biblioentry id="webcomp" type="book">
+ <authorgroup>
+ <author>
+ <surname>Goossens</surname>
+ <firstname>Michel</firstname>
+ </author>
+ <author>
+ <surname>Rahtz</surname>
+ <firstname>Sebastian</firstname>
+ </author>
+ <author>
+ <surname>Moore</surname>
+ <firstname>Ross</firstname>
+ </author>
+ <author>
+ <surname>Sutor</surname>
+ <firstname>Bob</firstname>
+ </author>
+ </authorgroup>
+ <title>The <LaTeX/> Web Companion</title>
+ <titleabbrev>Web Companion</titleabbrev>
+ <publisher>
+ <publishername>Addison-Wesley</publishername>
+ <address>Reading, MA</address>
+ </publisher>
+ <isbn>0-201-43311-7</isbn>
+ <date YYYY-MM-DD="1999">1999</date>
+ </biblioentry>
+ <biblioentry id="goreham-ctt" type="article">
+ <articleinfo>
+ <author>
+ <surname>Goreham</surname>
+ <firstname>Anthony</firstname>
+ </author>
+ <title>Re: Installing a new font: PFM, PFB</title>
+ <titleabbrev>Installing a new font</titleabbrev>
+ </articleinfo>
+ <title><ulink url="comp.text.tex" type="news"></ulink></title>
+ <issuenum>m3r8qj42o3.fsf@micawber.queens.ox.ac.uk</issuenum>
+ <pagenums>(all pages)</pagenums>
+ <date YYYY-MM-DD="2001-11-28T10:20:44">28 November 2001</date>
+ </biblioentry>
+ <biblioentry id="heller" type="article">
+ <articleinfo>
+ <author>
+ <surname>Heller</surname>
+ <firstname>Robert</firstname>
+ </author>
+ <title>New To <LaTeX/>&hellip;Unlearning Bad Habits</title>
+ <titleabbrev>Bad habits</titleabbrev>
+ </articleinfo>
+ <title><ulink url="comp.text.tex" type="news"></ulink></title>
+ <issuenum>MPG.18d82140d65ddc5898968c@news.earthlink.net</issuenum>
+ <pagenums>(all pages)</pagenums>
+ <date YYYY-MM-DD="2003-03-11T22:21:49">11 March 2003</date>
+ </biblioentry>
+ <biblioentry id="fontinst" type="techreport">
+ <authorgroup>
+ <author>
+ <surname>Jeffrey</surname>
+ <firstname>Alan</firstname>
+ </author>
+ <author>
+ <surname>McDonnell</surname>
+ <firstname>Rowland</firstname>
+ </author>
+ </authorgroup>
+ <title>Font installation software for <TeX/></title>
+ <titleabbrev>Fontinst</titleabbrev>
+ <releaseinfo>http://www.tex.ac.uk/tex-archive/fonts/utilities/fontinst/</releaseinfo>
+ <orgname><TeX/> Users Group</orgname>
+ <date YYYY-MM-DD="1998-06-30">30 June 1998</date>
+ </biblioentry>
+ <biblioentry id="aocs" type="book">
+ <author>
+ <surname>Knuth</surname>
+ <firstname>Donald Ervin</firstname>
+ </author>
+ <title>The Art of Computer Programming</title>
+ <publisher>
+ <publishername>Addison-Wesley</publishername>
+ <address>Reading, MA</address>
+ </publisher>
+ <edition>2nd</edition>
+ <volumenum>1</volumenum>
+ <isbn>0-201-89685-0</isbn>
+ <date YYYY-MM-DD="1980">1980</date>
+ </biblioentry>
+ <biblioentry id="latexbook" type="book">
+ <author>
+ <surname>Lamport</surname>
+ <firstname>Leslie</firstname>
+ </author>
+ <title><LaTeX/></title>
+ <subtitle>A Document Preparation System</subtitle>
+ <publisher>
+ <publishername>Addison-Wesley</publishername>
+ <address>Reading, MA</address>
+ </publisher>
+ <isbn>0-201-52983-1</isbn>
+ <edition>2nd</edition>
+ <date YYYY-MM-DD="1994">1994</date>
+ </biblioentry>
+ <biblioentry id="macnamara" type="book">
+ <author>
+ <surname remap="preserve">Mac Namara</surname>
+ <firstname>Matthew</firstname>
+ </author>
+ <title>La Textualisation de <citation>Madame
+ Bovary</citation></title>
+ <publisher>
+ <publishername>Rodopi</publishername>
+ <address>Amsterdam</address>
+ </publisher>
+ <date YYYY-MM-DD="2003">2003</date>
+ </biblioentry>
+ <biblioentry id="lshort" type="techreport">
+ <authorgroup>
+ <author>
+ <surname>Oetiker</surname>
+ <firstname>Tobias</firstname>
+ </author>
+ <author>
+ <surname>Partl</surname>
+ <firstname>Hubert</firstname>
+ </author>
+ <author>
+ <surname>Hyna</surname>
+ <firstname>Irene</firstname>
+ </author>
+ <author>
+ <surname>Schlegl</surname>
+ <firstname>Elisabeth</firstname>
+ </author>
+ </authorgroup>
+ <title>The (Not So) Short Guide to <LaTeXe/></title>
+ <subtitle><LaTeXe/> in 131 Minutes</subtitle>
+ <titleabbrev>Short Guide</titleabbrev>
+ <orgname><TeX/> Users Group</orgname>
+ <releaseinfo>http://www.ctan.org/tex-archive/info/lshort/</releaseinfo>
+ <date YYYY-MM-DD="2001">2001</date>
+ <edition>3.2</edition>
+ </biblioentry>
+ <biblioentry id="symbol-list" type="techreport">
+ <author>
+ <surname>Pakin</surname>
+ <firstname>Scott</firstname>
+ <affiliation>
+ <orgname>University of Illinois</orgname>
+ <address>Urbana-Champaign</address>
+ </affiliation>
+ </author>
+ <title>A comprehensive list of symbols in <TeX/></title>
+ <titleabbrev>Symbol list</titleabbrev>
+ <orgname><TeX/> Users Group</orgname>
+ <releaseinfo>http://www.ctan.org/tex-archive/info/symbols/comprehensive/</releaseinfo>
+ <date YYYY-MM-DD="2002">2002</date>
+ </biblioentry>
+ <biblioentry type="techreport" id="begin">
+ <author remap="TUG">
+ <othername><TeX/> Users Group</othername>
+ </author>
+ <title>Getting Started with <TeX/>, <LaTeX/>, and friends</title>
+ <titleabbrev>Getting Started</titleabbrev>
+ <orgname><TeX/> Users Group</orgname>
+ <address>Portland, OR</address>
+ <releaseinfo>http://www.tug.org/begin.html</releaseinfo>
+ <date YYYY-MM-DD="2003-11-29">November 2003</date>
+ </biblioentry>
+ <biblioentry id="imported" type="techreport">
+ <author>
+ <surname>Reckdahl</surname>
+ <firstname>Keith</firstname>
+ </author>
+ <title>Using imported graphics in <LaTeXe/></title>
+ <titleabbrev>Imported graphics</titleabbrev>
+ <orgname><TeX/> Users Group</orgname>
+ <releaseinfo>http://www.ctan.org/tex-archive/info/epslatex.pdf/</releaseinfo>
+ <date YYYY-MM-DD="1997">1997</date>
+ <edition>2.0</edition>
+ </biblioentry>
+ <biblioentry id="tain" type="incollection">
+ <articleinfo>
+ <author>
+ <othername>Anon</othername>
+ </author>
+ <title>Táin bó Cúailnge</title>
+ <artpagenums>55</artpagenums>
+ </articleinfo>
+ <title>Leabhar na h-Uidhri</title>
+ <subtitle>The Book of the Dun Cow</subtitle>
+ <publisher>
+ <publishername>Royal Irish Academy</publishername>
+ <address>Dublin</address>
+ </publisher>
+ <date YYYY-MM-DD="1870-00-00">1100</date>
+ </biblioentry>
+ <biblioentry type="article" id="varmints">
+ <articleinfo>
+ <author>
+ <surname>Rawlings</surname>
+ <firstname>Marjorie Kinnan</firstname>
+ </author>
+ <title>Varmints</title>
+ </articleinfo>
+ <title>Scribner&apos;s Magazine</title>
+ <date YYYY-MM-DD="1932-12-00">1936</date>
+ </biblioentry>
+ <biblioentry id="ryder" type="book">
+ <author>
+ <surname>Ryder</surname>
+ <firstname>John</firstname>
+ </author>
+ <title>Printing for Pleasure</title>
+ <publisher>
+ <publishername>Bodley Head</publishername>
+ <address>London</address>
+ </publisher>
+ <isbn>0-370-10443-9</isbn>
+ <date YYYY-MM-DD="1976">1976</date>
+ </biblioentry>
+ <biblioentry id="xmlfaq" type="techreport">
+ <author>
+ <surname>Flynn</surname>
+ <firstname>Peter</firstname>
+ </author>
+ <title>The XML FAQ</title>
+ <orgname>University College Cork</orgname>
+ <address>Cork, Ireland</address>
+ <releaseinfo>http://www.ucc.ie/xml/</releaseinfo>
+ <date YYYY-MM-DD="2005-01-01">January 2005</date>
+ </biblioentry>
+ <biblioentry id="gnufdl" type="techreport">
+ <author remap="FSF">
+ <othername>Free Software Foundation</othername>
+ </author>
+ <title>The GNU Free Documentation License</title>
+ <titleabbrev>GNU FDL</titleabbrev>
+ <orgname>Free Software Foundation</orgname>
+ <address>Boston, MA</address>
+ <releaseinfo>http://www.fsf.org/copyleft/fdl.html</releaseinfo>
+ <date YYYY-MM-DD="2003-02-10T23:42:49">2003/02/10
+ 23:42:49</date>
+ </biblioentry>
+ <biblioentry id="tugboat" type="proceedings">
+ <editor>
+ <surname>Beeton</surname>
+ <firstname>Barbara</firstname>
+ </editor>
+ <title>TUGboat</title>
+ <publisher>
+ <publishername><TeX/> Users Group</publishername>
+ <address>Portland, OR</address>
+ </publisher>
+ <issn>0896-3207</issn>
+ <date YYYY-MM-DD="1980-00-00">Since 1980</date>
+ </biblioentry>
+ <biblioentry id="practex" type="proceedings">
+ <authorgroup>
+ <editor>
+ <surname>Carnes</surname>
+ <firstname>Lance</firstname>
+ </editor>
+ <editor>
+ <surname>Berry</surname>
+ <firstname>Karl</firstname>
+ </editor>
+ </authorgroup>
+ <title>The Prac<TeX/> Journal</title>
+ <publisher>
+ <publishername><TeX/> Users Group</publishername>
+ <address>Portland, OR</address>
+ </publisher>
+ <releaseinfo>http://www.tug.org/pracjourn/</releaseinfo>
+ <date YYYY-MM-DD="2004-00-00">2004</date>
+ </biblioentry>
+ <biblioentry id="wired" type="proceedings">
+ <editor>
+ <surname>Anderson</surname>
+ <firstname>Chris</firstname>
+ </editor>
+ <title>WIRED</title>
+ <publisher>
+ <publishername>Cond&eacute; Nast</publishername>
+ <address>San Francisco, CA</address>
+ </publisher>
+ <issn>1059-1028</issn>
+ <date YYYY-MM-DD="1993-00-00">1993--</date>
+ </biblioentry>
+ <biblioentry type="book" id="mathwrite">
+ <authorgroup>
+ <author>
+ <surname>Knuth</surname>
+ <firstname>Donald E</firstname>
+ </author>
+ <author>
+ <surname>Larrabee</surname>
+ <firstname>Tracey</firstname>
+ </author>
+ <author>
+ <surname>Roberts</surname>
+ <firstname>Paul M</firstname>
+ </author>
+ </authorgroup>
+ <title>Mathematical Writing</title>
+ <publisher>
+ <publishername>Mathematical Association of America</publishername>
+ <address>Washington, DC</address>
+ </publisher>
+ <seriesvolnums>MAA Notes 14</seriesvolnums>
+ <isbn>0-88385-063-X</isbn>
+ <date YYYY-MM-DD="1989-00-00">1989</date>
+ </biblioentry>
+ </bibliography>
+ <index id="index">
+ <title>Index</title>
+ <para>The same fonts are used here as in the text of the book
+ (see <xref linkend="symbols"/>) to distinguish between different
+ meanings:</para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec align="left" colsep="flush"/>
+ <colspec align="left" colsep="flush"/>
+ <thead>
+ <row>
+ <entry>Notation</entry>
+ <entry>Meaning</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><acronym ref="CTAN"></acronym></entry>
+ <entry>Acronyms (small caps in some typefaces)</entry>
+ </row>
+ <row>
+ <entry><command>command</command></entry>
+ <entry><LaTeX/> control sequences (monospace font)</entry>
+ </row>
+ <row>
+ <!-- can't use id=term here as it's been used earlier -->
+ <entry><format fontseries="b"
+ fontshape="it">term</format></entry>
+ <entry>Defining instance of a specialist term (bold
+ italics)</entry>
+ </row>
+ <row>
+ <entry><productname>product</productname></entry>
+ <entry>program or product name (italics)</entry>
+ </row>
+ <row>
+ <entry><modespec>environment</modespec></entry>
+ <entry><LaTeX/> environment (sans-serif bold)</entry>
+ </row>
+ <row>
+ <entry><methodname>package</methodname></entry>
+ <entry><LaTeX/> package (sans-serif; all available from
+ <acronym ref="CTAN"></acronym>)</entry>
+ </row>
+ <row>
+ <entry><option>options</option></entry>
+ <entry>Options to environments (sans-serif oblique)</entry>
+ </row>
+ <row>
+ <entry><varname
+ role="counter">variables</varname></entry>
+ <entry>Variables (monospace oblique)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>In the online version, the entries below are all hyperlinked
+ to their source, with subsequent multiple occurrences giving the
+ section number or name. Page or section numbers in <format
+ fontseries="b">bold type</format> indicate a defining
+ instance.</para>
+ </index>
+</book>