summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/faq-install.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/FAQ-en/faq-install.tex')
-rw-r--r--Master/texmf-dist/doc/generic/FAQ-en/faq-install.tex1021
1 files changed, 0 insertions, 1021 deletions
diff --git a/Master/texmf-dist/doc/generic/FAQ-en/faq-install.tex b/Master/texmf-dist/doc/generic/FAQ-en/faq-install.tex
deleted file mode 100644
index 7c01b80fcf1..00000000000
--- a/Master/texmf-dist/doc/generic/FAQ-en/faq-install.tex
+++ /dev/null
@@ -1,1021 +0,0 @@
-% $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}
-
-