summaryrefslogtreecommitdiff
path: root/obsolete/help/texfaq/faq-install.tex
diff options
context:
space:
mode:
Diffstat (limited to 'obsolete/help/texfaq/faq-install.tex')
-rw-r--r--obsolete/help/texfaq/faq-install.tex1021
1 files changed, 1021 insertions, 0 deletions
diff --git a/obsolete/help/texfaq/faq-install.tex b/obsolete/help/texfaq/faq-install.tex
new file mode 100644
index 0000000000..7c01b80fcf
--- /dev/null
+++ b/obsolete/help/texfaq/faq-install.tex
@@ -0,0 +1,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}
+
+