summaryrefslogtreecommitdiff
path: root/info/beginlatex/html/chapter5.html
blob: 4e57992c95d28c29ff488ed51fa60a704072bdcb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
<!DOCTYPE html
  PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "/dtds/html4t.dtd">

<!--Generated from beginlatex.XML.xml with typebook-html.xslt on 2005-04-04T01:02:25--><html>
   <head>
      <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   
      <title>Formatting information: Chapter 5&nbsp;&#8212; CTAN, packages, and online help</title>
      <link rel="stylesheet" href="typebook.css" type="text/css">
      <meta http-equiv="Content-Style-Type" content="text/css">
   </head>
   <body>
      <table width="100%">
         <tr>
            <th class="title" width="66%">
               <h1><a name="doctitle">Formatting information</a></h1>
               <h2>A beginner's introduction to typesetting with
                  <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span></h2>
               <h3>Chapter 5&nbsp;&#8212; CTAN, packages, and online help</h3>
               <h3>Peter Flynn</h3>
               <h4>Silmaril Consultants<br>Textual Therapy Division
               </h4><br>v. 3.6 (March 2005)
            </th>
            <td class="toc" width="33%">
               <h4><a name="doctoc">Contents</a></h4>
               <dl>
                  <dd class=""><a href="intro.html#intro">Introduction</a></dd>
                  <dd class=""><a href="foreword.html#foreword">Foreword</a></dd>
                  <dd class=""><a href="preface.html#preface">Preface</a></dd>
               </dl>
               <ol>
                  <li class=""><a href="chapter1.html#get">Installing <span class="TEX">T<span class="E">E</span>X</span> and <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span></a></li>
                  <li class=""><a href="chapter2.html#plaintext">Using your editor to create documents</a></li>
                  <li class=""><a href="chapter3.html#basic">Basic document structures</a></li>
                  <li class=""><a href="chapter4.html#process">Typesetting, viewing and printing</a></li>
                  <li class="current"><a href="chapter5.html#ctan">CTAN, packages, and online help</a></li>
                  <li class=""><a href="chapter6.html#otherdoc">Other document structures</a></li>
                  <li class=""><a href="chapter7.html#texttools">Textual tools</a></li>
                  <li class=""><a href="chapter8.html#typo">Fonts and layouts</a></li>
                  <li class=""><a href="chapter9.html#macros">Programmability (macros)</a></li>
                  <li class=""><a href="chapter10.html#compat">Compatibility with other systems</a></li>
               </ol>
               <ol type="A">
                  <li class=""><a href="appendixA.html#cnf">Configuring <span class="TEX">T<span class="E">E</span>X</span> search paths</a></li>
                  <li class=""><a href="appendixB.html#tugform"><span class="TEX">T<span class="E">E</span>X</span> Users Group membership</a></li>
                  <li class=""><a href="appendixC.html#asciicharset">The ASCII character set</a></li>
                  <li class=""><a href="appendixD.html#gfdl">GNU Free Documentation License</a></li>
               </ol>
               <dl>
                  <dd class=""><a href="bibliography.html#biblio">References</a></dd>
                  <dd class=""><a href="index.html#index">Index</a></dd>
               </dl>
            </td>
         </tr>
         <tr>
            <td class="credits">
               <p>This edition of <cite>Formatting
                     	  Information</cite> was prompted by the generous help I
                  	have received from <span class="TEX">T<span class="E">E</span>X</span> 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 <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> 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. &para;&nbsp;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&nbsp;&#8212; as well as other online
                  	documents&nbsp;&#8212; dealing with mathematical typesetting in
                  <span class="TEX">T<span class="E">E</span>X</span> and <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> in finer and better detail than I am
                  	capable of. &para;&nbsp;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. &para;&nbsp;As I was finishing this edition, I was asked to review
                  	an article for <cite><a href="http://www.tug.org/pracjourn/" name="C3">The Prac<span class="TEX">T<span class="E">E</span>X</span> Journal</a></cite>, which
                  	grew out of the Practical <span class="TEX">T<span class="E">E</span>X</span> 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
                  	<em>your</em> knowledge, please let me know so
                  	that I can correct&nbsp;it. 
                  <p>Peter Flynn is author of <cite><a href="bibliography.html#htmlbook" name="C4">The HTML Handbook</a></cite> and <cite><a href="bibliography.html#sgmltools" name="C5">Understanding SGML and XML Tools</a></cite>, and editor of <cite><a href="http://www.ucc.ie/xml/" name="C6">The XML FAQ</a></cite>.
                  </p>
               </p>
            </td>
            <td class="legal">
               <p>
                  <p>This document is Copyright &copy; 1999&#8211;2005 by
                     Silmaril Consultants under the terms of what is now the GNU
                     Free Documentation License (copyleft).
                  </p>
                  <p>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 <cite><a href="http://www.fsf.org/copyleft/fdl.html" name="C1">The GNU Free Documentation License</a></cite>.
                  </p>
                  <p>You are allowed to distribute, reproduce, and modify it
                     without fee or further requirement for consent subject to the
                     conditions in <a href="appendixD.html#gfdl-4">section D.5</a>. 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 <a href="appendixD.html#gfdl">Appendix D</a>.
                     
                  </p>
               </p>
            </td>
         </tr>
      </table>
      <div class="chapter">
         <table width="100%">
            <tr>
               <td align="center"><small><i class="chaphead"><b><a name="ctan">CHAPTER</a></b></i></small><br><table border="1">
                     <tr>
                        <td class="chapno">5</td>
                     </tr>
                  </table>
               </td>
               <td><pre class="spacing"></pre></td>
               <td>
                  <p>&nbsp;</p>
                  <h1>CTAN, packages, and online help</h1>
               </td>
               <td class="toc">
                  <p>&nbsp;</p>
                  <ol>
                     <li><a href="#packages">Packages</a></li>
                     <li><a href="#pkginst">Downloading and installing packages</a></li>
                     <li><a href="#help">Online help</a></li>
                  </ol>
               </td>
               <td align="right"><a href="#doctoc"><img src="top.png" title="Table of Contents" width="32" alt="ToC" align="right" border="0"></a></td>
            </tr>
         </table>
         <p>The <a name="CTAN" class="acroref">Comprehensive <span class="TEX">T<span class="E">E</span>X</span> Archive
               	Network</a>&nbsp;(<small>CTAN</small>) is a repository of Web and <small><a href="intro.html#FTP" class="acroref" name="A110" title="File Transfer Protocol">FTP</a></small> servers worldwide which contain copies of
            almost every piece of free software related to <span class="TEX">T<span class="E">E</span>X</span> and
            <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>.
         </p>
         <p><small><a href="chapter5.html#CTAN" class="acroref" name="A111" title="Comprehensive Archive Network">CTAN</a></small> is based on three main
            servers, and there are several online indexes available. There
            are complete <span class="TEX">T<span class="E">E</span>X</span> and <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> systems for all platforms,
            utilities for text and graphics processing, conversion programs
            into and out of <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>, printer drivers, extra typefaces, and
            (possibly the most important) the <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> packages. The three
            main servers are:
         </p>
         <ul>
            <li>
               <p><span class="TEX">T<span class="E">E</span>X</span> Users Group: <a href="http://www.ctan.org/"><tt>http://www.ctan.org/</tt></a></p>
            </li>
            <li>
               <p>UK <span class="TEX">T<span class="E">E</span>X</span> Users Group: <a href="http://www.tex.ac.uk/"><tt>http://www.tex.ac.uk/</tt></a></p>
            </li>
            <li>
               <p>Deutschsprachige Anwendervereinigung <span class="TEX">T<span class="E">E</span>X</span> e.V. (DANTE,
                  	  the German-speaking <span class="TEX">T<span class="E">E</span>X</span> Users Group); <a href="http://dante.ctan.org/"><tt>http://dante.ctan.org/</tt></a></p>
            </li>
         </ul>
         <div align="center" class="sidebar">
            <table width="75%">
               <tr>
                  <td align="left" class="sidebar">
                     <p><small><a href="chapter5.html#CTAN" class="acroref" name="A112" title="Comprehensive Archive Network">CTAN</a></small> should
                        	<em>always</em> be your first port of call when
                        	looking for a software update or a feature you want to use.
                        	Please don't ask the <a href="chapter5.html#help" title="sect1">network help
                           	  resources</a> until you have checked <small><a href="chapter5.html#CTAN" class="acroref" name="A113" title="Comprehensive Archive Network">CTAN</a></small> and the <small><a href="chapter5.html#FAQ" class="acroref" name="A114" title="Frequently-Asked Questions">FAQ</a></small> (<a href="chapter5.html#faq">section 5.3.1</a>).
                     </p>
                  </td>
               </tr>
            </table>
         </div>
         <div class="sect1">
            <h2><a href="#ctan"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>5.1 <a name="packages">Packages</a></h2><a name="I80"></a><p>Add-on features for <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> are known as <b><i><a name="pack">packages</a></i></b>. Dozens of these are
               	pre-installed with <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> and can be used in your documents
               	immediately. They should all be stored in subdirectories of
               	<code>texmf/tex/latex</code> named after each package.
               	To find out what other packages are available and what they
               	do, you should use the <a href="http://www.ctan.org/search"><small><a href="chapter5.html#CTAN" class="acroref" name="A115" title="Comprehensive Archive Network">CTAN</a></small> search page</a> which includes a
               	link to Graham Williams' comprehensive package
               	catalogue.
            </p>
            <p>A package is a file or collection of files containing
               	extra <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> commands and programming which add new styling
               	features or modify those already existing. Installed package
               	files all end with <code>.sty</code> (there may be
               	  ancillary files as well).
            </p>
            <p>When you try to typeset a document which requires a
               	package which is not installed on your system, <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> will
               	warn you with an error message that it is missing (see <a href="chapter4.html#nopkg">section 4.2.3.6</a>), and you can
               	then download the package and install it using the
               	instructions in <a href="chapter5.html#pkginst">section 5.2</a>. You can also
               	download updates to packages you already have (both the ones
               	that were installed along with your version of <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> as
               	well as ones you added).
            </p>
            <p>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 <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> 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).
            </p>
            <div class="sect2">
               <h3><a href="#doctoc"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>5.1.1 <a name="colorpkg">Using an existing package</a></h3>
               <p>To use a package already installed on your system,
                  	  insert a <code class="command"><a name="c100">\usepackage</a></code> 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 <span class="package"><a name="m30">color</a></span> package, which lets
                  	  you typeset in colours (I warned you this was
                  	  coming!), you would type:
               </p>
               <blockquote><pre>
