TeX Live 2008 guide

1.  Clean uninstall

Introduction

In this section we will assume that you have >=app-text/tetex-3 installed. This also applies if you had app-text/texlive-2005 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 tetex editing the files in /etc/texmf, you should save them first:

$ cp -rf /etc/texmf ~/tetex-texmf

Removing tetex

Now you can safely unmerge tetex:

# emerge -C tetex

Some weird errors have been reported when stray configuration files were left behind in /etc/texmf. For safety and for a clean install of TeX Live it is recommended to remove the /etc/texmf/texmf.d/00texmf.cnf file:

# rm /etc/texmf/texmf.d/00texmf.cnf

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

$ ls -l /usr/bin/pdftex
lrwxrwxrwx 1 root root 7 2007-07-09 07:34 /usr/bin/pdftex -> pdfetex

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

# find /usr/bin -type l ! -xtype f ! -xtype d -ok rm -f {} \;

< rm ... /usr/bin/pdflatex > ? y
< rm ... /usr/bin/amstex > ? y
< rm ... /usr/bin/pdftex > ? y
< rm ... /usr/bin/eplain > ? y
< rm ... /usr/bin/jadetex > ? y
< rm ... /usr/bin/lambda > ? y
< rm ... /usr/bin/pdfamstex > ? y
< rm ... /usr/bin/elatex > ? y
< rm ... /usr/bin/lamed > ? y
< rm ... /usr/bin/pdfjadetex > ? y
< rm ... /usr/bin/latex > ? y

These were the files left over by my tetex installation.

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

# rm -rf /var/lib/texmf/web2c

2.  Installing TeX Live 2008

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

# emerge texlive

In theory this should just go smoothly and install everything. You might want to tune app-text/texlive USE flags to install extra TeX packages, but you can do it later; app-text/texlive 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 texconfig conf (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.

3.  Configuration

Introduction

As was the case for tetex-3, TeX Live on Gentoo has its three main configuration files separated and handled by texmf-update. These files are, namely, texmf.cnf, fmtutil.cnf, updmap.cfg. They lie in /etc/texmf/web2c; you should not modify them directly because the changes will be lost the next time texmf-update is run.

texmf.cnf

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

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

00header.cnf
05searchpaths.cnf
10standardpaths.cnf
15options.cnf
20sizes.cnf
25misc.cnf

This is the result of the splitting in their respective sections of a (lightly) modified texmf.cnf file from TeX Live 2008 DVD.

The 00header.cnf, 05searchpaths.cnf, 10standardpaths.cnf and 25misc.cnf files should not be modified. If the defaults can be improved, please file a bug.

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

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

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

insinto /etc/texmf/texmf.d
doins 40mytexmfadditions.cnf

updmap.cfg

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

The updmap.cfg file in /etc/texmf/web2c is the result of concatenating the files in /etc/texmf/updmap.d. The initial 00updmap.cfg file installed by app-text/texlive-core is the result of running updmap --syncwithtrees on the the installed texmf tree (in fact, it just mimics what updmap --syncwithtrees would do, but it is only a technical detail).

Various TeX Live ebuilds will add files to the /etc/texmf/updmap.d 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 /etc/texmf/updmap.d and let texmf-update handle it.

A better way of handling this would be to create a file to be installed in /etc/texmf/updmap.d and install it for TeX distributions that support the texmf-update way:

inherit latex-package
...
src_install() {
    ...
    if latex-package_has_tetex_3; then
        insinto /etc/texmf/updmap.d
        doins myfontmapconfig.cfg
    fi
    ...
}
...
pkg_postinst() {
    latex-package_pkg_postinst
    latex-package_has_tetex_3 || updmap-sys --enable Map=mymap.map
}

pkg_postrm() {
    latex-package_pkg_postinst
    latex-package_has_tetex_3 || updmap-sys --disable Map=mymap.map
}

The files in /etc/texmf/updmap.d should respect updmap syntax:

There are two possible entries: Map and MixedMap. Both have one additional
argument: the file name of the map file. MixedMap ("mixed" means that the font
is available as bitmap and as outline) lines will not be used in the default map
of dvips if dvipsPreferOutline is false. Inactive Map files should be marked by
"#! " (without the quotes), not just #.

fmtutil.cnf

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

The fmtutil.cnf file is the result of concatenating the files in /etc/texmf/fmtutil.d. Various TeX Live ebuilds install files there. Those files come with the formats they add support for and the symlink to the relevant engine.

The fmtutil.cnf file contains the configuration information for fmtutil(8).
Each line contains the name of the format (e.g., "tex", "latex", "omega"), the
name of the engine that is used by that format (e.g., "tex", "etex", "omega"),
the pattern file (e.g., language.dat, language.def), and any arguments (name of
an .ini file).

Fields are separated by whitespace and complete lines can be commented out with
"#".  The "pattern file" field cannot be used to define a file that is used
while building the format. It tells fmtutil which file the format creation
procedure reads and it has an effect to the options --showhyphen and --byhyphen.
If the format has no way to customize hyphenation, a "-" can be used to indicate
this.

TeX Live ebuilds that install a fmtutil.d file, install the relevant format files in /var/lib/texmf/web2c and create the symlink from the format to the engine.

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

Updating your configuration

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

4.  Common errors

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:

---! //var/lib/texmf/web2c/latex.fmt was written by pdfetex

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

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

# rm -rf /var/lib/texmf/web2c
# texmf-update

Format directory does not exist

When installing e.g., texlive-latex, you might encounter the error:

fmtutil: format directory
`/var/tmp/portage/dev-texlive/texlive-latex-2008/work/texmf-var/web2c' does not
exist.

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

$ kpsewhich --var-value=TEXMFMAIN
/usr/share/texmf

This is very important, since fmtutil looks for mktexdir at this location; if you have a different result then fmtutil will not find mktexdir 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 /etc/texmf/texmf.d. This will most likely be due to an old 00texmf.cnf being still there and thus setting wrong definitions for the texmf.cnf file. Please refer to the Clean uninstall chapter and remember that when you modify or remove a file in /etc/texmf/*.d you need to run texmf-update to have the changes taken into account.

Missing .tex files

When installing texlive-latex (or any other format that has babel hyphenation support), you might encounter an error like:

===========================================
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 language.dat file is being used:

$ kpsewhich language.dat
/usr/share/texmf/tex/generic/config/language.dat

This file is automatically generated by texmf-update and is the result of concatenating language.*.dat files present in the directory with language.us (for TeX Live 2008, the language.*.dat files are taken from /etc/texmf/language.dat.d/). This directory should be /usr/share/texmf/tex/generic/config/. So you should check that there are no other language.*.dat files in that directory other than the ones installed by the various dev-texlive/texlive-lang* 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.

The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.