diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-install.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-install.tex | 1020 |
1 files changed, 0 insertions, 1020 deletions
diff --git a/Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-install.tex b/Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-install.tex deleted file mode 100644 index b65ecb06130..00000000000 --- a/Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-install.tex +++ /dev/null @@ -1,1020 +0,0 @@ -% $Id: faq-install.tex,v 1.16 2012/02/08 21:59:32 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 te\TeX{} or \texlive{}-based system, 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 te\TeX{} or \texlive{}, 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 the -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}. - -There are circumstances when 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, you should replace the existing copy in the - \acro{TEXMF} tree. -\end{itemize} -The reason one would put things on a local tree is to avoid their -disappearance if the system is upgraded (or otherwise re-installed). - -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 will 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} - - |