summaryrefslogtreecommitdiff
path: root/help/uk-tex-faq/faq-install.tex
blob: 7c01b80fcf19dc53dada76e01f7062a490023bfa (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
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
% $Id: faq-install.tex,v 1.17 2014/01/28 18:17:36 rf10 Exp rf10 $

\section{Installing \AllTeX{} files}

\Question[Q-installthings]{Installing things on a \AllTeX{} system}
\AliasQuestion{Q-instpackages}

Installing (or replacing) things on your \AllTeX{} system has the
potential to be rather complicated; the following questions attempt to
provide a step-by-step approach, starting from the point where you've
decided what it is that you want to install:
\begin{itemize}
\item You must \Qref*{find the file you need}{Q-install-find};
\item If you are going to install a \LaTeX{} package, you may need to
  \Qref*{unpack the distributed files}{Q-install-unpack};
\item It may be necessary to % ! line break
  \Qref*{generate some documentation to read}{Q-install-doc};
\item You need to % ! line break
  \Qref*{decide where to install the files}{Q-install-where};
\item You must now \Qref*{install the files}{Q-inst-wlcf}; and
  finally
\item You may need to \Qref*{tidy up}{Q-inst-tidy} after the installation.
\end{itemize}

\Question[Q-install-find]{Finding packages to install}

How did you learn about the package?

If the information came from these \acro{FAQ}s, you should already
have a link to the file (there are lists of packages at the end of
each answer).
\begin{narrowversion}
  Make a browser link from \URL{http://mirror.ctan.org/} and the text
  in the package list; if the link returns a directory listing, you can
  generally retrieve the whole directory by appending the link with
  \extension{zip}~--- so, for example
  \URL{http://mirror.ctan.org/macros/latex/doc.zip} for the \latex{}
  documentation directory.
\end{narrowversion}
\begin{wideversion}
  Click on one of the links associated with the package, and you can
  get the package (which may be one file or several).
% need separate wording for pdfversion and htmlversion, here
\end{wideversion}

If you heard about the file somewhere else, it's possible that the
source told you where to look; if not, try the \acro{CTAN} searching
facilities, such as \URL{http://www.tex.ac.uk/search/}.  That (rather
simple) search engine can return data from a search of the CTAN
catalogue (which covers most useful packages), or data from a search
of the names of files on the archive.

Packages come in a variety of different styles of distribution; the
very simplest will actually offer just \File{package.sty}~--- in this
case, just download the file and % ! line break
\Qref*{get on with installation}{Q-inst-wlcf}.

You will regularly find that the file you want (e.g., \File{foo.sty})
is distributed in a \LaTeX{} documented source file \File{foo.dtx};
thus you should search just for \emph{foo}~--- \File{foo.sty} won't be
visible anywhere on the archive or in the catalogue.

Since most packages are distributed in this
\extension{dtx}/\extension{ins} way, they usually occupy their own
directory on the archive.  Even if that directory contains other
packages, you should download everything in the directory: as often as
not, packages grouped in this way depend on each other, so that you
really \emph{need} the other ones.

Having acquired the package distribution, % ! line break
``\Qref*{unpacking \LaTeX{} packages}{Q-install-unpack}'' outlines
your next step.

\Question[Q-install-unpack]{Unpacking \LaTeX{} packages}

As discussed \Qref*{elsewhere}{Q-dtx}, the `ordinary' way to
distribute a \LaTeX{} package is as a pair of files \File{package.dtx}
and \File{package.ins}.  If you've acquired such a pair, you simply
process \File{package.ins} with \LaTeX{}, and the files will appear,
ready for installation.

Other sorts of provision should ordinarily be accompanied by a
\File{README} file, telling you what to do; we list a few example
configurations.

Sometimes, a directory comes with a bunch of \extension{dtx} files, but
fewer (often only one) \extension{ins} files (\LaTeX{} itself comes
looking like this).  If there is more than one \extension{ins} file,
and in the absence of any instruction in the \File{README} file, simply
process the \extension{ins} file(s) one by one.

If you're missing the \File{package.ins} altogether, you need to play
around until something works.  Some \extension{dtx} files are
``self-extracting''~--- they do without an \extension{ins} file, and once
you've processed the \File{package.dtx}, \File{package.sty} has
automagically appeared.  Various other oddities may appear, but the
archivists aim to have \File{README} file in every package, which
should document anything out of the ordinary with the distribution.

\Question[Q-install-doc]{Generating package documentation}

We are faced with a range of ``normal'' provision, as well as several
oddities.  One should note that documentation of many packages is
available on \acro{CTAN}, without the need of any further effort by
the user~--- such documentation can usually be browsed \emph{in situ}.

However, if you find a package that does not offer documentation on
the archive, or if you need the documentation in some other format
than the archive offers, you can usually generate the documentation
yourself from what you download from the archive.

The standard mechanism, for \LaTeX{} packages, is simply to run
\LaTeX{} on the \File{package.dtx} file, as you would any ordinary
\LaTeX{} file (i.e., repeatedly until the warnings go away).

A variant is that the unpacking process provides a file
\File{package.drv}; if such a thing appears, process it in preference
to the \File{package.dtx} (it seems that when the documented \LaTeX{}
source mechanism was first discussed, the \File{.drv} mechanism was
suggested, but it's not widely used nowadays).

Sometimes, the \LaTeX{} run will complain that it can't find
\File{package.ind} (the code line index) and/or \File{package.gls}
(the list of change records, not as you might imagine, a glossary).
Both types of file are processed with special \ProgName{makeindex}
style files; appropriate commands are:
\begin{quote}
\begin{verbatim}
makeindex -s gind package
makeindex -s gglo -o package.gls package.glo
\end{verbatim}
\end{quote}
This author finds that the second (the change record) is generally of
limited utility when reading package documentation; it is, however,
valuable if you're part of the package development team.  If you don't
feel you need it, just leave out that step

Another common (and reasonable) trick performed by package authors is
to provide a separate file \File{package-doc.tex} or even simply
\File{manual.tex}; if the file \File{package.dtx} doesn't help, simply
look around for such alternatives.  The files are treated in the same
way as any ``ordinary'' \LaTeX{} file.

\Question[Q-inst-wlcf]{Installing files ``where \AllTeX{} can find them''}
\AliasQuestion{Q-wherefiles}

In the past, package documentation used always to tell you to put your
files ``where \LaTeX{} can find them''; this was always unhelpful~---
if you knew where that \emph{was}, you didn't need telling, but if you
\emph{didn't} know, you were completely stuck.

It was from this issue that the whole idea of the \acro{TDS} sprang;
``where to put'' questions now come down to ``where's the \acro{TDS}
tree?''.

We therefore answer the question by considering:
\begin{itemize}
\item \Qref*{what tree to use}{Q-what-TDS}, and
\item \Qref*{where in the tree to put the files}{Q-install-where}.
\end{itemize}

Once we know the answer to both questions, and we've created any
directories that are needed, we simply copy files to their rightful
location.

This has done what the old requirement specified: \LaTeX{} (or
whatever) \emph{can} (in principle) find the files.  However, in order
that the software \emph{will} find the files, we need to update an
index file.

On a \miktex{} system, open the window
  \texttt{Start}\arrowhyph{}%
  \texttt{All Programs}\arrowhyph{}%
  \texttt{\miktex{} \meta{version}}\arrowhyph{}%
  \texttt{Settings},
and click on \texttt{Refresh FNDB}.
The job may also be done in a command window, using the command:
\begin{quote}
\begin{verbatim}
initexmf --update-fndb
\end{verbatim}
\end{quote}
The % ! line break
\href{http://docs.miktex.org/manual/initexmf.html}{\miktex{} documentation}
gives further details about \texttt{initexmf}.

On a \texlive{}-based system (or its predecessor te\TeX{}, use the command
\texttt{texhash} (or if that's not available, \texttt{mktexlsr}~---
they ought to be different names for the same program).

Having done all this, the new package will be available for use.

\Question[Q-what-TDS]{Which tree to use}

In almost all cases, new material that you install should go into the
``local'' tree of your \AllTeX{} installation.  (A discussion of
reasons \emph{not} to use the local tree appears below.)

On a Unix(-alike) system, using \texlive{} or te\TeX{}, the root
directory will be named something like \path{/usr/share/texmf-local/}
or \path{/usr/local/share/texmf/}
You can ask such a system where it believes a local tree should be:
\begin{quote} 
\begin{verbatim}
kpsewhich -var-value TEXMFLOCAL
\end{verbatim}
\end{quote}
the output being the actual path, for example (on the workstation this
author is using today):
\begin{quote}
\begin{verbatim}
/usr/local/share/texmf
\end{verbatim}
\end{quote}

In a \miktex{} installation, the location will in fact typically be
something you specified yourself when you installed \miktex{} in the
first place, but you may find you need to create one.  The \miktex{}
``Settings'' window (%
  \texttt{Start}\arrowhyph{}%
  \texttt{Programs}\arrowhyph{}%
  \texttt{\miktex{}}\arrowhyph{}%
  \texttt{Settings})
has a tab ``\texttt{Roots}''; that tab gives a list of current
\acro{TDS} roots (they're typically not called
\texttt{texmf}-anything).  If there's not one there with
``\texttt{local}'' in its name, create an appropriate one (see below),
and register it using the window's
``\texttt{Add}'' button.

The % ! line break
\href{http://docs.miktex.org/faq/maintenance.html}{\miktex{} \acro{FAQ}}
suggests that you should create % ! line break
``\texttt{C:\textbackslash Local TeX Files}'', which is good if you
manage your own machine, but often not even possible in corporate, or
similar, environments~--- in such situations, the user may have no
control over the hard disc of the computer, at all.

So the real criterion is that your local tree should be somewhere that
\emph{you}, rather than the system, control.  Restrictive systems often
provide a ``home directory'' for each user, mounted as a network
drive; this is a natural home for the user's local tree.  Other (often
academic) environments assume the user is going to provide a memory
stick, and will assign it a defined drive letter~--- another good
candidate location.  Note that the semantics of such a tree are
indistinguishable from those of a % ! line break
\Qref*{``home'' \acro{TEXMF} tree}{Q-privinst}.

You might not wish to use the `local' tree:
\begin{itemize}
\item if the package, or whatever, is ``personal'' (for example,
  something commercial that has been licensed to you alone, or
  something you're developing yourself), it should go in your
  \Qref*{``home'' \acro{TEXMF} tree}{Q-privinst};
\item if you \emph{know} that the package you are installing is a
  replacement for the copy on the \acro{TEXMF} tree of your \AllTeX{}
  distribution; in this case it is reasonable to replace the existing
  copy in the \acro{TEXMF} tree.
\end{itemize}
If the system is upgraded (or otherwise re-installed), a copy made in
the \acro{TEXMF} tree will probably be overwritten or deleted.  This
may be what you want, but otherwise it's a powerful incentive to use a
tree that is \emph{not} ``part of the installed system''.

The reason one might place upgrades the distribution's main tree is to
avoid confusion.  Suppose you were to place the file on the local
tree, and then install a new version of the distribution~--- you might
have an effect like:
\begin{itemize}
\item distribution comes with package version \ensuremath{n};
\item you install package version \ensuremath{n+1} on the local tree; and
\item the updated distribution provides package version \ensuremath{n+2}.
\end{itemize}
In such a situation, you could find yourself using version
\ensuremath{n+1} (from the local tree) \emph{after} the new
distribution has been installed.

If you install in the local tree, the only way to avoid such problems
is to carefully purge the local tree when installing a new
distribution.  This is tedious, if you're maintaining a large
installation.

\Question[Q-install-where]{Where to install packages}

We assume here that you have decided what tree to put your files in,
after reading % ! line break
``\Qref*{choosing a \acro{TDS} tree}{Q-what-TDS}''.  We will therefore
write \texttt{\$TEXMF} for it, and you need to substitute the tree
you decided on.

The basic idea is to imitate the directory structure in your
existing tree(s). Here are some examples of where various sorts of
files should go:
\begin{verbatim}
.sty, .cls or .fd: $TEXMF/tex/<format>/<package>/
.mf:   $TEXMF/fonts/source/<supplier>/<font>/
.tfm:  $TEXMF/fonts/tfm/<supplier>/<font>/
.vf:   $TEXMF/fonts/vf/<supplier>/<font>/
.afm:  $TEXMF/fonts/afm/<supplier>/<font>/
.pfb:  $TEXMF/fonts/type1/<supplier>/<font>/
.ttf:  $TEXMF/fonts/truetype/<supplier>/<font>/
.otf:  $TEXMF/fonts/opentype/<supplier>/<font>/
.pool, .fmt, .base or .mem: $TEXMF/web2c
\end{verbatim}
and for modern systems (those distributed in 2005 or later, using \acro{TDS}
v1.1 layouts):
\begin{verbatim}
.map:  $TEXMF/fonts/map/<syntax>/<bundle>/
.enc:  $TEXMF/fonts/enc/<syntax>/<bundle>/
\end{verbatim}
(Map and encoding files went to directories under
\File{$TEXMF/dvips/}, %$
in earlier distributions.)

In the lists above \meta{format} identifies the format the macros
are designed for~--- it can be things such as \texttt{plain},
\texttt{generic} (i.e., any format), \texttt{latex} or
\texttt{context} (or several less common formats).

For fonts, \meta{font} refers to the font family (such as \texttt{cm}
for Knuth's Computer Modern, \texttt{times} for Adobe's Times Roman).
The supplier is usually obvious~--- the supplier
``public'' is commonly used for free fonts.

The \meta{syntax} (for \extension{map} and \extension{enc} files) is a
categorisation based on the way the files are written; candidates are
names of programs such as \ProgName{dvips} or \ProgName{pdftex}.

``Straight'' \AllTeX{} input can take other forms than the
\extension{sty}, \extension{cls} or \extension{fd} listed above, too
(apart from the `obvious' \extension{tex}).  Examples are (the
obvious) \extension{tex}, \extension{lfd} for \Package{babel} language
definitions, \extension{sto} and \extension{clo} for package and class
options, \extension{cfg} for configuration information,
\extension{def} for variants (such as the types of devices
\Package{graphics} drives).  The \File{README} of the package should
tell you of any others, though sometimes that information is printed
when the package's \Qref*{comments are stripped}{Q-install-unpack}.
All of these files should live together with the main package files.

Note that \meta{font} may stand for a single font or an entire family:
for example, files for all of Knuth's Computer Modern fonts are to be
found in \texttt{.../public/cm}, with various prefixes as appropriate.

The font ``supplier'' \emph{public} is a sort of hold-all for
``free fonts produced for use with \AllTeX{}'': as well as Knuth's
fonts, \emph{public}'s directory holds fonts designed by others
(originally, but no longer exclusively, in \MF{}).

Documentation for each package should all go, undifferentiated, into a
directory on the \path{doc/} subtree of the \acro{TDS}.  The layout of
the subtree is slightly different: \path{doc/latex} hosts all
\LaTeX{} documentation directories, but more fundamental things are
covered, e.g., by \path{doc/etex} or \path{doc/xetex}.

\Question[Q-inst-tidy]{Tidying up after installation}

There's not usually a lot to do after you've completed the steps
above~--- indeed, if you're merely installed files direct from the
archive, or whatever, there will be precisely nothing left, by way of
debris.

Things you might care to clean up are:
\begin{itemize}
\item the archive file, if you retrieved your data from the archive
  as a \extension{zip} file, or the like;
\item the \extension{dtx} and \extension{ins} files, if you chose not
  to install them with the documentation; and
\item the \extension{aux}, \extension{log}, \extension{idx}, etc.,
  from building the documentation.
\end{itemize}
A simple way of achieving all this is to download to a working
directory that was created for the purpose, and then to delete that
directory and all its contents after you've finished installing.

\Question[Q-inst-scut]{Shortcuts to installing files}

There are circumstances in which most of the fuss of installation can
be bypassed:
\begin{itemize}
\item If you are a \miktex{} user, the 
\begin{hyperversion}
  \Qref{\miktex{} package management system}{Q-inst-miktex*}
  can usually help;
\end{hyperversion}
\begin{flatversion}
  \miktex{} package management system can usually help
  (\Qref{}{Q-inst-miktex*});
\end{flatversion}
\item Similarly, if you are a \texlive{} user, the 
\begin{hyperversion}
  \Qref{\texlive{} manager}{Q-inst-texlive}
  can usually help;
\end{hyperversion}
\begin{flatversion}
  \texlive{} package management system can usually help
  (\Qref{}{Q-inst-texlive});
\end{flatversion}
\item The package you want may already exist as a \acro{ZIP} file
\begin{wideversion}
  formatted for \Qref{direct installation}{Q-inst-tds-zip}.
\end{wideversion}
\begin{narrowversion}
  formatted for direct installation (\Qref{}{Q-inst-tds-zip}).
\end{narrowversion}
\end{itemize}

\Question[Q-inst-miktex*]{Installation using \miktex{} package manager}
\AliasQuestion{Q-inst-miktex}

Packages for use with \miktex{} are maintained very efficiently by the
project managers (new packages and updates on \acro{CTAN} ordinarily
make their way to the \miktex{} package repository within a week).
Thus it makes sense for the \miktex{} user to take advantage of the
system rather than grinding through the steps of installation.

\miktex{} maintains a database of packages it ``knows about'',
together with (coded) installation instructions that enable it to
install the packages with minimal user intervention; you can update
the database over the internet.

If \miktex{} does know about a package you need installed, it's worth
using the system:
first, open the \miktex{} packages window: click on
  \texttt{Start}\arrowhyph{}%
  \texttt{Programs}\arrowhyph{}%
  \texttt{MiKTeX}\arrowhyph{}%
  \texttt{MiKTeX Options}, and select the
  \texttt{Packages} tab.
  
On the tab, there is an Explorer-style display of packages.
Right-click on the root of the tree, ``\texttt{MiKTeX Packages}'',
and select ``\texttt{Search}'': enter the name of the package you're
interested in, and press the ``\texttt{Search}'' button.  If
\miktex{} knows about your package, it will open up the tree to show
you a tick box for your package: check that box.

If you prefer a command-line utility, there's \ProgName{mpm}.  Open a
command shell, and type:
\begin{quote}
\begin{verbatim}
mpm --install=<package>
\end{verbatim}
\end{quote}
(which of course assumes you know the name by which \miktex{} refers to
your package).

\Question[Q-inst-texlive]{Installation using \texlive{} manager}

\texlive{} manager (\ProgName{tlmgr}) is, by default, a shell (or
Windows terminal window) command.  There is voluminous documentation
about it from the command
\begin{quote}
  \texttt{tldoc tlmgr}
\end{quote}
but basic operation is pretty straightforward.  The manager needs to
know where to download stuff from; the canonical setup is
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
tlmgr option repository \
  http://mirror.ctan.org/systems/texlive/tlnet
\end{verbatim}
(line wrapped to fit in the narrow column)
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet
\end{verbatim}
\end{wideversion}
\end{quote}
which passes the decision to the mirror selector.  You can (of course)
specify a particular archive or mirror that you ``trust'', or even a
local disc copy that you keep up-to-date (disc space and bandwidth are
so cheap nowadays, that a ``home mirror'' of \acro{CTAN} is a feasible
proposition).

To update a single package, use:
\begin{quote}
\begin{verbatim}
tlmgr update <package>
\end{verbatim}
\end{quote}

To update everything you already have in your installation, use:
\begin{quote}
\begin{verbatim}
tlmgr update --all
\end{verbatim}
\end{quote}

\Question[Q-inst-tds-zip]{Installing using ready-built \acro{ZIP} files}

Installing packages, as they (``traditionally'') appear on
\acro{CTAN}, involves:
\begin{itemize}
\item identifying where to put the various files on an \acro{TDS}
  tree,
\item installing them, and
\item a few housekeeping operations.
\end{itemize}
Most people, for most packages, find the first two steps onerous, the
last being easy (unless it is forgotten!).

Ready-built \acro{ZIP} files~--- also known as % ! line break
\Qref*{\acro{TDS}-\acro{ZIP} files}{Q-tds-zip}~--- are designed to lighten
the load of performing the first two steps of installation: they
contain all the files that are to be installed for a given
package, in their ``correct'' locations in a % ! line break
\Qref*{\acro{TDS} tree}{Q-tds}.

To install such a file on a Unix system (we assume that you'll install
into the local \acro{TEXMF} tree, at \texttt{\$TEXMFLOCAL}):
\begin{quote}
\begin{verbatim}
cd $TEXMFLOCAL
unzip $package.tds.zip
\end{verbatim}
\end{quote}

On a Windows system that is modern enough that it has a built-in
\acro{ZIP} unpacker, simply double-click on the file, and browse to
where it's to be unpacked.  (We trust that those using earlier
versions of Windows will already have experience of using
\ProgName{WinZIP} or the like.)

Having unpacked the \extension{zip} archive, in most cases the only
remaining chore is to update the file indexes~--- as in % ! line break
\Qref*{normal installation instructions}{Q-inst-wlcf}.  However, if
the package provides a font, you also need to enable the font's map,
which is discussed in % ! line break
``\Qref*{Installing a Type~1 font}{Q-instt1font}''
\LastEdit{2012-02-08}

\Question[Q-tempinst]{``Temporary'' installation of \AllTeX{} files}

Operating systems and applications need to know where to find files:
many files that they need are ``just named''~--- the user doesn't
necessarily know \emph{where} they are, but knows to ask for them.
The commonest case, of course, is the commands whose names you type to
a shell (yes, even Windows' ``\MSDOS{} prompt'') are using a shell to read what
you type: many of the commands simply involve loading and executing a
file, and the \texttt{PATH} variable tells the shell where to find those files.

Modern \TeX{} implementations come with a bunch of search paths
built in to them.  In most circumstances these paths are adequate, but
one sometimes needs to extend them to pick up files in strange
places: for example, we may wish to try a new bundle of packages
before \Qref*{installing them `properly'}{Q-installthings}.  To do
this, we need to change the relevant path as \TeX{} perceives it.
However, we don't want to throw away \TeX{}'s built-in path (all of a
sudden, \TeX{} won't know how to deal with all sorts of things).

To \emph{extend} a \TeX{} path, we define an operating system
environment variable in `path format', but leaving a gap which \TeX{}
will fill with its built-in value for the path.  The commonest case is
that we want to place our extension in front of the path, so that our
new things will be chosen in preference, so we leave our `gap to be
filled' at the end of the environment variable.  The syntax is simple
(though it depends which shell you're actually using): so on a
Unix-like system, using the \ProgName{bash} shell, the job might be
done like:
\begin{quote}
\begin{verbatim}
export TEXINPUTS=/tmp:
\end{verbatim}
\end{quote}
while in a Windows system, within a \MSDOS{} window, it would be:
\begin{quote}
\begin{verbatim}
set TEXINPUTS=C:/temp;
\end{verbatim}
\end{quote}
In either case, we're asking \TeX{} to load files from the root disc
temporary files directory; in the Unix case, the ``empty slot'' is
designated by putting the path separator `|:|' on its own at the end
of the line, while in the Windows case, the technique is the same, but
the path separator is `|;|'.

Note that in either sort of system, the change will only affect
instances of \TeX{} that are started from the shell where the
environment variable was set.  If you run \TeX{} from another window,
it will use the original input path.  To make a change of input path
that will ``stick'' for all windows, set the environment variable in
your login script or profile (or whatever) in a Unix system and log
out and in again, or in \File{autoexec.bat} in a Windows system, and
reboot the system.

While all of the above has talked about where \TeX{} finds its macro
files, it's applicable to pretty much any sort of file any
\TeX{}-related program reads~--- there are lots of these paths, and of
their corresponding environment variables.  In a
\ProgName{web2c}-based system, the copious annotations in the
\File{texmf.cnf} system configuration file help you to learn which
path names correspond to which type of file.

\Question[Q-privinst]{``Private'' installations of files}

It sometimes happens that you need a new version of some macro package
or font, but that the machine you use is maintained by someone who's
unwilling to update and won't give you privileges to do the job
yourself.  A \Qref*{``temporary'' installation}{Q-tempinst} is
sometimes the correct approach, but if there's the slightest chance
that the installation will be needed on more than one project,
temporary installations aren't right.

In circumstances where you have plenty of quota on backed-up media, or
adequate local scratch space, the correct approach is to create a
private installation of \AllTeX{} which includes the new stuff you
need; this is the ideal, but is not generally possible.

So, since you can't install into the public \texttt{texmf} tree, you
have to install into a \File{texmf} tree of your own; fortunately, the
\acro{TDS} standard allows for this, and modern distributions allow
you to do it.  The most modern distributions refer to the tree as
\texttt{\$TEXMFHOME}, but it used to be called \texttt{\$HOMETEXMF};
so to check that your \TeX{} system does indeed support the mechanism
you should start with
\begin{quote}
\begin{verbatim}
kpsewhich -var-value TEXMFHOME
\end{verbatim}
\end{quote}
(for example).  This will almost invariably return a pointer to a
subdirectory \File{texmf} of your home directory; the commonest
exception is Macintoshes, using Mac\TeX{}, where the diretory is
conventionally \File{Library/texmf} in your home directory.

If you can confirm that the technique does indeed work, install your
new package (or whatever) in the \Qref*{correct place}{Q-install-where}
in a tree based on \File{$HOME/texmf}, %$
and generate an index of that tree
\begin{quote}
\begin{verbatim}
texhash $HOME/texmf
\end{verbatim}
\end{quote}
(the argument specifies which tree you are indexing: it's necessary
since you don't, by hypothesis, have access to the main tree, and
\ProgName{texhash} without the argument would try to write the main
tree.

There are two wrinkles to this simple formula: first, the installation
you're using may \emph{not} define a home TEXMF directory, and second,
there may be some obstruction to using \File{$HOME/texmf} %$
as the
default name.  In either case, a good solution is to have your own
\File{texmf.cnf}~--- an idea that sounds more frightening that it
actually is.  The installation's existing file may be located with the
command:
\begin{quote}
\begin{verbatim}
kpsewhich texmf.cnf
\end{verbatim}
\end{quote}
Take a copy of the file and put it into a directory of your own; this
could be any directory, but an obvious choice is the \File{web2c}
directory of the tree you want to create, i.e.,
\File{$HOME/texmf/web2c} %$
or the like.  Make an environment variable to
point to this directory:
\begin{quote}
\begin{verbatim}
TEXMFCNF=$HOME/texmf/web2c
export TEXMFCNF
\end{verbatim}
\end{quote}
(for a Bourne shell style system), or
\begin{quote}
\begin{verbatim}
setenv TEXMFCNF $HOME/texmf/web2c
\end{verbatim}
\end{quote}
(for a C-shell style system).  Now edit the copy of \File{texmf.cnf}

There will be a line in the existing file that defines the tree where
everything searches; the simplest form of the line is:
\begin{quote}
\begin{verbatim}
TEXMF = !!$TEXMFMAIN
\end{verbatim}
\end{quote}
but, there are likely to be several alternative settings behind
comment markers (``\texttt{\textpercent{}}''), and the person who 
installed your system may have left them there.  Whatever, you need to
modify the line that's in effect: change the above to three lines:
\begin{quote}
\begin{verbatim}
HOMETEXMF = $HOME/texmf
TEXMF = {$HOMETEXMF,!!$TEXMFMAIN}
% TEXMF = !!$TEXMFMAIN
\end{verbatim}
\end{quote}
the important point being that \texttt{\$HOMETEXMF} must come before
whatever was there before, inside the braces.  For example, if the
original was
\begin{quote}
\begin{verbatim}
TEXMF = {!!$LOCALTEXMF,!!$TEXMFMAIN}
\end{verbatim}
\end{quote}
it should be converted to:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
HOMETEXMF = $HOME/texmf
TEXMF = {$HOMETEXMF,!!$LOCALTEXMF,
                     !!$TEXMFMAIN}
% TEXMF = {!!$LOCALTEXMF,!!$TEXMFMAIN}
\end{verbatim}
{\small Note that the \texttt{TEXMF} line is only wrapped to make it
  fit in the column; there should be no line break or space between
  the final comma on the line and the \texttt{!!} on the next line.\par
}%
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
HOMETEXMF = $HOME/texmf
TEXMF = {$HOMETEXMF,!!$LOCALTEXMF,!!$TEXMFMAIN}
% TEXMF = {!!$LOCALTEXMF,!!$TEXMFMAIN}
\end{verbatim}
\end{wideversion}
\end{quote}
(retaining the original, as a comment, is merely an aide-memoir in
case you need to make another change, later).  The \texttt{!!} signs
tell the file-searching library that it should insist on a
\ProgName{texhash}-ed directory tree; if you can count on yourself
remembering to run \ProgName{texhash} on your new tree every time you
change it, then it's worth adding the marks to your tree:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
TEXMF = {!!$HOMETEXMF,!!$LOCALTEXMF,
                       !!$TEXMFMAIN}
\end{verbatim}
{\small Note that the line is only wrapped to make it
  fit in the column; there should be no line break or space between
  the final comma on the line and the \texttt{!!} on the next line.\par
}%
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
TEXMF = {!!$HOMETEXMF,!!$LOCALTEXMF,!!$TEXMFMAIN}
\end{verbatim}
\end{wideversion}
\end{quote}
as this will make \AllTeX{} find its files marginally faster.

Having made all these changes, \AllTeX{} should ``just use'' files in
your new tree, in preference to anything in the main tree~--- you can
use it for updates to packages in the main tree, as well as for
installing new versions of things.
\LastEdit{2011-04-13}

\Question[Q-instfont]{Installing a new font}

Fonts are really ``just another package'', and so should be installed
in the same sort of way as packages.  However, fonts tend to be more
complicated than the average package, and as a result it's sometimes
difficult to see the overall structure.

Font files may appear in any of a large number of different formats;
each format has a different function in a \TeX{} system, and each is
stored in a directory its own sub-tree in the installation's
\acro{TDS} tree; all these sub-trees have the directory
\File{$TEXMF/fonts} %$
as their root.  A sequence of answers\nothtml{, below,} describes the
installation of fonts\latexhtml{.}{:}
\begin{htmlversion}
follow the list through the ``next question'' links at the bottom of
this answer to view them all.
\end{htmlversion}
Other answers discuss specific font families~--- for example,
% ! line break
``\Qref*{using the concrete fonts}{Q-concrete}''.

\Question[Q-instmffont]{Installing a font provided as \MF{} source}

Installing Metafont fonts is (by comparison with other sorts of font) rather
pleasingly simple.  Nowadays, they are mostly distributed just as the
\MF{} source, since modern \TeX{} distributions are able to produce
everything the user needs ``on the fly''; however, if the distribution
\emph{does} include \acro{TFM} files, install them too, since they
save a little time and don't occupy much disc space.  Always distrust
distributions of \acro{PK} font bitmap files: there's no way of
learning from them what printer they were generated for, and naming
schemes under different operating systems are another source of
confusion.

``\Qref*{Where to install files}{Q-install-where}''
specifies where the files should go.

Further confusion is introduced by font families whose authors devise rules
for automatic generation of \MF{} sources for generating fonts at
particular sizes; the installation has to know about the rules, as
otherwise it cannot generate font files.  No general advice is
available, but most such font families are now obsolescent.

\Question[Q-instprinterfont]{`Installing' a \PS{} printer built-in font}

There is a ``standard'' set of fonts that has appeared in every \PS{}
printer since the second generation of the type.  These fonts
(8~families of four text fonts each, and three special-purpose fonts)
are of course widely used, because of their simple availability.  The
set consists of:
\begin{itemize}
\item \FontName{Times} family (4 fonts)
\item \FontName{Palatino} family (4 fonts)
\item \FontName{New} \FontName{Century} \FontName{Schoolbook} family (4 fonts)
\item \FontName{Bookman} family (4 fonts)
\item \FontName{Helvetica} family (4 fonts)
\item \FontName{Avant} \FontName{Garde} (4 fonts)
\item \FontName{Courier} family (4 fonts)
\item \FontName{Utopia} family (4 fonts)
\item Zapf \FontName{Chancery} (1 font)
\item Zapf \FontName{Dingbats} (1 font)
\item \FontName{Symbol} (1 font)
\end{itemize}
All these fonts are supported, for \LaTeX{} users, by the
\Package{psnfss} set of metrics and support files in the file
\File{lw35nfss.zip} on \acro{CTAN}.  Almost any remotely modern \TeX{}
system will have some version of \Package{psnfss} installed, but
users should note that the most recent version has much improved
coverage of maths with \FontName{Times} (see package
\Package{mathptmx}) and with \FontName{Palatino} (see package
\Package{mathpazo}, as well as a more reliable set of font metrics.

The archive \File{lw35nfss.zip} is laid out according to the
\acro{TDS}, so in principle, installation consists simply of
``unzipping'' the file at the root of a \path{texmf} tree.

Documentation of the \Package{psnfss} bundle is provided in
\File{psnfss2e.pdf} in the distribution.
\begin{ctanrefs}
\item[mathpazo.sty]Part of the \Package{psnfss} bundle
\item[mathptmx.sty]Part of the \Package{psnfss} bundle
\item[psnfss \nothtml{\rmfamily}bundle]\CTANref{psnfss}
\end{ctanrefs}

\Question[Q-prept1font]{Preparing a Type~1 font}

The process of installing a Type~1 font set is rather convoluted, and
we will deal with it in two chunks: first (in the present answer)
preparing the font for installation, and second % ! line break
\Qref*{installing a Type~1 font}{Q-instt1font}).

Many fonts are supplied in \AllTeX{} ready form: such fonts need no
preparation, and may be installed immediately.

However, if you purchase a font from a Type foundry (either direct or
via one of the web stores), you are likely to need to `prepare' it for
use with \AllTeX{}.  The rest of this answer discusses this preparation.
\begin{itemize}
\item Acquire the font.  A very small set of Type~1 fonts is installed
  in most \PS{} printers you will encounter.  For those few (whose use
  is covered by the basic \acro{PSNFSS} package), you don't need the
  Type~1 font itself, to be able to print using the font.

  For all the myriad other Type~1 fonts, to be able to print using
  the font you need the Type~1 file itself.  Some of these are
  available for free (they've either been donated to the public
  domain, or were developed as part of a free software project), but
  the vast majority are commercial products, requiring you to spend
  real money.
\item Acquire the fonts' \acro{AFM} files.  \acro{AFM} files contain
  information from the font foundry, about the sizes of the characters
  in the font, and how they fit together.  One measure of the quality
  of a font-supplier is that they provide the \acro{AFM} files by
  default: if the files are not available, you are unlikely to be able
  to use the font with \AllTeX{}.
\item Rename the \acro{AFM} files and the Type~1 files to match the
  \Qref*{Berry font naming scheme}{Q-fontname}.
\item Generate \TeX{} metric files from the \acro{AFM} files.  The
  commonest tool for this task is \Package{fontinst}; the package
  documentation helps, but other guides are available (see below).
  The simplest possible script to pass to \Package{fontinst} is:
  \begin{quote}
\begin{verbatim}
\latinfamily{xyz}{}
\bye
\end{verbatim}
  \end{quote}
  where \texttt{xyz} is the Berry name of the font family.  This
  simple script is adequate for most purposes: its output covers the
  font family in both \acro{T}1 and \acro{OT}1 font encodings.  Nevertheless,
  with fancier fonts, more elaborate things are possible with
  \Package{fontinst}: see its documentation for details.

  \Package{Fontinst} also generates map files, and \LaTeX{} font
  definition (\extension{fd}) files.
\end{itemize}
Having traversed this list, you have a set of font files ready for
installation.
\begin{ctanrefs}
\item[fontinst.sty]\CTANref{fontinst}
\item[\nothtml{\rmfamily}Type 1 installation guide]\CTANref{T1instguide}
\end{ctanrefs}


\Question[Q-instt1font]{Installing a Type~1 font}

Once you have a prepared Type~1 font, either direct from \acro{CTAN}
or the like, or having \Qref*{`prepared' it yourself}{Q-prept1font},
you can get on with installation.

The procedure is merely an extension of that for packages, etc., so
much of what follows will be familiar:
\begin{itemize}
\item Install the files, in your local \texttt{texmf} tree (the advice
  about installing non-standard things applies here, too).  The
  following list gives reasonable destinations for the various files
  related to a font family \meta{fname}:
\begin{narrowversion}
\begin{verbatim}
.pfb,
.pfa  .../fonts/type1/<foundry>/<fname>
.tfm  .../fonts/tfm/<foundry>/<fname>
.vf   .../fonts/vf/<foundry>/<fname>
.sty,
.fd   .../tex/latex/<fname>
.map  .../fonts/map/dvips/<foundry>
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{quote}
\begin{verbatim}
.pfb,
.pfa  .../fonts/type1/<foundry>/<fname>
.tfm  .../fonts/tfm/<foundry>/<fname>
.vf   .../fonts/vf/<foundry>/<fname>
.sty,
.fd   .../tex/latex/<fname>
.map  .../fonts/map/dvips/<foundry>
\end{verbatim}
\end{quote}
\end{wideversion}
  but if you are lucky, you will be starting from a distribution from
  \acro{CTAN} and there is a corresponding \extension{tds.zip} file:
  using this \acro{TDS}-file saves the bother of deciding where to put
  your files in the \acro{TDS} tree.
\item Regenerate the file indexes (as described in
  \Qref[question]{package installation}{Q-inst-wlcf}).
\item Update the \ProgName{dvips}, \PDFTeX{} and other maps:
  \begin{itemize}
  \item On any current \texlive{}-based system, or a te\TeX{} v3.0
    system, execute the command
\begin{quote}
\begin{verbatim}
updmap-sys --enable Map <fname>.map
\end{verbatim}
\end{quote}
    as root.  (If you \emph{can} use \ProgName{updmap-sys}~--- do; if
    not~--- presumably because your \alltex{} system was set up by
    someone else~--- you have to fall back on plain \ProgName{updmap},
    but be aware that it's a potent source of confusion, setting up
    map sets that might be changed behind your back.)
  \item On a current \miktex{} system, update the system file
    \File{updmap.cfg}, using the shell command
\begin{quote}
\begin{verbatim}
initexmf --edit-config-file updmap
\end{verbatim}
\end{quote}
    adding a line at the end:
\begin{quote}
\begin{verbatim}
Map <fname>.map
\end{verbatim}
\end{quote}
    for each font family \meta{fname} you are adding to the system.
    Now generate revised maps with the shell command
\begin{quote}
\begin{verbatim}
initexmf --mkmaps
\end{verbatim}
\end{quote}
    This, and other matters, are described in \miktex{} % beware line break
    \href{http://docs.miktex.org/manual/advanced.html}{``advanced'' documentation}.
  \end{itemize}
\end{itemize}
Both processes (preparing and installing a font) are very well (and
thoroughly) described in Philipp Lehman's guide to font installation,
which may be found on \acro{CTAN}.
\begin{ctanrefs}
\item[fontinst.sty]\CTANref{fontinst}
\item[\nothtml{\rmfamily}Type 1 installation guide]\CTANref{T1instguide}
\end{ctanrefs}

\Question[Q-inst1cm]{Installing the Type~1 versions of the CM~fonts}

This is a specialised case of \Qref*{installing a font}{Q-instfont},
but it is almost never necessary~--- it's inconceivable that any (even
remotely) recent system will \emph{not} have the fonts already
installed.  You can confirm this (near-inevitable) fact by trying the
fonts.  On a system that uses \ProgName{dvips} (almost all do), try
the sequence:
\begin{quote}
\begin{verbatim}
latex sample2e
dvips -o sample2e.ps sample2e
\end{verbatim}
\end{quote}
at a ``command prompt'' (\ProgName{shell}, in a Unix-style system,
``\acro{DOS} box'' in a Windows system).

If the command works at all, the console output of the command will
include a sequence of Type~1 font file names, listed as
\texttt{<\emph{path}/cmr10.pfb>} and so on; this is \ProgName{dvips}
telling you it's copying information from the Type~1 font, and you
need do no more.

If the test has failed, you need to install your own set of the fonts;
the distribution (including all the fonts the \acro{AMS} designed and
produced themselves) is now described as \Package{amsfonts}.  The
bundle contains metric and map files~--- all you need to
\Qref*{install the fonts}{Q-instt1font}.
\begin{ctanrefs}
\item[AMS and CM fonts, in Type 1 format]\CTANref{amsfonts}
\end{ctanrefs}