Attachment 135180 Details for Bug 198068 – update before I forget

update before I forget

migrationhowto.xml (text/plain), 15.88 KB, created by Alexis Ballier on 2007-11-04 18:35:10 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Alexis Ballier

Created: 2007-11-04 18:35:10 UTC

Size: 15.88 KB

patch

obsolete

><?xml version="1.0" encoding="UTF-8"?>
><!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
>
>
><guide lang="en">
><title>TeX Live 2007 guide</title>
>
><author title="Author">
>  <mail link="aballier@gentoo.org">Alexis Ballier</mail>
></author>
>
><abstract>
>This guide aims to show you how to install TeX Live 2007 on Gentoo, more specifically
>what you need to take care of if you already had a TeX distribution installed
>(like tetex or TeX Live 2005).
></abstract>
>
>
>
><license/>
>
><version>1.0</version>
><date>2007-10-27</date>
>
><chapter id="uninstall">
><title> Clean uninstall </title>
>
><section>
><title>Introduction</title>
><body>
><p>
>In this section we will assume that you have <c> >=app-text/tetex-3 </c>
>installed. This applies as well if you had installed <c>app-text/texlive-2005</c>.
>In a perfect world it would be as simple as unmerging it, but unfortunately it is not.
></p>
></body>
></section>
>
><section>
><title>Saving your old configuration</title>
><body>
><p>
>If you had modified your configuration of <c>tetex</c> by editing files in
><path>/etc/texmf</path>,
>you should first save them:
></p>
><pre caption="Save your old configuration files">
>$ <i>cp -rf /etc/texmf /tmp/tetex-texmf</i>
></pre>
></body>
></section>
><section>
><title>Removing tetex</title>
><body>
><p>
>Then you can unmerge safely <c>tetex</c>:
></p>
><pre caption="Remove tetex">
># <i>emerge -C tetex</i>
></pre>
>
><p>
>Some weird errors have been reported when there were stray configuration files left
>in <path>/etc/texmf</path>. For safety and a clean install of <c>TeX Live</c> it is
>recommended to remove the <path>/etc/texmf/texmf.d/00texmf.cnf</path> file:
></p>
><pre caption="Cleanup /etc/texmf">
># <i>rm /etc/texmf/texmf.d/00texmf.cnf</i>
></pre>
><note> 
>You have not lost anything since you just saved your old configuration files.
></note>
>
>
><p>
>Due to <c>tetex</c> using <c>texlinks</c> outside of the scope of the package
>manager, simply unmerging it will have left some stray symlinks:
></p>
><pre caption="tetex stray symlink">
>$ <i>ls -l /usr/bin/pdftex</i>
>lrwxrwxrwx 1 root root 7 2007-07-09 07:34 /usr/bin/pdftex -> pdfetex
></pre>
><p>
>Of course, pdfetex has gone with <c>tetex</c>'s removal, so the pdftex symlink
>is a dead one. It can be safely removed.
>The <c>find</c> command can help finding dead symlinks (with a GNU extension
>though):
></p>
><pre caption="Find dead symlinks">
>$ <i>find /usr/bin -name "*" -type l ! -xtype f ! -xtype d</i>
>
>/usr/bin/lamed
>/usr/bin/latex
>/usr/bin/amstex
>/usr/bin/elatex
>/usr/bin/eplain
>/usr/bin/lambda
>/usr/bin/pdftex
>/usr/bin/pdflatex
>/usr/bin/pdfamstex
></pre>
><p>
>These are the files left over by my <c>tetex</c> installation.
></p>
>
><p>
><c>tetex</c> was also using <c>fmtutil</c> outside of the scope of the package
>manager to generate the format files. With <c>TeX Live 2007</c> we are now
>building most of the format files while compiling the packages; which format
>files will be installed in <path>/var/lib/texmf</path>. That means you have to make
>sure that there are no stray format files:
></p>
><pre caption="Remove stray format files">
># <i>rm -rf /var/lib/texmf/web2c</i>
></pre>
>
></body>
></section>
></chapter>
><chapter>
><title> Installing TeX Live 2007 </title>
><section>
><body>
>
><p>
>If you have passed through all the above steps, now installing <c>TeX Live 
>2007</c> should be very easy.
></p>
><pre caption="Install TeX Live 2007">
># <i>emerge texlive</i>
></pre>
>
><p>
>In theory this should just go smoothly and install everything. You might want at
>some point to tune <c>app-text/texlive</c> use flags to install extra TeX
>packages, but you can do it later; <c>app-text/texlive</c> is just a meta-ebuild
>that pulls the real packages depending on its use flags.
></p>
>
><p>
>Nevertheless, it is possible that you get dependencies problems, errors while
>installing a package, etc. In that case, you are advised to file a bug on 
><uri>https://bugs.gentoo.org</uri>. If you do file a bug, please include at
>least the output of <c>texconfig conf</c> in addition to the error; this output
>will most often be requested.
></p>
></body>
></section>
></chapter>
>
><chapter>
><title> Configuration </title>
>
><section>
><title>Introduction</title>
><body>
><p>
>As it was the case for <c>tetex-3</c>, <c>TeX Live</c> on <c>Gentoo</c> has its
>three main configuration files splitted and handled by <c>texmf-update</c>.
>These files are, namely, <path>texmf.cnf</path>, <path>fmtutil.cnf</path>,
><path>updmap.cfg</path>. They lie in <path>/etc/texmf/web2c</path>; you should
>not modify them directly because the changes will be lost the next time
><c>texmf-update</c> is ran.
></p>
></body>
></section>
>
><section>
><title> texmf.cnf </title>
><body>
><p>
>The <path>texmf.cnf</path> configuration file is the main configuration file for your
>TeX installation, it contains various variable definitions that will be used by
>a lot of programs.
></p>
><p>
>The <path>texmf.cnf</path> file is the result of the concatenation of the files in
><path>/etc/texmf/texmf.d</path>. In order to modify your TeX environment
>configuration, you should modify the files there. At the time of writing,
><c>Gentoo TeX Live</c>'s ebuild install six files there:
></p>
><pre caption="texmf.d installed files">
>00header.cnf
>05searchpaths.cnf
>10standardpaths.cnf
>15options.cnf
>20sizes.cnf
>25misc.cnf
></pre>
><p>
>This is the result of the splitting in their respective sections of a (lightly)
>modified <path>texmf.cnf</path> file from <c>TeX Live 2007</c> DVD.
></p>
>
><p>
>The files <path>00header.cnf</path>, <path>05searchpaths.cnf</path>,
><path>10standardpaths.cnf</path> and <path>25misc.cnf</path> should not be
>modified and kept as is. If the defaults can be improved, please file a bug.
></p>
><warn>
>The <c>TeX Live</c> ebuilds are not aware of paths changes of those files,
>so if you change any path there, make sure you know what you are doing.
></warn>
>
><p>
>The files <path>15options.cnf</path> and <path>20sizes.cnf</path> can be
>modified with caution. The comments in these files should be explicit of what
>option means what. For example, in <path>20sizes.cnf</path> you can increase TeX
>memory, in case you are trying to compile a too big document and run into <c>TeX
>capacity exceeded, sorry</c> errors.
></p>
>
><p>
>If you wish to append some additions to the <path>texmf.cnf</path> file, you can also
>create a new file in <path>/etc/texmf/texmf.d</path>, called for example
><path>99myadditions.cnf</path>. Beware though to not give it a higher priority than
>the core configuration files, so it should begin with a two digits number greater than
><c>25</c>.
></p>
>
><p>
>Packages that need to append something to the <path>texmf.cnf</path> file get the same
>treatment, they should install a <path>texmf.d</path> file instead:
></p>
><pre caption="Sample code for installing a texmf.d file">
><keyword>insinto</keyword> <const>/etc/texmf/texmf.d</const>
><keyword>doins</keyword> <const>40mytexmfadditions.cnf</const>
></pre>
></body>
></section>
>
><section>
><title>updmap.cfg</title>
><body>
><p>
>The <path>updmap.cfg</path> is the configuration file used by <c>updmap</c>
>(and <c>updmap-sys</c>), unless otherwise specified. It tells it which font maps
>to update for the various TeX output drivers.
></p>
><p>
>The <path>updmap.cfg</path> file in <path>/etc/texmf/web2c</path> is the result of
>the concatenation of the files in <path>/etc/texmf/updmap.d</path>.
>The initial <path>00updmap.cfg</path> file installed by <c>app-text/texlive-core</c> is
>the result of <c>updmap --syncwithtrees</c> ran on the <c>texmf</c> tree that it
>installs (in fact, it just mimics what <c>updmap --syncwithtrees</c> would do,
>but it is only a technical detail).
></p>
>
><p>
>Various <c>TeX Live</c> ebuilds will add files to the
><path>/etc/texmf/updmap.d</path> 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.
></p>
>
><p>
>If a third party package wants to add some font maps, it should install a file
>in <path>/etc/texmf/updmap.d</path> and let <c>texmf-update</c> handle it.
></p>
><warn>
>Sometimes you can see <c>updmap-sys --enable Map=mymap.map</c> in some ebuilds
>or some installation instructions of a third party font package, while this
>might work at a first try, the changes will be reverted the next time
><c>texmf-update</c> is ran.
></warn>
><p>
>The good way of handling it would be to create a file to be installed in
><path>/etc/texmf/updmap.d</path> and install it for TeX distributions that support the
><c>texmf-update</c> way:
></p>
><pre caption="How to enable a font map">
><keyword>inherit</keyword> <ident>latex-package</ident>
>...
><stmt>src_install()</stmt> {
>    ...
>    <keyword>if</keyword> <stmt>latex-package_has_tetex_3</stmt>; then
>        <keyword>insinto</keyword> /etc/texmf/updmap.d
>        <keyword>doins</keyword> myfontmapconfig.cfg
>    <keyword>fi</keyword>
>    ...
>}
>...
><stmt>pkg_postinst()</stmt> {
>    <stmt>latex-package_pkg_postinst</stmt>
>    <stmt>latex-package_has_tetex_3</stmt> || updmap-sys --enable Map=mymap.map
>}
>
><stmt>pkg_postrm()</stmt> {
>    <stmt>latex-package_pkg_postinst</stmt>
>    <stmt>latex-package_has_tetex_3</stmt> || updmap-sys --disable Map=mymap.map
>}
></pre>
><p>
>The files in <path>/etc/texmf/updmap.d</path> should respect <c>updmap</c> syntax:
></p>
><pre caption="Snippet of updmap.cfg explaining the 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 #.
></pre>
></body>
></section>
><section>
><title>fmtutil.cnf</title>
><body>
><p>
>The <path>fmtutil.cnf</path> file contains the information on how to build a format
>file and how to handle it.
></p>
>
><p>
>The <path>fmtutil.cnf</path> file is the result of the concatenation of the files in 
><path>/etc/texmf/fmtutil.d</path>. Various <c>TeX Live</c> ebuilds install files
>there, those files come with the formats they add support for and the symlink to
>the relevant engine.
></p>
>
><pre caption="Snippet of the fmtutil.cnf(5) man page that explains the syntax">
>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.
></pre>
><p>
><c>TeX Live</c> ebuilds that install a <path>fmtutil.d</path> file install the relevant
>format files in <path>/var/lib/texmf/web2c</path> and create the symlink from the format to
>the engine.
></p>
><p>
>It should be noted that when a support file for a language gets added,
><c>texmf-update</c> takes care of adding it to the <path>language.dat</path> file and
>regenerates the format files so that they support the newly installed language.
></p>
></body>
></section>
><section>
><title> Updating your configuration </title>
><body>
><p>
>Now that you know how does <c>TeX Live</c> configuration is managed, you should
>be able to port the changes you had made to your older TeX distribution
>configuration to the <c>TeX Live</c> configuration layout.
></p>
></body>
></section>
>
></chapter>
>
><chapter>
><title> Common errors </title>
>
><section>
><title>Introduction</title>
><body>
><p>
>In this chapter we will try to give a short summary of the most common errors
>and explain what has gone wrong.
></p>
></body>
></section>
>
><section>
><title>Format was written by (pdf)etex</title>
><body>
>
><p>
>Sometimes when installing some packages that requires latex, you'll get this
>error:
></p>
><pre caption="Format was written by pdfetex">
>---! //var/lib/texmf/web2c/latex.fmt was written by pdfetex
></pre>
><p>
>This is due to old files remaining from an old installation of a <c>TeX</c>
>distribution based on <c>etex</c>. That most likely means you did not follow
>entirely this guide, especially the <uri link="#uninstall">Clean uninstall
>chapter </uri>.
></p>
>
><p>
>Nevertheless, it is still possible to fix it quickly without having to reinstall
>anything, just run as root:
></p>
><pre caption="Remove old formats">
># <i>rm -rf /var/lib/texmf/web2c</i>
># <i>texmf-update</i>
></pre>
></body>
></section>
>
><section>
><title>Format directory does not exist</title>
><body>
>
><p>
>When installing e.g., <c>texlive-latex</c>, you might encounter the error:
></p>
><pre caption="Format directory does not exist">
>fmtutil: format directory
>`/var/tmp/portage/dev-texlive/texlive-latex-2007/work/texmf-var/web2c' does not
>exist.
></pre>
>
><p>
>This is most likely to be due to a wrong configuration. You should try to run
>the following command and get the same results:
></p>
><pre caption="TEXMFMAIN definition">
>$ <i>kpsewhich --var-value=TEXMFMAIN</i>
>/usr/share/texmf
></pre>
><p>
>This is very important, since <c>fmtutil</c> looks for <c>mktexdir</c> at this
>location; if you have a different result then <c>fmtutil</c> will not find
><c>mktexdir</c> and thus will fail to create the directory where to temporarily
>store the compiled formats.
></p>
>
><p>
>There is no magic command to fix this one, you should check that your
>configuration is correct, that there is no stray configuration file in
><path>/etc/texmf/texmf.d</path>. This will most likely be due to
><path>00texmf.cnf</path> being still there and thus setting wrong definitions
>for the <path>texmf.cnf</path> file. Please refer to the <uri
>link="#uninstall">Clean uninstall chapter </uri>.
></p>
></body>
></section>
>
><section>
><title>Missing .tex files</title>
><body>
><p>
>When installing <c>texlive-latex</c> (or any other format that has babel
>hyphenation support), you might encounter an error like:
></p>
><pre caption="missing bghyphen.tex">
>===========================================
>Local configuration file hyphen.cfg used
>===========================================
>
>(/var/tmp/portage/dev-texlive/texlive-latex-2007/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
></pre>
><p>
>In that case, you will have to check which <path>language.dat</path> file is being
>used:
></p>
><pre caption="find language.dat">
>$ <i>kpsewhich language.dat</i>
>/usr/share/texmf/tex/generic/config/language.dat
></pre>
><p>
>This file is automatically generated by <c>texmf-update</c>, it is the result of
>the concatenation of <path>language.*.dat</path> files present in the directory where
>is <path>language.us</path>. This directory should be
><path>/usr/share/texmf/tex/generic/config/</path>. So you should check that there are
>no other <path>language.*.dat</path> files in that directory than the ones installed
>by the various <c>dev-texlive/texlive-lang*</c> ebuilds. A file present in that
>directory means that you want to enable hyphenation support for a specific
>language; and if you don't have the hyphenation support files this will cause
>formats that can use this extra hyphenation support to fail to build.
></p>
></body>
></section>
></chapter>
></guide>

Actions: View

Attachments on bug 198068: 135158 | 135180