Project:TeX/Tex Live Migration Guide

This guide aims to show you how to install TeX Live 2008 on Gentoo, more specifically what you need to take care of if you already have a TeX distribution installed (like tetex or TeX Live 2005).

Introduction
In this section we will assume that you have  installed. This also applies if you had  installed. In a perfect world it would be as simple as unmerging it, but unfortunately it is not.

Saving your old configuration
If you have modified your configuration of  editing the files in , you should save them first:

Removing tetex
Now you can safely unmerge  :

Some weird errors have been reported when stray configuration files were left behind in. For safety and for a clean install of  it is recommended to remove the  file:

Due to  using   outside of the scope of the package manager, simply unmerging it will have left behind some stray symlinks:

Of course, pdfetex has gone with  's removal, so the pdftex symlink is dead and can be safely removed. The  command (with a GNU extension though) can help us find and remove dead symlinks interactively:

These were the files left over by my  installation.

was also using outside of the scope of the package manager to generate the format files. With we now build most of the format files while compiling the packages; which format files will be installed in. That means you have to make sure that there are no stray format files:

Installing TeX Live 2008
If you have passed through all the above steps, installing  now should be very easy.

In theory this should just go smoothly and install everything. You might want to tune  USE flags to install extra TeX packages, but you can do it later;   is just a meta-ebuild that pulls the real packages depending on its USE flags.

Nevertheless, it is possible to get dependency problems, errors while installing a package, etc. In that case, you are advised to file a bug on https://bugs.gentoo.org. If you file a bug, please include at least the output of  (run as the same user that failed to install, because some environment variables might be important) in addition to the error; this output will most often be requested.

Introduction
As was the case for ,   on   has its three main configuration files separated and handled by. These files are, namely,,  ,. They lie in ; you should not modify them directly because the changes will be lost the next time   is run.

texmf.cnf
The file is the main TeX installation configuration file. It contains variable definitions that will be used by a lot of programs.

The file is the result of concatenating files in. In order to modify your TeX environment configuration, you should modify the files there. At the time of writing,  's ebuild install six files there:

This is the result of the splitting in their respective sections of a (lightly) modified file from   DVD.

The,  ,  and  files should not be modified. If the defaults can be improved, please file a bug.

The and  files can be modified with caution. The comments in these files should explain what options mean. For example, in you can increase TeX memory, in case you are trying to compile a document that is too big and runs into   errors.

If you wish to append additions to the file, you can also create a new file in , called for example. Beware not to give it a higher priority than the core configuration files, so it should begin with a two digit number greater than.

Packages that need to append something to the file get the same treatment, they should install a  file instead:

updmap.cfg
The file is the configuration file used by   (and   ), unless otherwise specified. It tells it which font maps to update for the various TeX output drivers.

The file in  is the result of concatenating the files in. The initial file installed by   is the result of running   on the the installed   tree (in fact, it just mimics what   would do, but it is only a technical detail).

Various  ebuilds will add files to the  directory when they install fonts. While you can edit those files to disable some font maps to be updated, it would probably be wiser to remove the relevant package.

If a third party package wants to add font maps, it should install a file in and let   handle it.

A better way of handling this would be to create a file to be installed in and install it for TeX distributions that support the   way:

The files in should respect   syntax:

fmtutil.cnf
The file contains information on how to build and handle a format file.

The file is the result of concatenating the files in. Various  ebuilds install files there. Those files come with the formats they add support for and the symlink to the relevant engine.

ebuilds that install a file, install the relevant format files in  and create the symlink from the format to the engine.

Note that when a support file for a language gets added,  takes care of adding it to the  file and regenerates the format files to support the newly installed language.

Updating your configuration
Now that you know how  configuration is managed, you should be able to port the changes you had made to your older TeX distribution configuration to the   configuration layout.

Introduction
In this chapter we will try to give a short summary of the most common errors and explain what has gone wrong.

Format was written by (pdf)etex
Sometimes when installing some packages that requires latex, you'll get this error:

This is due to old files remaining from an old installation of a  distribution based on. This most likely means you did not follow entirely this guide, especially the.

Nevertheless, it is still possible to fix it quickly without having to reinstall anything, just run as root:

Format directory does not exist
When installing e.g., , you might encounter the error:

This is most likely due to a wrong configuration. Try to run the following command and get the same results:

This is very important, since  looks for   at this location; if you have a different result then   will not find   and thus will fail to create the directory where to temporarily store the compiled formats.

There is no magic command to fix this one, you should check that your configuration is correct, that there are no stray configuration files in. This will most likely be due to an old being still there and thus setting wrong definitions for the  file. Please refer to the and remember that when you modify or remove a file in  you need to run   to have the changes taken into account.

Missing .tex files
When installing  (or any other format that has babel hyphenation support), you might encounter an error like:

{{CodeBox|title=missing bghyphen.tex|

=
============================== Local configuration file hyphen.cfg used

=
==============================

(/var/tmp/portage/dev-texlive/texlive-latex-2008/work/texmf-dist/tex/generic/ba bel/hyphen.cfg (/usr/share/texmf/tex/generic/hyphen/hyphen.tex) (/usr/share/texmf/tex/generic/hyphen/ushyphmax.tex) (/usr/share/texmf/tex/generic/hyphen/dumyhyph.tex) (/usr/share/texmf/tex/generic/hyphen/zerohyph.tex) (/usr/share/texmf/tex/generic/hyphen/zerohyph.tex) (/usr/share/texmf-dist/tex/generic/xu-hyphen/xu-bahyph.tex (/usr/share/texmf/tex/generic/hyphen/bahyph.tex)) (/usr/share/texmf-dist/tex/generic/xu-hyphen/xu-bghyphen.tex ! I can't find file `bghyphen.tex'. l.10  \input bghyphen.tex

Please type another input file name: ! Emergency stop. l.10  \input bghyphen.tex

No pages of output. Transcript written on latex.log. Error: `pdftex -ini -jobname=latex -progname=latex -translate-file=cp227.tcx *latex.ini' failed }}

In that case, you will have to check which file is being used:

This file is automatically generated by  and is the result of concatenating  files present in the directory with  (for TeX Live 2008, the  files are taken from  ). This directory should be. So you should check that there are no other files in that directory other than the ones installed by the various   ebuilds. A file present in that directory means that you want to enable hyphenation support for a specific language; if you don't have the hyphenation support files the formats that use this extra hyphenation support will fail to build.

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide:


 * Alexis Ballier