Attachment 135158 Details for Bug 198068 – guidexml file

guidexml file

migrationhowto.xml (text/plain), 15.97 KB, created by Alexis Ballier on 2007-11-04 16:11:58 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Alexis Ballier

Created: 2007-11-04 16:11:58 UTC

Size: 15.97 KB

patch

obsolete

><?xml version="1.0" encoding="UTF-8"?>
><!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
>
>
><guide link="/doc/en/guide.xml" 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 <c>/etc/texmf</c>,
>you should first save them:
></p>
><pre caption="Save your old configuration files">
>$ <keyword>cp -rf</keyword> <const>/etc/texmf</const> <ident>/tmp/tetex-texmf</ident>
></pre>
></body>
></section>
><section>
><title>Removing tetex</title>
><body>
><p>
>Then you can unmerge safely <c>tetex</c>:
></p>
><pre caption="Remove tetex">
># <keyword>emerge</keyword> <ident>-C</ident> <const>tetex</const>
></pre>
>
><p>
>Some weird errors have been reported when there were stray configuration files left
>in <c>/etc/texmf</c>. For safety and a clean install of <c>TeX Live</c> it is
>recommended to remove the <c>/etc/texmf/texmf.d/00texmf.cnf</c> file:
></p>
><pre caption="Cleanup /etc/texmf">
># <keyword>rm</keyword> <const>/etc/texmf/texmf.d/00texmf.cnf</const>
></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">
>$ <keyword>ls -l</keyword> <const>/usr/bin/pdftex</const>
>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">
>$ <keyword>find</keyword> <const>/usr/bin</const> -name "*" -type l ! -xtype f ! -xtype d
>
>/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 <c>/var/lib/texmf</c>. That means you have to make
>sure that there are no stray format files:
></p>
><pre caption="Remove stray format files">
># <keyword>rm -rf</keyword> <const>/var/lib/texmf/web2c</const>
></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">
># <keyword>emerge</keyword> <const>texlive</const>
></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, <c>texmf.cnf</c>, <c>fmtutil.cnf</c>, <c>updmap.cfg</c>.
>They lie in <c>/etc/texmf/web2c</c>; 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 <c>texmf.cnf</c> 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 <c>texmf.cnf</c> file is the result of the concatenation of the files in
><c>/etc/texmf/texmf.d</c>. 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 <c>texmf.cnf</c> file from <c>TeX Live 2007</c> DVD.
></p>
>
><p>
>The files <c>00header.cnf</c>, <c>05searchpaths.cnf</c>,
><c>10standardpaths.cnf</c> and <c>25misc.cnf</c> 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 <c>15options.cnf</c> and <c>20sizes.cnf</c> can be modified with
>caution. The comments in these files should be explicit of what option means
>what. For example, in <c>20sizes.cnf</c> 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 <c>texmf.cnf</c> file, you can also
>create a new file in <c>/etc/texmf/texmf.d</c>, called for example
><c>99myadditions.cnf</c>. 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 <c>texmf.cnf</c> file get the same
>treatment, they should install a <c>texmf.d</c> 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 <c>updmap.cfg</c> 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 <c>updmap.cfg</c> file in <c>/etc/texmf/web2c</c> is the result of
>the concatenation of the files in <c>/etc/texmf/updmap.d</c>.
>The initial <c>00updmap.cfg</c> 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 <c>/etc/texmf/updmap.d</c>
>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 <c>/etc/texmf/updmap.d</c> 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
><c>/etc/texmf/updmap.d</c> 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 <c>/etc/texmf/updmap.d</c> 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 <c>fmtutil.cnf</c> file contains the information on how to build a format
>file and how to handle it.
></p>
>
><p>
>The <c>fmtutil.cnf</c> file is the result of the concatenation of the files in 
><c>/etc/texmf/fmtutil.d</c>. 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 <c>fmtutil.d</c> file install the relevant
>format files in <c>/var/lib/texmf/web2c</c> 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 <c>language.dat</c> 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">
># <keyword>rm -rf</keyword> <const>/var/lib/texmf/web2c</const>
># <keyword>texmf-update</keyword>
></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">
>$ <keyword>kpsewhich</keyword> <ident>--var-value=</ident><var>TEXMFMAIN</var>
><const>/usr/share/texmf</const>
></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
><c>/etc/texmf/texmf.d</c>. This will most likely be due to <c>00texmf.cnf</c>
>being still there and thus setting wrong definitions for the <c>texmf.cnf</c>
>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 <c>language.dat</c> file is being
>used:
></p>
><pre caption="find language.dat">
>$ <keyword>kpsewhich</keyword> <ident>language.dat</ident>
><const>/usr/share/texmf/tex/generic/config/language.dat</const>
></pre>
><p>
>This file is automatically generated by <c>texmf-update</c>, it is the result of
>the concatenation of <c>language.*.dat</c> files present in the directory where
>is <c>language.us</c>. This directory should be
><c>/usr/share/texmf/tex/generic/config/</c>. So you should check that there are
>no other <c>language.*.dat</c> 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