diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /info/beginlatex/src/beginlatex.xml |
Initial commit
Diffstat (limited to 'info/beginlatex/src/beginlatex.xml')
-rw-r--r-- | info/beginlatex/src/beginlatex.xml | 13330 |
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 & inside <literal>. In normal + text, use the homebrew &ers; instead. + +--> + +<book id="null"> + <bookinfo> + <title>Formatting information</title> + <subtitle>A beginner'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 © 1999–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—as well as other online + documents—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 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's corrections (see + separate emails) and rewrote a few formatting macros to + allow the document to fit more easily into US Letter shape. + It would be nice if it would also format for A5 so that it + could become a paperback but that's another day's work. + Started on writing the missing sections (Installing Type 1 + <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't know how to do + these things yet, it's important to go and learn them + first. Trying to become familiar with the fundamentals of + using a computer <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—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/>'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'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'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'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&ers;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™, 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>'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>'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&ers;Y<TeX/></entry> + <entry>MS-Windows</entry> + <entry>Y&ers;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> <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>'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, ⪚ <command>newpage</command></entry> + </row> + <row> + <entry><varname + role="dimension">length</varname></entry> + <entry>Control sequences which store a dimension + (measurement in units), ⪚ <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), ⪚ <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> <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'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'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't heard of it. It'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>—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—this is perfectly + normal and healthy in a 3-year old child who is being + creative, but is of questionable usefulness for, say, a grad + student writing a Master's or PhD thesis or a business + person writing a white paper, &etc; For this reason, + <emphasis>I</emphasis> strongly recommend + <emphasis>not</emphasis> using any sort of fancy <acronym + ref="GUI"></acronym> <wordasword>crutch</wordasword>. + Use a plain vanilla text editor and treat it like an + old-fashioned typewriter. Don'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…<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'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'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's impossible + to tell how many people are using it, but it's a + <emphasis>lot</emphasis>.</para> + </footnote></para> + <para>To count yourself as a <TeX/> or <LaTeX/> user, visit the + <TeX/> Users Group'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' 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…</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/>'s default font is Computer Modern (based + on Monotype Series 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's what they're for—get used to it.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>MYTH: <quote><LaTeX/> isn'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/>'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'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'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; <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're using something <TeX/> doesn'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>π</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's nonsense: most people grasp + <LaTeX/> in 20 minutes or so. It's not rocket + science (or if it is, I know any number of unemployed + rocket scientists who will teach it to you).</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 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>'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>'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't much use to you if you're + unfamiliar with editors and previewers, so have a look at the + table below, and maybe flip ahead to <xref + linkend="editors"/> for a moment, where there are + descriptions and screenshots.</para> + <para>The best bet is probably to install more than one—if + you've got the disk space—or maybe all of them, because + you can always delete the ones you don't like.</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'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'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's tool for + MS-Windows. Runs <LaTeX/> &etc; 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 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> &smiley;. + 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. $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'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'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'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'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…</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> <productname>WinEdt</productname> + (with or without some of its add-ons) <emphasis + role="high">or</emphasis> <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's a good editor, + especially for the heavy user of a + <productname>MIK<TeX/></productname>-based system. This is + a free month's trial—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'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'll + only have one (the text itself) but if you are working with + anything beyond simple articles, you'll probably have + illustrations (images or diagrams), and possibly separate + chapter files for larger documents, plus indexes, + glossaries, bibliographies, etc. I recommend that you create + a new project for each new document, even if it's a + single-file article, as I did for the example in <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're new to + <LaTeX/>, pick Quick Install on the following screen. This + gives you everything you need to get started, and + doesn't ask any questions, it just installs it all + straight away.</para> + <para>If you're installing under Windows NT, 2000, or + XP, you may want to click on the option to install for + all users if you have other users on your system.</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>' MS-DOS implementation of <TeX/> + called em<TeX/>—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't have to install just one editor: if + you've got the space, install them all so you can + try them out. You can always uninstall the ones you + don't want afterwards.</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. (<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's always annoying when a program that's supposed to + install painlessly causes trouble, and none the more so when + everyone else seems to have been able to install it without + problems. I've installed <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'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'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's always fixed and notified + on <ulink url="comp.text.tex" type="news:"></ulink>, + that'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're a computer scientist or a software + engineer, I suggest you never change or fiddle with + the default directories for installation. I know some + of them look odd, but they're that way for a purpose, + especially when it comes to avoiding directories will + spaces in their names, like the notorious + <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't: you'll just make it harder to find, harder to + fix problems, and more embarrassing if you have to + explain it to someone else trying to help you.</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>—see <xref + linkend="asciicodes"/>—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–1) or + ISO-8859-15 (Western Latin plus the Euro sign). These are + international standards which work everywhere: you should + avoid using manufacturers' proprietary character sets + like Microsoft Windows–1252 or Apple Macintosh + Roman–8, because they may make your documents unusable + on some other systems.</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' 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'd probably like to type something in and see <LaTeX/> + do its job. If you don'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'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—and so you shouldn't, for your + <LaTeX/> documents—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'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>—in either case + there'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'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—or month. As + well as edit, you can use it to read your mail, browse the + Web, read Usenet news, do wordprocessing and spreadsheets, + compile programs, help you write in any computer + language—including <acronym ref="XML"></acronym> and + <LaTeX/>—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's sometimes criticised for a steep learning + curve, but in fact it's no worse in this respect than + any other editor, given the power that it provides, and it + is significantly better than most which lack many of the + authorial tools available in Emacs.</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'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'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'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>( )</literal>, square brackets + <literal>[ ]</literal>, or angle brackets + <literal><![CDATA[<]]> ></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's harder to edit: + normally you'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>\</keycap></entry> + <entry>The command character</entry> + <entry><command>textbackslash</command></entry> + <entry>\</entry> + </row> + <row> + <entry><keycap>$</keycap></entry> + <entry>Math typesetting delimiter</entry> + <entry><command>$</command></entry> + <entry>$</entry> + </row> + <row> + <entry><keycap>%</keycap></entry> + <entry>The comment character</entry> + <entry><command>%</command></entry> + <entry>%</entry> + </row> + <row> + <entry><keycap>⁁</keycap></entry> + <entry>Math superscript character</entry> + <entry><command>⁁</command></entry> + <entry>⁁</entry> + </row> + <row> + <entry><keycap>&ers;</keycap></entry> + <entry>Tabular column separator</entry> + <entry><command>&ers;</command></entry> + <entry>&ers;</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>˜</keycap></entry> + <entry>Non-breaking space</entry> + <entry><command>˜</command></entry> + <entry>˜</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>{</keycap></entry> + <entry>Argument start delimiter</entry> + <entry><command + userlevel="math">{</command></entry> + <entry><literallayout role="{">$\{$</literallayout></entry> + </row> + <row> + <entry><keycap>}</keycap></entry> + <entry>Argument end delimiter</entry> + <entry><command + userlevel="math">}</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 $, + &hash;, &ers;, and %) 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>$</keycap></term> + <listitem> + <para>Because of the special mathematical meaning + <LaTeX/> uses for the dollar-sign on its own, if you + want to print $35.99 you type + <literal>\$35.99</literal></para> + </listitem> + </varlistentry> + <varlistentry> + <term><keycap>%</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% you need + to type <literal>45\%</literal></para> + </listitem> + </varlistentry> + <varlistentry> + <term><keycap>⁁</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>&ers;</keycap></term> + <listitem> + <para>The ampersand is used in tables to separate + columns (see <xref linkend="tables"/>). If you want to + print AT&ers;T you need to type + <literal>AT\&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>˜</keycap></term> + <listitem> + <para>The tilde prints as a space, but prevents a + linebreak ever occurring at that point. It's often + used between a person's initials and their surname, eg + <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 £, 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're on the subject of money, an unusual but + interesting serif-font Euro<indexterm> + <primary sortas="euro">€</primary> + </indexterm> sign <format fontdefault="rm">€</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">"</keycap> key for quotation + marks. Correct typographic quotes are got with the <keycap + remap="tt">`</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, + “I'm just going out.”</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> and <superscript>99</superscript> + or as symmetrically-balanced strokes). If you are using + <productname>Emacs</productname> as your editor, the + <keycap>"</keycap> key is specially programmed in + <LaTeX/>-mode to think for itself and produce correct <format + fontdefault="tt">``</format> and + <literal>''</literal> characters (so this is one occasion when + you <emphasis>can</emphasis> use the <keycap>"</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, ‘Her answer was + “never” ’.</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–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—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't covered the use of + packages yet. Don't worry, see <xref linkend="packages"/> + if you're curious.</para></footnote> in your preamble + with the relevant option. For example, to tell <LaTeX/> you + will be typing ISO Latin–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'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't have accented letter keys on your + keyboard, you'll need to use your operating system'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 >ilde; you can have one with the command + <command>˜</command><literal>g</literal> (and Welsh + users can get ŵ with + <command>⁁</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>ñ</entry> + <entry><literal>\~n</literal></entry> + </row> + <row> + <entry>Macron</entry> + <entry>ō</entry> + <entry><literal>\=o</literal></entry> + </row> + <row> + <entry>Bar-under</entry> + <entry><format lining="under" + condition="HTML">⦵</format><format + condition="LaTeX">⦵</format></entry> + <entry><literal>\b o</literal></entry> + </row> + <row> + <entry>Dot-over (séı&mdot;ıú)</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">⋅</format><format + condition="LaTeX">⋅</format></entry> + <entry><literal>\d s</literal></entry> + </row> + <row> + <entry>Breve</entry> + <entry>ŭ</entry> + <entry><literal>\u u</literal></entry> + </row> + <row> + <entry>Háč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>ç</entry> + <entry><literal>\c c</literal></entry> + </row> + <row> + <entry>O-E ligature</entry> + <entry>œ, Œ</entry> + <entry><literal>\oe</literal>, + <literal>\OE</literal></entry> + </row> + <row> + <entry>A-E ligature</entry> + <entry>æ, Æ</entry> + <entry><literal>\ae</literal>, + <literal>\AE</literal></entry> + </row> + <row> + <entry>A-ring</entry> + <entry>å, Å</entry> + <entry><literal>\aa</literal>, + <literal>\AA</literal></entry> + </row> + <row> + <entry>O-slash</entry> + <entry>ø, Ø</entry> + <entry><literal>\o</literal>, + <literal>\O</literal></entry> + </row> + <row> + <entry>Soft-l</entry> + <entry><format fontencoding="T1" + fontfamily="cmr">ł, Ł</format></entry> + <entry><literal>\l</literal>, + <literal>\L</literal></entry> + </row> + <row> + <entry>Ess-zet (scharfes-S)</entry> + <entry>ß</entry> + <entry><literal>\ss</literal></entry> + </row> + </tbody> + </tgroup> + </table> + <para>Irish and Turkish dotless-ı is done with the + special command <command>i</command>, so an í-fada + (which is normally typed with <keycap>í</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ċ</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-ı 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&ers;J</primary> + <see>hyphenation, justification</see> + </indexterm> + <para><LaTeX/>'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's + what you'll get—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/>'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' 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/> <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' 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'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's 2.7pt, which is nearly + 1mm, enough to be clearly visible if you'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>…</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's initials followed by their surname, as in + Prof. D. E. 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's + <emphasis>not</emphasis> the end of a sentence, and the + backslash-space forces <LaTeX/> to insert just an ordinary + word-space because it's OK to break the line after + <wordasword>Prof.</wordasword>, whereas it would look + wrong to have initials separated with Prof. D.<?html + <br>?>E. Knuth broken over a line-end.</para> + </warning> + </sect2> + <sect2> + <title>Dashes</title> + <para>For a long dash—what printers call an + <wordasword>em rule</wordasword> like this—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'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–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 (⪚ 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; 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'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>−</m:mo> + <m:mn>30</m:mn> + </informalequation>° 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'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'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' + work that <command>(</command>…<command>)</command> + and <command>[</command>…<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/>'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'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/>'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—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'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;×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;×14&inch;, a bastard cutting close to + the old Foolscap (8¼&inch;×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, ⪚</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; 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% 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'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> …<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'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's name, and the date (except + in letters, which have a special set of commands for + addressing which we'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's + date by default.</para> + <para>You always finish the metadata with the + <command>maketitle</command> command, which tells + <LaTeX/> that it'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'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' 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've cheated and <link linkend="colorpkg">done it in + colour</link> for fun—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't really ready for printing like this, + but if you'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's aimed at.</para> + <para>In both cases (reports and articles) the Abstract or + Summary is optional (that is, <LaTeX /> doesn't force you + to have one), but it'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'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'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'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'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>…<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'll + see I sneakily added an extra command to the Preamble. + We'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'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>−</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'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'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'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'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'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 I, Part 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 <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 <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'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'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' 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't bother about line-wrapping or + formatting—<LaTeX/> will take care of all + that.</para> + </listitem> + <listitem> + <para>If you'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'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'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'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'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'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've now got far enough to typeset what you've + entered. I'm assuming at this stage that you have typed + some sample text in the format specified in the previous + chapter, and you've saved it in a plain-text file with a + filetype of + <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'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'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–Z and a–z), the + digits 0–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—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'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't always come + pre-set with buttons or menus for every possible option, + because they can'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'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'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't already done so. Do it.</para> + </example> + <para>If <LaTeX/> reports any errors—easily identifiable + as lines in the log beginning with an exclamation mark + (!)—<emphasis>don'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> + </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's typesetting while it does it, + and if it encounters something it doesn't understand or can't + do, it will display a message saying what's wrong. It may + also display warnings for less serious conditions.</para> + <para><emphasis>Don't panic if you see error + messages</emphasis>: it's very common for beginners to + mistype or mis-spell commands, forget curly braces, type a + forward slash instead of a backslash, or use a special + character by mistake. Errors are easily spotted and easily + corrected in your editor, and you can then run <LaTeX/> again + to check you have fixed everything. Some of the most common + errors are described in <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'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'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'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'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—usually unsuccessfully—by interfering + with the letter-spacing, <LaTeX/> takes the view that the + author or editor should be able to contribute. While it is + certainly possible to set <LaTeX/>'s parameters so that + the spacing is sufficiently sloppy that you will almost never + get a warning about badly-fitting lines or pages, you will + almost certainly just be delaying matters until you start to + get complaints from your readers or publishers.</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'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't + mean to. This disappears after a few days as you get used to + them.</para> + <sect3 id="toomany"> + <title>Too many }'s</title> + <indexterm> + <primary>Too many }'s</primary> + </indexterm> + <indexterm> + <primary>Error messages</primary> + <secondary>Too many }'s</secondary> + </indexterm> + <programlisting> +! Too many }'s. +l.6 \date December 2004} + </programlisting> + <para>The reason <LaTeX/> thinks there are too many + <literal>}</literal>'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've missed out the opening curly brace—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'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—it'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'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–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'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'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'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'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 1 fonts, however, + and don'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'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'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's also very simple to do manually: let'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'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'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 3 (bitmap) fonts. If you are using these (either + in an old <LaTeX/> installation which has not been + upgraded to Type 1, or with files using specialist + fonts only available in Type 3 format), you will see + a very fuzzy display at low magnifications. It will print + perfectly, but Acrobat Reader's display is + disappointing. The solution is to use a better previewer + or to upgrade to the Type 1 versions of the fonts + if possible, or both. If you need to + use Type 3 fonts in <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'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' 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's for a repeatable + style we'll see in <xref linkend="macros"/> how it can + be automated and kept out of the author'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>'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'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'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's one of a few rare or + unusual packages still supplied as a single + <filename>.sty</filename> file intended for the now + obsolete <LaTeX/> 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'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/> <emphasis>local</emphasis> installation + directory tree—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 1 fonts</entry> + </row> + <row> + <entry><filename>.pfb</filename></entry> + <entry>/fonts/type1/<userinput>foundry</userinput>/<userinput>typeface</userinput></entry> + <entry>PostScript Type 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 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 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'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'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'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 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> .</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'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't treat this as a commercial + support service.</para> + <para>To access Usenet news, type the following <acronym + ref="URI"></acronym> into your browser's + <wordasword>Location</wordasword> or + <wordasword>Address</wordasword> window: + <systemitem>news:comp.text.tex</systemitem> (if your browser + doesn'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—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's more + common to need other features as well, especially if the + document is technical in nature or complex in structure.</para> + <para>It's worth pointing out that + <wordasword>technical</wordasword> doesn't necessarily mean + <wordasword>computer technical</wordasword> or + <wordasword>engineering technical</wordasword>: it just means it + contains a lot of <foreignphrase lang="gr" + remap="τηχνε">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>'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's very easy to sit down at a keyboard with a + traditional wordprocessor and just start typing. If it'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/>'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's <emphasis>my</emphasis> thesis, book, + leaflet, pamphlet, paper, article, &etc; + <emphasis>That</emphasis>'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've got that far, you're over half-way + done. Using a structural editor—even a simple + outliner—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—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> 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't type the bullet or the number or the + formatting, it'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't show it, don't + worry: most don't. <LaTeX/> will.</para> + </footnote> (•) 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/>'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'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—digits wouldn'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'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 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'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/>'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>&</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—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't type + anything—but you still need the + <literal>&</literal> separating it from the next + column'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>−</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'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't use it. + It'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'll see in a minute why you don'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'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'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't print, the chances are it's been + badly made by the graphics software. Download Adobe'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> <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'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'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't do photographs as vectors, but + it'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'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've used the <wordasword>safe</wordasword> + (MS-DOS) form of the Windows <filename>My + Pictures</filename> folder because it'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'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's galley (tray) + from the days of metal type: it accumulates typeset text until + it'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 (⪚ lists, paragraphs, + tabulations, &etc;) 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' 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'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 (⪚ <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> <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' 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' 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 1 at the start of each + chapter (but you can override that and make them run + continuously throughout the document, or even restart at 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'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'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't overlap.</para> + <para>We're jumping ahead a bit here, as we haven't + covered how to define your own commands yet. I won'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'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, ⪚</para> + <informalexample> + <programlisting> +In \S~\ref{newstuff} there is a list of recent +projects. + </programlisting> + <para>In <xref xreflabel="§" linkend="normalxref"/> + there is a list of recent projects.</para> + </informalexample> + <para>(The <command>S</command> command produces a section + sign (<literallayout role="§">\S</literallayout>) and the + <command>P</command> command produces a paragraph sign + (<literallayout role="¶">\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 <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's never any harm in having + <command>label</command>s you don't refer to, but using + <command>ref</command> when you don'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/>'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 [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>…as has clearly been shown by <citetitle + ref="fg" show="both"></citetitle>.</para> + </informalexample> + <para>Note that in this case you don't type the + author'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'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/>'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—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 (⪚ 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 + (⪚ <productname>harvard</productname>, + <productname>oxford</productname>) or the publisher or + journal which specified them (⪚ + <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't happen to like it: it'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 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—if possible: it's not always + achievable—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's hard to + hyphenate and justify well when there is little space to + manœ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'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;) 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's Compositor'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/>'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, ⪚ <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>, ⪚ + <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⅓ or 1½ 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'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'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> (⅙em), + which we saw between single and double quotes in + <xref linkend="thinspace"/>. It's also + sometimes used between the full point after + abbreviations and a following number, as in page + references like p. 199, where a word space + would look too big, and setting it solid would + look too tight.</para> + </listitem> + <listitem> + <para><command>enspace</command> (½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> (1em).</para> + </listitem> + <listitem> + <para><command>qquad</command> (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> <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 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'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 Consortium. Plus, of course, standard + <LaTeX/> can use any of the thousands of + Type 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 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="Éı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 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>…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' 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/>'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't need to edit your document text at all! + What'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>†</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="†">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's an + impossibility to combine one family with another (such as a + seriffed sans-serif typeface!). Slanted plus italics, for + example, doesn'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'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'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'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's 12pt Computer + Modern</format>, and <literallayout + remap="cmr5-12">{\font\cmbig=cmr5 at12pt\cmbig here's + 5pt Computer Modern scaled up to 12pt}</literallayout>, and + <literallayout remap="cmr17-12">{\font\cmsmall=cmr17 + at12pt\cmsmall here's 17pt Computer Modern scaled down + to 12pt}</literallayout> so you can see there really is a + significant difference. In general, you probably don'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/>'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; 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 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'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'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's + probably not important, but if you'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) It'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—such as making an index of scientific names + or product names (as in this document)—if they are + identified with a special command. Otherwise you'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'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'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'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'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'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'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, ⪚ + <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/>'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 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'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'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'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 (⪚ 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&ers;Y's + <TeX/>'n'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 (⪚ <literal>ptmr8a</literal> is [Adobe] + <abbrev>P</abbrev>ost­Script + <abbrev>T</abbrev>i<abbrev>m</abbrev>es + <abbrev>R</abbrev>oman in an + <abbrev>8</abbrev>–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&ers;Y's + <TeX/>'n'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'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'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&ers;Y's<footnote> + <para>Sadly, Y&ers;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/>'n'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'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're doing all this stuff. If you'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'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'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'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'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'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't do this, you'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'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'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'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> + <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&ers;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's a sans-serif font, make it + <command>sfdefault</command> instead.</para> + </listitem> + <listitem> + <para>Omit the command completely if you + don'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'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 414–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's not + part of font file names, it's purely a <LaTeX/> + creation, so here'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% 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 1 Computer Modern + fonts</title> + <para>Most new distributions of <LaTeX/> use the + <trademark>PostScript</trademark> Type 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 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 K.</firstname> + <surname>Malyshev</surname> + </personname>'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>'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ław</firstname> + <surname>Jackowski</surname> + </personname>'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'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 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> .</para> + </sect2> + </sect1> + </chapter> + <chapter id="macros"> + <title>Programmability (macros)</title> + <indexterm> + <primary>macros</primary> + </indexterm> + <para>We'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'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—rather a big collection—written in + <TeX/>'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, ⪚</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, + ⪚</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'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'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'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'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>™ typeset, and if + you look in the index, you'll find this page referenced + under <wordasword><format + fontshape="it">Velcro</format></wordasword>. Let's + examine what this does:</para> + <orderedlist> + <listitem> + <para>The macro is specified as having one argument + (that'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'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'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'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's a slightly more complex example, where one + macro calls another. It'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, ⪚ + <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/>'s <command>newcommand</command><footnote> + <para>Don'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'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, Leslie</quote> with virtually no effort + on the author'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/>'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/>'s internals</title> + <para><LaTeX/>'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/>'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 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's a macro called <literal>\thesection</literal> + which reproduces the current section number counter (see <xref + + linkend="thecounter"/>). It'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/>'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'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/>'s internal code (as you may have noticed in + the example earlier). And I've also used the + <wordasword>public</wordasword> macro + <command>arabic</command> to output the value of <varname + role="counter">section</varname> (<LaTeX/>'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 Introduction</format></para> + <para>What's important is that you <emphasis>don'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'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'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 ¼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—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—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't possess, so they cannot be + translated—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>…<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'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'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…</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>'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'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's + expensive and they don'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'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'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…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 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>'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­yam</surname> + </personname>'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'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–it's what I use for this book. + <productname>AbiWord</productname> can also export <LaTeX/>, + but we're going make our own + version, working from the <acronym ref="XML"></acronym> + (Brownie points for the reader who can guess why I'm + not just accepting the <LaTeX/> conversion output).</para> + <para>Although <productname>AbiWord</productname>'s + default is to output an <acronym + ref="XML"></acronym> <sgmltag>book</sgmltag> document + type, we'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's not used. Here's the + <acronym ref="XML"></acronym> output (I'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'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'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>
</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/>'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'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'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—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—if not + optimal—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—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'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>—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>'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'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—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' 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>—where things can + go—so you'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'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'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'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 (⪚ 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'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 $65 (US) per year + for individuals and $35 for students and seniors. Add + $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 $85. The current institutional rate is + $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↑</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↑</entry> + </row> + <row> + <entry>'01↑</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↓</entry> + </row> + <row> + <entry>'02↑</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↑</entry> + </row> + <row> + <entry>'03↑</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↓</entry> + </row> + <row> + <entry>'04↑</entry> + <entry remap="Space"></entry> + <entry remap="Exclamation mark">!</entry> + <entry remap="Double quote">"</entry> + <entry remap="Hash (pound)">&hash;</entry> + <entry remap="Dollar">$</entry> + <entry remap="Percent">%</entry> + <entry remap="Ampersand">&ers;</entry> + <entry remap="Apostrophe">'</entry> + <entry>''2↑</entry> + </row> + <row> + <entry>'05↑</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↓</entry> + </row> + <row> + <entry>'06↑</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↑</entry> + </row> + <row> + <entry>'07↑</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↓</entry> + </row> + <row> + <entry>'10↑</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↑</entry> + </row> + <row> + <entry>'11↑</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↓</entry> + </row> + <row> + <entry>'12↑</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↑</entry> + </row> + <row> + <entry>'13↑</entry> + <entry>X</entry> + <entry>Y</entry> + <entry>Z</entry> + <entry remap="Open bracket">[</entry> + <entry remap="Backslash">\</entry> + <entry remap="Close bracket">]</entry> + <entry remap="Caret">⁁</entry> + <entry remap="Underscore">&uline;</entry> + <entry>''5↓</entry> + </row> + <row> + <entry>'14↑</entry> + <entry remap="Grave accent">`</entry> + <entry>a</entry> + <entry>b</entry> + <entry>c</entry> + <entry>d</entry> + <entry>e</entry> + <entry>f</entry> + <entry>g</entry> + <entry>''6↑</entry> + </row> + <row> + <entry>'15↑</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↓</entry> + </row> + <row> + <entry>'16↑</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↑</entry> + </row> + <row> + <entry>'17↑</entry> + <entry>x</entry> + <entry>y</entry> + <entry>z</entry> + <entry remap="Open curly brace">{</entry> + <entry remap="Vertical bar">&vbar;</entry> + <entry remap="Close curly brace">}</entry> + <entry remap="Tilde">˜</entry> + <entry remap="Delete">DEL</entry> + <entry>''7↓</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'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'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'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'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'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'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'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…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 $65 (US) a year for + individuals and $35 for students and seniors. Add + $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 $85. The 2006 institutional + rate is $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'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>$5</entry> + </row> + <row> + <entry>Dante <acronym ref="CTAN"></acronym> <acronym + ref="CD-ROM" condition="noid"></acronym>s (2002)</entry> + <entry>$10</entry> + </row> + <row> + <entry><citetitle condition="nocite" + ref="tugboat"></citetitle> volume 23 (2002)</entry> + <entry>$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 &ers; 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'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/>…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'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é 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> |