\documentclass[11pt,a4paper,oneside]{report}
\usepackage{color}
\begin{document}
...
\end{document}
        </pre></blockquote>
               <p>You can include several package names in one
                  <code class="command"><a name="c101">\usepackage</a></code> command by separating the
                  names with commas, and you can have more than one
                  <code class="command"><a name="c102">\usepackage</a></code> command.
               </p>
               <p>Some packages allow optional settings in square
                  	  brackets. If you use these, you must give the package its
                  	  own separate <code class="command"><a name="c103">\usepackage</a></code> command, like
                  	  <span class="package"><a name="m31">geometry</a></span> shown below:
               </p>
               <blockquote><pre>
\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}
        </pre></blockquote>
               <p>(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 <a href="chapter9.html#macros">Chapter 9</a> how it can
                  	  be automated and kept out of the author's way.)
               </p>
               <p>Many packages can have additional formatting
                  specifications in optional arguments in square brackets, in
                  the same way as <span class="package"><a name="m32">geometry</a></span> 
                  does. Read the documentation for the package concerned to
                  find out what can be done.
               </p>
               <blockquote class="exercise"><a name="geoex"></a><hr>
                  <h4><img src="kwrite.png" align="middle"> &nbsp; <i>Exercise 12</i>. Add colour
                  </h4>
                  <p>Use the <span class="package"><a name="m33">color</a></span> package to add
                     	    some colour to your document. Stick with primary colours
                     	    for the moment.
                  </p>
                  <p>Use the <span class="package"><a name="m34">geometry</a></span>
                     	    package to change the margins.
                  </p>
                  <p>Reprocess and print your document if you have a colour
                     	    printer (monochrome printers should print it in shades of
                     	    grey).
                  </p>
                  <hr>
               </blockquote>
               <p><small><a href="chapter8.html#CMYK" class="acroref" name="A116" title="Cyan-Magenta-Yellow-Black">CMYK</a></small> and <small><a href="chapter8.html#RGB" class="acroref" name="A117" title="Red-Green-Blue">RGB</a></small> are not the only colour
                  	    models. <a name="ul">Uwe Kern</a>'s
                  	  <span class="package"><a name="m35">xcolor</a></span> package defines half a
                  	    dozen, and includes facilities for converting colour
                  	    values from one model to another.
               </p>
            </div>
            <div class="sect2">
               <h3><a href="#doctoc"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>5.1.2 <a name="packagedoc">Package documentation</a></h3><a name="I81"></a><p>To find out what commands a package provides (and thus
                  	  how to use it), you need to read the documentation. In the
                  	  <code>texmf/doc</code> subdirectory of your
                  	  installation there should be directories full of
                  	  <code>.dvi</code> files, one for every package
                  	  installed. These can be previewed or printed like any other
                  	  <small><a href="chapter4.html#DVI" class="acroref" name="A118" title="device-independent">DVI</a></small> file (see
                  <a href="chapter4.html#dvipreview">section 4.3.1</a>). If your installation
                  	  procedure has not installed the documentation, the <small><a href="chapter4.html#DVI" class="acroref" name="A119" title="device-independent">DVI</a></small> files can all be downloaded from
                  	  <small><a href="chapter5.html#CTAN" class="acroref" name="A120" title="Comprehensive Archive Network">CTAN</a></small>.
               </p>
               <p>Before using a package, you should read the
                  documentation carefully, especially the subsection usually
                  called &#8216;User Interface&#8217;, 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.
               </p>
               <p>See the next section for details of how to create the
                  documentation <code>.dvi</code> file for additional
                  packages you install yourself.
               </p>
               <blockquote class="exercise">
                  <hr>
                  <h4><img src="kwrite.png" align="middle"> &nbsp; <i>Exercise 13</i>. Read all about it
                  </h4>
                  <p>Find and view (or print) the documentation on the
                     <span class="package"><a name="m36">geometry</a></span> package you used in
                     <a href="chapter5.html#geoex">the example &#8216;Add colour&#8217;  in section 5.1.1</a>.
                  </p>
                  <p>Investigate some of the other package documentation
                     files in the directory.
                  </p>
                  <hr>
               </blockquote>
            </div>
         </div>
         <div class="sect1">
            <h2><a href="#ctan"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>5.2 <a name="pkginst">Downloading and installing packages</a></h2><a name="I82"></a><a name="I83"></a><p>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 <small><a href="chapter5.html#CTAN" class="acroref" name="A121" title="Comprehensive Archive Network">CTAN</a></small> server to find the package you need
               	and the directory where it can be downloaded from.
            </p>
            <div class="sect2">
               <h3><a href="#doctoc"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>5.2.1 <a name="downloadpkg">Downloading packages</a></h3>
               <p>What you need to look for is always <em>two
                     	    files</em>, one ending in <code>.dtx</code>
                  	  and the other in <code>.ins</code>. The first is a
                  	  DOC<span class="TEX">T<span class="E">E</span>X</span><a name="I84"></a> file, which combines the package program and its
                  	  documentation in a single file. The second is the
                  	  installation routine (much smaller). You <em>must
                     	    always</em> download <em>both</em>
                  	  files.
               </p>
               <p>If the two files are not there, it means one of two
                  	  things:
               </p>
               <ul>
                  <li>
                     <p><em>Either</em> the package is part of a
                        	      much larger bundle which you shouldn't normally update
                        	      unless you change version of <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>;<sup><a href="#F29">1</a></sup></p>
                  </li>
                  <li>
                     <p><em>or</em> it's one of a few rare or
                        	      unusual packages still supplied as a single
                        	      <code>.sty</code> file intended for the now
                        	      obsolete <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>&#8201;2.09.<sup><a href="#F30">2</a></sup></p>
                  </li>
               </ul>
               <p><a name="packinst"></a>Download both files to a <b><i><a name="tempdir">temporary directory</a></i></b>. If you use
                  	  Windows, keep a folder like <code>C:\tmp</code> or
                  	  <code>C:\temp</code> for this; Mac and Linux systems
                  	  already have a <code>/tmp</code> directory.
               </p>
               <ol class="footnotes" start="1">
                  <li><a name="F29">For example, there is no
                        		  <code>color.dtx</code> and
                        		  <code>color.ins</code> for the
                        		  <span class="package"><a name="m37">color</a></span> package because it
                        		  forms part of the <span class="package"><a name="m38">graphics</a></span>
                        		  bundle, which is installed on all <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> systems
                        		  anyway. Such packages change very rarely, as they
                        
                        		  form part of the core of <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> and are very
                        		  stable. In
                        		  general you should never try to update these
                        		  packages in isolation.</a></li>
                  <li><a name="F30">You can try to use these if you wish but they
                        		  are not guaranteed to work, and have now almost all
                        		  been replaced by <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span>&#949;</span> versions. Always look for
                        		  the
                        		  <code>.dtx</code> and
                        		  <code>.ins</code> pair of files
                        		  first.</a></li>
               </ol>
            </div>
            <div class="sect2">
               <h3><a href="#doctoc"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>5.2.2 <a name="installpkg">Installing a package</a></h3>
               <p>There are four steps to installing a <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>
                  	  package:
               </p><a name="I85"></a><ol>
                  <li><b><a name="extract">Extract the files</a></b><br><p>Run <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> on the <code>.ins</code> file.
                        	      That is, open the file in your editor and process it as
                        	      if it were a <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> document (which is it), or if you
                        	      prefer, type <code class="literal">latex</code> followed by the
                        	      <code>.ins</code> filename in a command window
                        	      in your temporary directory.
                     </p>
                     <p>This will extract all the files needed from the
                        	      <code>.dtx</code> 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).
                     </p>
                  </li>
                  <li><b><a name="dtxdoc">Create the documentation</a></b><br><p>Run <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> on the <code>.dtx</code> file
                        	      twice. This will create a <code>.dvi</code> file
                        	      of documentation explaining what the package is for and
                        	      how to use it. Two passes through <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> are needed in
                        	      order to resolve any internal crossreferences in the
                        	      text (a feature we'll come onto later). If you
                        	      prefer to create <small><a href="chapter4.html#PDF" class="acroref" name="A122" title="Portable Document Format">PDF</a></small> then run
                        	      <i><a name="p153">pdf<span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span></a></i> instead. View or
                        	      print this file in the usual manner (see <a href="chapter4.html#dvi">section 4.3</a>).
                     </p>
                  </li>
                  <li><b>Install the files</b><br><p>While the documentation is printing, move or copy
                        	      the files created in <a href="chapter5.html#extract">step 1</a>
                        	      from your temporary directory to the right place[s] in
                        	      your <span class="TEX">T<span class="E">E</span>X</span>&nbsp;<em>local</em> installation
                        	      directory tree&nbsp;&#8212; always your &#8216;local&#8217;
                        	      directory tree,  <i>a</i>)&nbsp;to prevent your new package accidentally
                        		    overwriting files in the main <span class="TEX">T<span class="E">E</span>X</span>
                        		    directories;  and <i>b</i>)&nbsp;to avoid your newly-installed files being
                        		    overwritten when you next update your version of
                        		    <span class="TEX">T<span class="E">E</span>X</span>.
                     </p>
                     <div align="center" class="table">
                        <table>
                           <caption><i>Table 5.1</i>.&nbsp;<a name="where">Where to put files from packages</a></caption>
                           <tr class="headfoot">
                              <th valign="bottom" align="left">Type</th>
                              <th valign="bottom" align="left">Directory (under
                                 		      <code>texmf-local/</code>)
                              </th>
                              <th valign="bottom" align="left" width="216">Description</th>
                           </tr>
                           <tr>
                              <td valign="top" align="left"><code>.cls</code></td>
                              <td valign="top" align="left" style="font-family:monospace;">tex/latex/base</td>
                              <td valign="top" width="216" align="left" style="font-size:small;">Document class file</td>
                           </tr>
                           <tr>
                              <td valign="top" align="left"><code>.sty</code></td>
                              <td valign="top" align="left" style="font-family:monospace;">tex/latex/<code><u>packagename</u></code></td>
                              <td valign="top" width="216" align="left" style="font-size:small;">Style file: the normal package
                                 content
                              </td>
                           </tr>
                           <tr>
                              <td valign="top" align="left"><code>.bst</code></td>
                              <td valign="top" align="left" style="font-family:monospace;">bibtex/bst/<code><u>packagename</u></code></td>
                              <td valign="top" width="216" align="left" style="font-size:small;"><span class="BIBTEX">B<span class="I">I</span>B<span class="TEX">T<span class="E">E</span>X</span></span> style
                              </td>
                           </tr>
                           <tr>
                              <td valign="top" align="left"><code>.mf</code></td>
                              <td valign="top" align="left" style="font-family:monospace;">fonts/source/public/<code><u>typeface</u></code></td>
                              <td valign="top" width="216" align="left" style="font-size:small;">METAFONT outline</td>
                           </tr>
                           <tr>
                              <td valign="top" align="left"><code>.fd</code></td>
                              <td valign="top" align="left" style="font-family:monospace;">tex/latex/mfnfss</td>
                              <td valign="top" width="216" align="left" style="font-size:small;">Font Definition files for METAFONT fonts</td>
                           </tr>
                           <tr>
                              <td valign="top" align="left"><code>.fd</code></td>
                              <td valign="top" align="left" style="font-family:monospace;">tex/latex/psnfss</td>
                              <td valign="top" width="216" align="left" style="font-size:small;">Font Definition files for PostScript
                                 Type&nbsp;1 fonts
                              </td>
                           </tr>
                           <tr>
                              <td valign="top" align="left"><code>.pfb</code></td>
                              <td valign="top" align="left" style="font-family:monospace;">/fonts/type1/<code><u>foundry</u></code>/<code><u>typeface</u></code></td>
                              <td valign="top" width="216" align="left" style="font-size:small;">PostScript Type&nbsp;1 outline</td>
                           </tr>
                           <tr>
                              <td valign="top" align="left"><code>.afm</code></td>
                              <td valign="top" align="left" style="font-family:monospace;">/fonts/afm/<code><u>foundry</u></code>/<code><u>typeface</u></code></td>
                              <td valign="top" width="216" align="left" style="font-size:small;">Adobe Font Metrics for Type&nbsp;1
                                 fonts
                              </td>
                           </tr>
                           <tr>
                              <td valign="top" align="left"><code>.tfm</code></td>
                              <td valign="top" align="left" style="font-family:monospace;">/fonts/tfm/<code><u>foundry</u></code>/<code><u>typeface</u></code></td>
                              <td valign="top" width="216" align="left" style="font-size:small;"><span class="TEX">T<span class="E">E</span>X</span> Font Metrics for METAFONT and
                                 Type&nbsp;1 fonts
                              </td>
                           </tr>
                           <tr>
                              <td valign="top" align="left"><code>.vf</code></td>
                              <td valign="top" align="left" style="font-family:monospace;">/fonts/vf/<code><u>foundry</u></code>/<code><u>typeface</u></code></td>
                              <td valign="top" width="216" align="left" style="font-size:small;"><span class="TEX">T<span class="E">E</span>X</span> virtual fonts
                              </td>
                           </tr>
                           <tr>
                              <td valign="top" align="left"><code>.dvi</code></td>
                              <td valign="top" align="left" style="font-family:monospace;">/doc</td>
                              <td valign="top" width="216" align="left" style="font-size:small;">package documentation</td>
                           </tr>
                           <tr>
                              <td valign="top" align="left"><code>.pdf</code></td>
                              <td valign="top" align="left" style="font-family:monospace;">/doc</td>
                              <td valign="top" width="216" align="left" style="font-size:small;">package documentation</td>
                           </tr>
                           <tr>
                              <td valign="top" align="left">others</td>
                              <td valign="top" align="left" style="font-family:monospace;">tex/latex/<code><u>packagename</u></code></td>
                              <td valign="top" width="216" align="left" style="font-size:small;">other types of file unless instructed
                                 		      otherwise
                              </td>
                           </tr>
                        </table>
                     </div>
                     <p>&#8216;The right place&#8217; sometimes causes
                        	      confusion, especially if your <span class="TEX">T<span class="E">E</span>X</span> installation is old
                        	      or does not conform to the <span class="TEX">T<span class="E">E</span>X</span>
                        		Directory Structure&nbsp;(UNDEFINED ACRONYM). For a <small><a href="chapter5.html#TDS" class="acroref" name="A124" title="Directory Structure">TDS</a></small>-conformant system, this is either
                        	     <i>a</i>)&nbsp;for <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> packages, a suitably-named
                        		    subdirectory of
                        		    <code>texmf-local/tex/latex/</code><sup><a href="#F31">3</a></sup>;  or <i>b</i>)&nbsp;a suitably-named subdirectory of
                        		    <code>texmf-local/</code> for files like
                        <span class="BIBTEX">B<span class="I">I</span>B<span class="TEX">T<span class="E">E</span>X</span></span> styles which are not just for <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span> but can
                        		    be used in other <span class="TEX">T<span class="E">E</span>X</span> systems.
                     </p>
                     <p>&#8216;Suitably-named&#8217; means sensible and
                        	      meaningful (and probably short). For a package like
                        	      <span class="package"><a name="m39">paralist</a></span>, for example, I'd call
                        	      the directory <code>paralist</code>.
                     </p>
                     <p>Often there is just a <code>.sty</code> file
                        	      to move but in the case of complex packages there may be
                        	      more, and they may belong in different locations. For
                        	      example, new <span class="BIBTEX">B<span class="I">I</span>B<span class="TEX">T<span class="E">E</span>X</span></span> 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
                        	      <code>misc</code> along with other unrelated
                        	      stuff.
                     </p>
                     <p>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.
                     </p>
                  </li>
                  <li><b><a name="texindex">Update your index</a></b><br><a name="I86"></a><p>Finally, run your <span class="TEX">T<span class="E">E</span>X</span> indexer program to update
                        	      the package database. This program comes with every
                        	      modern version of <span class="TEX">T<span class="E">E</span>X</span> and is variously called
                        	      <i><a name="p154">texhash</a></i>,
                        	      <i><a name="p155">mktexlsr</a></i>, or even
                        	      <i><a name="p156">configure</a></i>, 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.
                     </p>
                  </li>
               </ol>
               <blockquote class="warning"><a name=""></a><p><img src="warning.png" align="left" alt="!!!">This last step is <em>utterly
                        	      essential</em>, otherwise nothing will
                     	    work.
                  </p>
               </blockquote>
               <blockquote class="exercise"><a name="insttest"></a><hr>
                  <h4><img src="kwrite.png" align="middle"> &nbsp; <i>Exercise 14</i>. Install a package
                  </h4>
                  <p>Download and install the
                     	    <span class="package"><a name="m40">paralist</a></span> package (which
                     	    implements inline lists).
                  </p>
                  <hr>
               </blockquote>
               <p>The reason this process has not been automated widely is
                  	  that there are still thousands of installations which do not
                  	  conform to the <small><a href="chapter5.html#TDS" class="acroref" name="A125" title="Directory Structure">TDS</a></small>, 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: <em>you</em> have to know
                  	  this. There are also systems where the owner, user, or
                  	  installer has chosen <em>not</em> to follow the
                  	  recommended <small><a href="chapter5.html#TDS" class="acroref" name="A126" title="Directory Structure">TDS</a></small> 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).
               </p>
               <p>The reason for having the
                  	  <code>texmf-local</code> directory (called
                  	  <code>texmf.local</code> 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 <span class="TEX">T<span class="E">E</span>X</span>
                  	  installation directory tree. You can also have a personal
                  	  <code>texmf</code> 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
                  	  <em>before</em> the superseded copies in the
                  	  main <code>texmf</code> tree. All modern <span class="TEX">T<span class="E">E</span>X</span>
                  	  installations should do this anyway, but if not, you can
                  	  edit <code>texmf/web2c/texmf.cnf</code> yourself.
                  	  There is an example in <a href="appendixA.html#cnf">this appendix</a>.
               </p>
               <ol class="footnotes" start="3">
                  <li><a name="F31">See <a href="chapter5.html#rightplace">section 5.2.3</a> for how
                        			to create a parallel structure in your local
                        			directory if your installation didn't create
                        			one for you.</a></li>
               </ol>
            </div>
            <div class="sect2">
               <h3><a href="#doctoc"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>5.2.3 <a name="rightplace">Replicating the TDS</a></h3>
               <p>The <a name="TDS" class="acroref"><span class="TEX">T<span class="E">E</span>X</span> Directory
                     	    Structure</a>&nbsp;(<small>TDS</small>) is documented at <a href="http://www.tug.org/tds/"><tt>http://www.tug.org/tds/</tt></a>. I find it useful to
                  	  make the directory structure of
                  	  <code>texmf-local</code> the same as that of
                  	  <code>texmf</code>. Examine the subdirectories of
                  	  <code>texmf/tex/latex/</code> for examples. For
                  	  updates of packages which came with your <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>
                  	  distribution (as distinct from new ones you are adding
                  	  yourself), you can then use the same subdirectory name and
                  	  position in <code>texmf-local/...</code> as the
                  	  original used in <code>texmf/...</code>.
               </p>
               <p>If you want to create the entire subdirectory structure
                  	  ready for use, you can do it under Unix with the following
                  	  commands:
               </p>
               <blockquote><pre>
cd /usr/TeX/texmf
find . -type d -exec mkdir -p /usr/TeX/texmf-local/{} \;
        </pre></blockquote>
               <p>If you are using Microsoft Windows, you can download
                  	  <i><a name="p157">Cygwin</a></i>, which provides you with
                  	  the standard Unix tools in a shell window. The above command
                  	  should also work on a Mac running OS&#8201;X. In all cases,
                  	  if your installation directory is not
                  	  <code>/usr/TeX</code>, you need to substitute the
                  	  actual paths to your <code>texmf</code> and
                  	  <code>texmf-local</code> directories.
               </p>
            </div>
         </div>
         <div class="sect1">
            <h2><a href="#ctan"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>5.3 <a name="help">Online help</a></h2><a name="I87"></a><p>The indexes and documentation files on <small><a href="chapter5.html#CTAN" class="acroref" name="A128" title="Comprehensive Archive Network">CTAN</a></small> are the primary online resource for
               	self-help on specific packages, and you should read these
               	carefully before asking questions about packages.
            </p>
            <div class="sect2">
               <h3><a href="#doctoc"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>5.3.1 <a name="faq">The FAQ</a></h3>
               <p>For general queries you should read the <a name="FAQ" class="acroref">Frequently-Asked Questions</a>&nbsp;(<small>FAQ</small>) document so
                  	  that you avoid wasting online time asking about things for
                  	  which there is already an easily-accessible answer.
               </p>
               <p>The <small><a href="chapter5.html#FAQ" class="acroref" name="A130" title="Frequently-Asked Questions">FAQ</a></small> is managed by the UK
                  <span class="TEX">T<span class="E">E</span>X</span> Users Group and can be found at <a href="http://www.tex.ac.uk/faq/"><tt>http://www.tex.ac.uk/faq/</tt></a>&#8201;.
               </p>
            </div>
            <div class="sect2">
               <h3><a href="#doctoc"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>5.3.2 The <span class="TEX">T<span class="E">E</span>X</span>hax mailing list
               </h3>
               <p>Another support resource is the mailing list <a href="texhax@tug.org"><tt>texhax@tug.org</tt></a>. Again, feel free to ask
                  	  questions, but again, try to answer the question yourself
                  	  first (and say what you've tried in your
                  	  message).
               </p>
            </div>
            <div class="sect2">
               <h3><a href="#doctoc"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>5.3.3 Web sites
               </h3>
               <p>The <span class="TEX">T<span class="E">E</span>X</span> Users Group, as well as most local user
                  	  groups, maintains a web site (<a href="http://www.tug.org"><tt>http://www.tug.org</tt></a>) with lots of information
                  	  about various aspects of the <span class="TEX">T<span class="E">E</span>X</span>
                  	  system.  See <a href="appendixB.html#tugform">this appendix</a> for information on
                  	  joining TUG.
               </p>
            </div>
            <div class="sect2">
               <h3><a href="#doctoc"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>5.3.4 News
               </h3>
               <p>The Usenet newsgroup <a href="news:comp.text.tex"><tt>comp.text.tex</tt></a> is the principal forum for other
                  	  questions and answers about <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>. Feel free to ask
                  	  questions, but
                  	  please do not ask frequently-asked questions: read the
                  	  <small><a href="chapter5.html#FAQ" class="acroref" name="A131" title="Frequently-Asked Questions">FAQ</a></small> 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.
               </p>
               <p>To access Usenet news, type the following <small><a href="chapter6.html#URI" class="acroref" name="A132" title="Uniform Resource Indicator">URI</a></small> into your browser's
                  	  &#8216;Location&#8217; or
                  	  &#8216;Address&#8217; window:
                  	  <code>news:comp.text.tex</code> (if your browser
                  	  doesn't support Usenet news properly, change it for one
                  	  that does, like <a href="http://www.mozilla.org/"><i><a name="p158">Mozilla</a></i></a>), or download one of the many free newsreaders.<sup><a href="#F32">4</a></sup></p>
               <ol class="footnotes" start="4">
                  <li><a name="F32">Note that this means newsreaders for the Usenet News
                        	      (NNTP) service. It does <em>not</em> mean
                        	      syndication readers for RSS, which are a different thing
                        	      entirely&nbsp;&#8212; these are unfortunately also sometimes
                        	      referred to as &#8216;newsreaders&#8217;.</a></li>
               </ol>
            </div>
            <div class="sect2">
               <h3><a href="#doctoc"><img src="up.png" title="Chapter Contents" width="32" alt="ToC" align="right" border="0"></a>5.3.5 Commercial support
               </h3>
               <p>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
                  	  <span class="TEX">T<span class="E">E</span>X</span>, or contact a consultancy which deals with <span class="TEX">T<span class="E">E</span>X</span>
                  	  (details on the TUG Web site).
               </p>
            </div>
         </div>
      </div>
      <hr>
      <table width="100%">
         <tr>
            <td align="left"><a href="chapter4.html"><img src="previous.png" alt="Previous" border="0"></a></td>
            <td align="center"><a href="#doctoc"><img src="top.png" alt="Top" border="0"></a></td>
            <td align="right"><a href="chapter6.html"><img src="next.png" alt="Next" border="0"></a></td>
         </tr>
      </table>
   </body>
</html>