Gentoo Archives: gentoo-commits

From: "Alexis Ballier (aballier)" <aballier@g.o>
To: gentoo-commits@l.g.o
Subject: [gentoo-commits] gentoo commit in xml/htdocs/proj/en/tex: index.xml texlive-migration-guide.xml
Date: Fri, 21 Dec 2007 00:10:39
Message-Id: E1J5VTC-0002I6-6U@stork.gentoo.org
1 aballier 07/12/21 00:10:30
2
3 Added: index.xml texlive-migration-guide.xml
4 Log:
5 Add tex project, and the texlive migration guide, bug #198068
6
7 Revision Changes Path
8 1.1 xml/htdocs/proj/en/tex/index.xml
9
10 file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/tex/index.xml?rev=1.1&view=markup
11 plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/tex/index.xml?rev=1.1&content-type=text/plain
12
13 Index: index.xml
14 ===================================================================
15 <?xml version="1.0" encoding="UTF-8"?>
16 <?xml-stylesheet href="/xsl/project.xsl" type="text/xsl"?>
17 <?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
18 <!DOCTYPE project SYSTEM "/dtd/project.dtd">
19 <project>
20
21 <name>TeX</name>
22
23 <author title="Author">
24 <mail link="aballier@g.o">Alexis Ballier</mail>
25 </author>
26
27 <description>
28 The TeX project maintains ebuilds for TeX distributions and TeX related
29 packages.
30 </description>
31
32 <longdescription>
33 <p>
34 The TeX project maintains ebuilds for TeX distributions and TeX related
35 packages. This includes app-text/texlive, app-text/tetex, the dev-texlive
36 category, most of dev-tex and a few others.
37 </p>
38 </longdescription>
39
40 <herd name="tex" />
41
42 <dev role="Member">aballier</dev>
43
44 <resource link="texlive-migration-guide.xml">
45 How to migrate from teTex or TeX Live 2005 to TeX Live 2007.
46 </resource>
47 </project>
48
49
50
51 1.1 xml/htdocs/proj/en/tex/texlive-migration-guide.xml
52
53 file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/tex/texlive-migration-guide.xml?rev=1.1&view=markup
54 plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/tex/texlive-migration-guide.xml?rev=1.1&content-type=text/plain
55
56 Index: texlive-migration-guide.xml
57 ===================================================================
58 <?xml version="1.0" encoding="UTF-8"?>
59 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
60 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/tex/texlive-migration-guide.xml,v 1.1 2007/12/21 00:10:29 aballier Exp $ -->
61
62 <guide lang="en">
63 <title>TeX Live 2007 guide</title>
64
65 <author title="Author">
66 <mail link="aballier@g.o">Alexis Ballier</mail>
67 </author>
68
69 <abstract>
70 This guide aims to show you how to install TeX Live 2007 on Gentoo, more specifically
71 what you need to take care of if you already had a TeX distribution installed
72 (like tetex or TeX Live 2005).
73 </abstract>
74
75 <!-- The content of this document is licensed under the CC-BY-SA license -->
76 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
77 <license/>
78
79 <version>1.0</version>
80 <date>2007-12-20</date>
81
82 <chapter id="uninstall">
83 <title> Clean uninstall </title>
84
85 <section>
86 <title>Introduction</title>
87 <body>
88 <p>
89 In this section we will assume that you have <c> >=app-text/tetex-3 </c>
90 installed. This applies as well if you had installed <c>app-text/texlive-2005</c>.
91 In a perfect world it would be as simple as unmerging it, but unfortunately it is not.
92 </p>
93 </body>
94 </section>
95
96 <section>
97 <title>Saving your old configuration</title>
98 <body>
99 <p>
100 If you had modified your configuration of <c>tetex</c> by editing files in
101 <path>/etc/texmf</path>,
102 you should first save them:
103 </p>
104 <pre caption="Save your old configuration files">
105 $ <i>cp -rf /etc/texmf /tmp/tetex-texmf</i>
106 </pre>
107 </body>
108 </section>
109 <section>
110 <title>Removing tetex</title>
111 <body>
112 <p>
113 Then you can unmerge safely <c>tetex</c>:
114 </p>
115 <pre caption="Remove tetex">
116 # <i>emerge -C tetex</i>
117 </pre>
118
119 <p>
120 Some weird errors have been reported when there were stray configuration files left
121 in <path>/etc/texmf</path>. For safety and a clean install of <c>TeX Live</c> it is
122 recommended to remove the <path>/etc/texmf/texmf.d/00texmf.cnf</path> file:
123 </p>
124 <pre caption="Cleanup /etc/texmf">
125 # <i>rm /etc/texmf/texmf.d/00texmf.cnf</i>
126 </pre>
127 <note>
128 You have not lost anything since you just saved your old configuration files.
129 </note>
130
131
132 <p>
133 Due to <c>tetex</c> using <c>texlinks</c> outside of the scope of the package
134 manager, simply unmerging it will have left some stray symlinks:
135 </p>
136 <pre caption="tetex stray symlink">
137 $ <i>ls -l /usr/bin/pdftex</i>
138 lrwxrwxrwx 1 root root 7 2007-07-09 07:34 /usr/bin/pdftex -> pdfetex
139 </pre>
140 <p>
141 Of course, pdfetex has gone with <c>tetex</c>'s removal, so the pdftex symlink
142 is a dead one. It can be safely removed.
143 The <c>find</c> command can help finding dead symlinks (with a GNU extension
144 though):
145 </p>
146 <pre caption="Find dead symlinks">
147 $ <i>find /usr/bin -type l ! -xtype f ! -xtype d</i>
148
149 /usr/bin/lamed
150 /usr/bin/latex
151 /usr/bin/amstex
152 /usr/bin/elatex
153 /usr/bin/eplain
154 /usr/bin/lambda
155 /usr/bin/pdftex
156 /usr/bin/pdflatex
157 /usr/bin/pdfamstex
158 </pre>
159 <p>
160 These are the files left over by my <c>tetex</c> installation.
161 </p>
162
163 <p>
164 <c>tetex</c> was also using <c>fmtutil</c> outside of the scope of the package
165 manager to generate the format files. With <c>TeX Live 2007</c> we are now
166 building most of the format files while compiling the packages; which format
167 files will be installed in <path>/var/lib/texmf</path>. That means you have to make
168 sure that there are no stray format files:
169 </p>
170 <pre caption="Remove stray format files">
171 # <i>rm -rf /var/lib/texmf/web2c</i>
172 </pre>
173
174 </body>
175 </section>
176 </chapter>
177 <chapter>
178 <title> Installing TeX Live 2007 </title>
179 <section>
180 <body>
181
182 <p>
183 If you have passed through all the above steps, now installing <c>TeX Live
184 2007</c> should be very easy.
185 </p>
186 <pre caption="Install TeX Live 2007">
187 # <i>emerge texlive</i>
188 </pre>
189
190 <p>
191 In theory this should just go smoothly and install everything. You might want at
192 some point to tune <c>app-text/texlive</c> use flags to install extra TeX
193 packages, but you can do it later; <c>app-text/texlive</c> is just a meta-ebuild
194 that pulls the real packages depending on its use flags.
195 </p>
196
197 <p>
198 Nevertheless, it is possible that you get dependencies problems, errors while
199 installing a package, etc. In that case, you are advised to file a bug on
200 <uri>https://bugs.gentoo.org</uri>. If you do file a bug, please include at
201 least the output of <c>texconfig conf</c> (run as the same user that failed to
202 install because some environment variables might be important) in addition to
203 the error; this output will most often be requested.
204 </p>
205 </body>
206 </section>
207 </chapter>
208
209 <chapter>
210 <title> Configuration </title>
211
212 <section>
213 <title>Introduction</title>
214 <body>
215 <p>
216 As it was the case for <c>tetex-3</c>, <c>TeX Live</c> on <c>Gentoo</c> has its
217 three main configuration files splitted and handled by <c>texmf-update</c>.
218 These files are, namely, <path>texmf.cnf</path>, <path>fmtutil.cnf</path>,
219 <path>updmap.cfg</path>. They lie in <path>/etc/texmf/web2c</path>; you should
220 not modify them directly because the changes will be lost the next time
221 <c>texmf-update</c> is ran.
222 </p>
223 </body>
224 </section>
225
226 <section>
227 <title> texmf.cnf </title>
228 <body>
229 <p>
230 The <path>texmf.cnf</path> configuration file is the main configuration file for your
231 TeX installation, it contains various variable definitions that will be used by
232 a lot of programs.
233 </p>
234 <p>
235 The <path>texmf.cnf</path> file is the result of the concatenation of the files in
236 <path>/etc/texmf/texmf.d</path>. In order to modify your TeX environment
237 configuration, you should modify the files there. At the time of writing,
238 <c>Gentoo TeX Live</c>'s ebuild install six files there:
239 </p>
240 <pre caption="texmf.d installed files">
241 00header.cnf
242 05searchpaths.cnf
243 10standardpaths.cnf
244 15options.cnf
245 20sizes.cnf
246 25misc.cnf
247 </pre>
248 <p>
249 This is the result of the splitting in their respective sections of a (lightly)
250 modified <path>texmf.cnf</path> file from <c>TeX Live 2007</c> DVD.
251 </p>
252
253 <p>
254 The files <path>00header.cnf</path>, <path>05searchpaths.cnf</path>,
255 <path>10standardpaths.cnf</path> and <path>25misc.cnf</path> should not be
256 modified and kept as is. If the defaults can be improved, please file a bug.
257 </p>
258 <warn>
259 The <c>TeX Live</c> ebuilds are not aware of paths changes of those files,
260 so if you change any path there, make sure you know what you are doing.
261 </warn>
262
263 <p>
264 The files <path>15options.cnf</path> and <path>20sizes.cnf</path> can be
265 modified with caution. The comments in these files should be explicit of what
266 option means what. For example, in <path>20sizes.cnf</path> you can increase TeX
267 memory, in case you are trying to compile a too big document and run into <c>TeX
268 capacity exceeded, sorry</c> errors.
269 </p>
270
271 <p>
272 If you wish to append some additions to the <path>texmf.cnf</path> file, you can also
273 create a new file in <path>/etc/texmf/texmf.d</path>, called for example
274 <path>99myadditions.cnf</path>. Beware though to not give it a higher priority than
275 the core configuration files, so it should begin with a two digits number greater than
276 <c>25</c>.
277 </p>
278
279 <p>
280 Packages that need to append something to the <path>texmf.cnf</path> file get the same
281 treatment, they should install a <path>texmf.d</path> file instead:
282 </p>
283 <pre caption="Sample code for installing a texmf.d file">
284 <keyword>insinto</keyword> <const>/etc/texmf/texmf.d</const>
285 <keyword>doins</keyword> <const>40mytexmfadditions.cnf</const>
286 </pre>
287 </body>
288 </section>
289
290 <section>
291 <title>updmap.cfg</title>
292 <body>
293 <p>
294 The <path>updmap.cfg</path> is the configuration file used by <c>updmap</c>
295 (and <c>updmap-sys</c>), unless otherwise specified. It tells it which font maps
296 to update for the various TeX output drivers.
297 </p>
298 <p>
299 The <path>updmap.cfg</path> file in <path>/etc/texmf/web2c</path> is the result of
300 the concatenation of the files in <path>/etc/texmf/updmap.d</path>.
301 The initial <path>00updmap.cfg</path> file installed by <c>app-text/texlive-core</c> is
302 the result of <c>updmap --syncwithtrees</c> ran on the <c>texmf</c> tree that it
303 installs (in fact, it just mimics what <c>updmap --syncwithtrees</c> would do,
304 but it is only a technical detail).
305 </p>
306
307 <p>
308 Various <c>TeX Live</c> ebuilds will add files to the
309 <path>/etc/texmf/updmap.d</path> directory, when they install fonts. While you
310 can edit those files to disable some font maps to be updated, it would probably
311 be wiser to remove the relevant package.
312 </p>
313
314 <p>
315 If a third party package wants to add some font maps, it should install a file
316 in <path>/etc/texmf/updmap.d</path> and let <c>texmf-update</c> handle it.
317 </p>
318 <warn>
319 Sometimes you can see <c>updmap-sys --enable Map=mymap.map</c> in some ebuilds
320 or some installation instructions of a third party font package, while this
321 might work at a first try, the changes will be reverted the next time
322 <c>texmf-update</c> is ran.
323 </warn>
324 <p>
325 The good way of handling it would be to create a file to be installed in
326 <path>/etc/texmf/updmap.d</path> and install it for TeX distributions that support the
327 <c>texmf-update</c> way:
328 </p>
329 <pre caption="How to enable a font map">
330 <keyword>inherit</keyword> <ident>latex-package</ident>
331 ...
332 <stmt>src_install()</stmt> {
333 ...
334 <keyword>if</keyword> <stmt>latex-package_has_tetex_3</stmt>; then
335 <keyword>insinto</keyword> /etc/texmf/updmap.d
336 <keyword>doins</keyword> myfontmapconfig.cfg
337 <keyword>fi</keyword>
338 ...
339 }
340 ...
341 <stmt>pkg_postinst()</stmt> {
342 <stmt>latex-package_pkg_postinst</stmt>
343 <stmt>latex-package_has_tetex_3</stmt> || updmap-sys --enable Map=mymap.map
344 }
345
346 <stmt>pkg_postrm()</stmt> {
347 <stmt>latex-package_pkg_postinst</stmt>
348 <stmt>latex-package_has_tetex_3</stmt> || updmap-sys --disable Map=mymap.map
349 }
350 </pre>
351 <p>
352 The files in <path>/etc/texmf/updmap.d</path> should respect <c>updmap</c> syntax:
353 </p>
354 <pre caption="Snippet of updmap.cfg explaining the syntax">
355 There are two possible entries: Map and MixedMap. Both have one additional
356 argument: the file name of the map file. MixedMap ("mixed" means that
357 the font is available as bitmap and as outline) lines will not be used
358 in the default map of dvips if dvipsPreferOutline is false. Inactive
359 Map files should be marked by "#! " (without the quotes), not just #.
360 </pre>
361 </body>
362 </section>
363 <section>
364 <title>fmtutil.cnf</title>
365 <body>
366 <p>
367 The <path>fmtutil.cnf</path> file contains the information on how to build a format
368 file and how to handle it.
369 </p>
370
371 <p>
372 The <path>fmtutil.cnf</path> file is the result of the concatenation of the files in
373 <path>/etc/texmf/fmtutil.d</path>. Various <c>TeX Live</c> ebuilds install files
374 there, those files come with the formats they add support for and the symlink to
375 the relevant engine.
376 </p>
377
378 <pre caption="Snippet of the fmtutil.cnf(5) man page that explains the syntax">
379 The fmtutil.cnf file contains the configuration information for fmtutil(8).
380 Each line contains the name of the format (e.g., "tex", "latex", "omega"),
381 the name of the engine that is used by that format (e.g., "tex", "etex", "omega"),
382 the pattern file (e.g., language.dat, language.def), and any arguments
383 (name of an .ini file).
384
385 Fields are separated by whitespace and complete lines can be commented out with "#".
386 The "pattern file" field cannot be used to define a file that is used while
387 building the format. It tells fmtutil which file the format creation procedure reads
388 and it has an effect to the options --showhyphen and --byhyphen.
389 If the format has no way to customize hyphenation, a "-" can be used to indicate this.
390 </pre>
391 <p>
392 <c>TeX Live</c> ebuilds that install a <path>fmtutil.d</path> file install the relevant
393 format files in <path>/var/lib/texmf/web2c</path> and create the symlink from the format to
394 the engine.
395 </p>
396 <p>
397 It should be noted that when a support file for a language gets added,
398 <c>texmf-update</c> takes care of adding it to the <path>language.dat</path> file and
399 regenerates the format files so that they support the newly installed language.
400 </p>
401 </body>
402 </section>
403 <section>
404 <title> Updating your configuration </title>
405 <body>
406 <p>
407 Now that you know how <c>TeX Live</c> configuration is managed, you should
408 be able to port the changes you had made to your older TeX distribution
409 configuration to the <c>TeX Live</c> configuration layout.
410 </p>
411 </body>
412 </section>
413
414 </chapter>
415
416 <chapter>
417 <title> Common errors </title>
418
419 <section>
420 <title>Introduction</title>
421 <body>
422 <p>
423 In this chapter we will try to give a short summary of the most common errors
424 and explain what has gone wrong.
425 </p>
426 </body>
427 </section>
428
429 <section>
430 <title>Format was written by (pdf)etex</title>
431 <body>
432
433 <p>
434 Sometimes when installing some packages that requires latex, you'll get this
435 error:
436 </p>
437 <pre caption="Format was written by pdfetex">
438 ---! //var/lib/texmf/web2c/latex.fmt was written by pdfetex
439 </pre>
440 <p>
441 This is due to old files remaining from an old installation of a <c>TeX</c>
442 distribution based on <c>etex</c>. That most likely means you did not follow
443 entirely this guide, especially the <uri link="#uninstall">Clean uninstall
444 chapter </uri>.
445 </p>
446
447 <p>
448 Nevertheless, it is still possible to fix it quickly without having to reinstall
449 anything, just run as root:
450 </p>
451 <pre caption="Remove old formats">
452 # <i>rm -rf /var/lib/texmf/web2c</i>
453 # <i>texmf-update</i>
454 </pre>
455 </body>
456 </section>
457
458 <section>
459 <title>Format directory does not exist</title>
460 <body>
461
462 <p>
463 When installing e.g., <c>texlive-latex</c>, you might encounter the error:
464 </p>
465 <pre caption="Format directory does not exist">
466 fmtutil: format directory
467 `/var/tmp/portage/dev-texlive/texlive-latex-2007/work/texmf-var/web2c' does not
468 exist.
469 </pre>
470
471 <p>
472 This is most likely to be due to a wrong configuration. You should try to run
473 the following command and get the same results:
474 </p>
475 <pre caption="TEXMFMAIN definition">
476 $ <i>kpsewhich --var-value=TEXMFMAIN</i>
477 /usr/share/texmf
478 </pre>
479 <p>
480 This is very important, since <c>fmtutil</c> looks for <c>mktexdir</c> at this
481 location; if you have a different result then <c>fmtutil</c> will not find
482 <c>mktexdir</c> and thus will fail to create the directory where to temporarily
483 store the compiled formats.
484 </p>
485
486 <p>
487 There is no magic command to fix this one, you should check that your
488 configuration is correct, that there is no stray configuration file in
489 <path>/etc/texmf/texmf.d</path>. This will most likely be due to
490 <path>00texmf.cnf</path> being still there and thus setting wrong definitions
491 for the <path>texmf.cnf</path> file. Please refer to the <uri
492 link="#uninstall">Clean uninstall chapter </uri>.
493 </p>
494 </body>
495 </section>
496
497 <section>
498 <title>Missing .tex files</title>
499 <body>
500 <p>
501 When installing <c>texlive-latex</c> (or any other format that has babel
502 hyphenation support), you might encounter an error like:
503 </p>
504 <pre caption="missing bghyphen.tex">
505 ===========================================
506 Local configuration file hyphen.cfg used
507 ===========================================
508
509 (/var/tmp/portage/dev-texlive/texlive-latex-2007/work/texmf-dist/tex/generic/ba
510 bel/hyphen.cfg (/usr/share/texmf/tex/generic/hyphen/hyphen.tex)
511 (/usr/share/texmf/tex/generic/hyphen/ushyphmax.tex)
512 (/usr/share/texmf/tex/generic/hyphen/dumyhyph.tex)
513 (/usr/share/texmf/tex/generic/hyphen/zerohyph.tex)
514 (/usr/share/texmf/tex/generic/hyphen/zerohyph.tex)
515 (/usr/share/texmf-dist/tex/generic/xu-hyphen/xu-bahyph.tex
516 (/usr/share/texmf/tex/generic/hyphen/bahyph.tex))
517 (/usr/share/texmf-dist/tex/generic/xu-hyphen/xu-bghyphen.tex
518 ! I can't find file `bghyphen.tex'.
519 l.10 \input bghyphen.tex
520
521 Please type another input file name:
522 ! Emergency stop.
523 l.10 \input bghyphen.tex
524
525 No pages of output.
526 Transcript written on latex.log.
527 Error: `pdftex -ini -jobname=latex -progname=latex
528 -translate-file=cp227.tcx *latex.ini' failed
529 </pre>
530 <p>
531 In that case, you will have to check which <path>language.dat</path> file is being
532 used:
533 </p>
534 <pre caption="find language.dat">
535 $ <i>kpsewhich language.dat</i>
536 /usr/share/texmf/tex/generic/config/language.dat
537 </pre>
538 <p>
539 This file is automatically generated by <c>texmf-update</c>, it is the result of
540 the concatenation of <path>language.*.dat</path> files present in the directory where
541 is <path>language.us</path>. This directory should be
542 <path>/usr/share/texmf/tex/generic/config/</path>. So you should check that there are
543 no other <path>language.*.dat</path> files in that directory than the ones installed
544 by the various <c>dev-texlive/texlive-lang*</c> ebuilds. A file present in that
545 directory means that you want to enable hyphenation support for a specific
546 language; and if you don't have the hyphenation support files this will cause
547 formats that can use this extra hyphenation support to fail to build.
548 </p>
549 </body>
550 </section>
551 </chapter>
552 </guide>
553
554
555
556 --
557 gentoo-commits@g.o mailing list