[subversion-commit] SVN tetex commit + diffs: r261 -
tex-common/trunk/doc
Florent Rougon
frn at costa.debian.org
Tue Oct 18 11:10:09 UTC 2005
Author: frn
Date: 2005-10-18 11:10:08 +0000 (Tue, 18 Oct 2005)
New Revision: 261
Modified:
tex-common/trunk/doc/Debian-TeX-Policy.sgml
Log:
Add structure and information to the section about font configuration.
It should be quite usable now.
Modified: tex-common/trunk/doc/Debian-TeX-Policy.sgml
===================================================================
--- tex-common/trunk/doc/Debian-TeX-Policy.sgml 2005-10-18 09:06:26 UTC (rev 260)
+++ tex-common/trunk/doc/Debian-TeX-Policy.sgml 2005-10-18 11:10:08 UTC (rev 261)
@@ -12,7 +12,8 @@
<name>The Debian teTeX mailing List</name>
<email>debian-tetex-maint at lists.debian.org</email>
</author>
- <version>version 0.31, 2005-10-16</version>
+ <!-- Maybe an SVN Id should be used here. Hmmm? -->
+ <version>version 0.32, 2005-10-18</version>
<abstract>
This document provides a set of rules for the packaging of
@@ -223,7 +224,7 @@
<p>
Debian packages generally install files in
<var>TEXMFMAIN</var> exclusively (but see <ref
- id="names_and_texmfsite">), and may ship or create empty
+ id="sec-names-and-texmfsite">), and may ship or create empty
directories in the other trees, in accordance with Debian
Policy. Packages should take care to ignore
<var>TEXMFHOME</var> in their maintainer scripts.
@@ -250,7 +251,7 @@
</sect>
- <sect id="names_and_texmfsite">
+ <sect id="sec-names-and-texmfsite">
<heading>Filenames and installation of alternative files</heading>
<p>
@@ -297,7 +298,7 @@
</p>
</sect>
- <sect id="documentation">
+ <sect id="sec-documentation">
<heading>Documentation</heading>
<p>
@@ -385,99 +386,247 @@
<sect1 id="sec-font-configuration">
<heading>Font configuration</heading>
+
<p>
- A package named <var>package</var> that provides PostScript
- Type 1 fonts for TeX should be useable with any Basic TeX
- Package. To achieve this, it should depend on
- <package>tex-common</package> but not on a Basic TeX Package. It
- should install the necessary map files below
- <file>/etc/texmf/map/</file><footnote>This directory (or relevant
- subdirectories such as <file>dvipdfm</file>, <file>dvips</file> and
- <file>pdftex</file>) is symlinked from
- <file><var>TEXMFMAIN</var>/fonts/map</file> by the Basic TeX
- packages. For more details about the placement of map files and
- other TeX-related files, please refer to <file>TETEXDOC.pdf</file>
- (<tt>texdoc TETEXDOC</tt>) for teTeX, and more generally to the TeX
- Directory Structure, also known as TDS and found at <url
- id="http://www.tug.org/tds/" name="http://www.tug.org/tds/">
- (teTeX 3 follows TDS version 1.1).</footnote> and have
- them registered by putting a configuration file with extension
- <tt>.cfg</tt> into <file>/etc/texmf/updmap.d/</file> and calling
- <tt>update-updmap --quiet</tt>. The file contents will then be
- incorporated into <file>/var/lib/texmf/web2c/updmap.cfg</file>, the
- effective configuration file for <prgn>updmap-sys</prgn>.
- </p>
+ A package that provides PostScript Type 1 fonts for TeX should
+ be usable with any Basic TeX Package. The recommended way to
+ implement the configuration scheme described below is to use the
+ <prgn>debhelper</prgn> program <prgn>dh_installtexfonts</prgn>
+ provided by <package>tex-common</package>. See <manref
+ name="dh_installtexfonts" section="1"> for usage details.
<p>
- <prgn>updmap-sys</prgn> has to be called afterwards. It is
- recommended to invoke the three programs in the following order:
- <prgn>update-updmap</prgn>, <prgn>mktexlsr</prgn> and then
- <prgn>updmap-sys</prgn>; the <prgn>mktexlsr</prgn> call is necessary
- for <prgn>updmap-sys</prgn> to locate the newly installed files (map
- files shipped by <var>package</var>; additionally,
- <file>/var/lib/texmf/web2c/updmap.cfg</file> might have been created
- by <prgn>update-updmap</prgn>, although it more probably already
- existed), and would be of no use to <prgn>update-updmap</prgn>.
- Since <prgn>mktexlsr</prgn> and <prgn>updmap-sys</prgn> are provided
- by the Basic TeX packages, <var>package</var> has to ensure that
- they are only called when found in <tt>$PATH</tt>. Sample
- implementations for this behaviour can be found in <ref
- id="appen-sample-font">.
- </p>
+ For the rest of this section, we'll assume we are dealing with a
+ package named <var>package</var> that installs PostScript
+ Type 1 fonts for TeX. <var>package</var> should fulfill the
+ following requirements:
+ <enumlist>
+ <item>
+ It should depend on <package>tex-common</package> (for
+ <prgn>update-updmap</prgn> and a sane <file>texmf.cnf</file>,
+ so that <prgn>mktexlsr</prgn> and <prgn>updmap-sys</prgn> can
+ be run safely if they are present) but not on any Basic TeX
+ Package, unless needed for another task than simply installing
+ the fonts for TeX.
+ </item>
- <p>
- If <var>package</var> is removed, but not purged, its map files will
- stay in subdirectories of <file>/etc/texmf/map/</file>, but the
- actual font files below <file>/usr/share/texmf/</file> are removed,
- rendering the fonts unusable. Therefore, <var>package</var> has to
- make sure that its <prgn>update-updmap</prgn> configuration files in
- <file>/etc/texmf/updmap.d/</file> are ignored when it is in this
- state. This can be achieved by putting the "magic comment":
+ <item>
+ <p>
+ It should install the necessary map files (<file>.map</file>
+ extension) below <file>/etc/texmf/map/</file>. This directory
+ (or relevant subdirectories thereof, such as
+ <file>dvipdfm</file>, <file>dvips</file> and
+ <file>pdftex</file>) is symlinked from
+ <file><var>TEXMFMAIN</var>/fonts/map</file> by the Basic TeX
+ Packages.
+ </p>
+ <p>
+ For more details about the placement of map files and other
+ TeX-related files, please refer to <file>TETEXDOC.pdf</file>
+ (<tt>texdoc TETEXDOC</tt>) for teTeX, and more generally to
+ the TeX Directory Structure, also known as TDS and found at
+ <url id="http://www.tug.org/tds/"
+ name="http://www.tug.org/tds/"> (teTeX 3 follows TDS
+ version 1.1). Of course, when any these documents
+ mentions a directory under <file><var>TEXMFMAIN</var></file>
+ that is, due to the symbolic links installed by the Basic TeX
+ Packages, accessible under <file>/etc</file>,
+ <var>package</var> should install the files in the appropriate
+ subdirectory of <file>/etc</file>, because the symlinks mean
+ that the directory is considered to contain configuration
+ files (for instance, don't install map files into
+ <file>/usr/share/texmf/fonts/map/dvips/</file>; use
+ <file>/etc/texmf/map/dvips/</file> instead).
+ </p>
+ </item>
+
+ <item>
+ It should also obviously install other needed or useful files
+ provided by upstream to use the fonts with TeX-related
+ programs (<file>.pfb</file>, <file>.tfm</file>,
+ <file>.enc</file>, <file>.fd</file>, <file>.sty</file>,
+ documentation, etc.).
+ </item>
+
+ <item>
+ <p>
+ It should install one or more configuration files with names
+ following the pattern <tt>10<var>name</var>.cfg</tt> into
+ <file>/etc/texmf/updmap.d/</file>. Such files will be later
+ merged by <prgn>update-updmap</prgn> to form
+ <file>/var/lib/texmf/web2c/updmap.cfg</file>, the effective
+ configuration file for <prgn>updmap-sys</prgn>.
+ </p>
+
+ <p>
+ Exactly what to put in these files is documented in <manref
+ name="update-updmap" section="1">. Basically, they should
+ contain the pseudo-comment:
+
<example>
# -_- DebPkgProvidedMaps -_-
</example>
- in these files, and installing a file in
- <file>/var/lib/tex-common/fontmap-cfg/</file> with the name
- <file><var>package</var>.list</file> that contains:
+ as well as the usual <tt>Map</tt> and/or <tt>MixedMap</tt>
+ lines that <var>package</var> needs to add to
+ <file>/var/lib/texmf/web2c/updmap.cfg</file>.
+ </p>
+ </item>
+ <item>
+ <p>
+ It should install a file named
+ <file>/var/lib/tex-common/fontmap-cfg/<var>package</var>.list</file>
+ that contains a reference to every <tt>.cfg</tt> file from the
+ previous step, one per line. For instance, if
+ <var>package</var> installs <file>10foo.cfg</file> and
+ <file>10bar.cfg</file> into <file>/etc/texmf/updmap.d/</file>,
+ the contents of
+ <file>/var/lib/tex-common/fontmap-cfg/<var>package</var>.list</file>
+ should be:
+
<example>
10foo
-12bar
+10bar
</example>
- if for instance <var>package</var> installs the files
- <file>10foo.cfg</file> and <file>12bar.cfg</file> in
- <file>/etc/texmf/updmap.d/</file>. When <var>package</var> is
- removed, but not purged, <file><var>package</var>.list</file> is
- removed, thus disabling the <file>10foo.cfg</file> and
- <file>12bar.cfg</file> <prgn>update-updmap</prgn> configuration
- files. As a consequence, after running <prgn>update-updmap</prgn>,
- <prgn>mktexlsr</prgn> and <prgn>updmap-sys</prgn> in
- <prgn><var>package</var>.postrm</prgn>, <var>package</var>'s map
- files won't be listed anymore in the final map files
- (<file>psfonts.map</file>, <file>pdftex.map</file>...) generated by
- <prgn>updmap-sys</prgn>.
+ This <file><var>package</var>.list</file> file must be shipped
+ in the <tt>.deb</tt>, so that when <var>package</var> is
+ removed but not purged, <file><var>package</var>.list</file>
+ disappears from <file>/var/lib/tex-common/fontmap-cfg/</file>.
+ </p>
+
+ <p>
+ The purpose of the "magic comment" in
+ <file>/etc/texmf/updmap.d/*.cfg</file> files and their
+ associated
+ <file>/var/lib/tex-common/fontmap-cfg/<var>package</var>.list</file>
+ files is explained below.
+ </p>
+ </item>
+
+ <item>
+ <p>
+ It should run <tt>update-updmap --quiet</tt> to merge the
+ <tt>.cfg</tt> files from <file>/etc/texmf/updmap.d/</file>
+ into <file>updmap.cfg</file>. But before running
+ <prgn>updmap-sys</prgn> with the updated
+ <file>updmap.cfg</file>, <var>package</var> should call
+ <prgn>mktexlsr</prgn> so that <prgn>updmap-sys</prgn> can
+ locate the newly-installed files (in particular, the map files
+ shipped by <var>package</var>). It is recommended to run the
+ three commands in the following order: <tt>update-updmap
+ --quiet</tt>, <tt>mktexlsr</tt> and then <tt>updmap-sys</tt>.
+ </p>
+
+ <p>
+ <em>Rationale</em>: we have already explained why the
+ <prgn>mktexlsr</prgn> call is necessary before running
+ <prgn>updmap-sys</prgn>. It is also slightly better after
+ <prgn>update-updmap</prgn>, because
+ <file>/var/lib/texmf/web2c/updmap.cfg</file> might have been
+ created by <prgn>update-updmap</prgn>, although it more
+ probably already existed. And since it would be of no use to
+ call <prgn>mktexlsr</prgn> before <prgn>update-updmap</prgn>,
+ it is better after, just in case.
+ </p>
+
+ <p>
+ Since <prgn>mktexlsr</prgn> and <prgn>updmap-sys</prgn> are
+ provided by the Basic TeX Packages, <var>package</var> has to
+ ensure that they are only called when found in <tt>$PATH</tt>
+ (unless <var>package</var> depends on the Basic TeX Packages
+ for some reason). As long as <package>tex-common</package> is
+ configured, it is expected that <prgn>mktexlsr</prgn> and
+ <prgn>updmap-sys</prgn> can be safely run whenever available
+ (even if the packages that provide them aren't configured).
+ </p>
+
+ <p>
+ A sample implementation of this scheme can be found in <ref
+ id="appen-sample-font">, but don't forget that
+ <prgn>dh_installtexfonts</prgn> can do the work for you.
+ </p>
+ </item>
+ </enumlist>
</p>
- <p>That way, <file>10foo.cfg</file> and <file>12bar.cfg</file> can
- (and should, unless there is a good reason not to) be shipped as
- conffiles in <file>/etc/texmf/updmap.d/</file> (which implies they
- stay there when <var>package</var> is removed, but not purged;
- without the "magic comment", they would be unconditionally included
- in <file>/var/lib/texmf/web2c/updmap.cfg</file> by
- <prgn>update-updmap</prgn>, and in the final map files by
- <prgn>updmap-sys</prgn>).
+ <p>
+ The rest of this section explains the purpose of the "magic
+ comments" and the
+ <file>/var/lib/tex-common/fontmap-cfg/<var>package</var>.list</file>
+ file. Suppose that <var>package</var> is removed, but not purged.
+ Its map files will stay in subdirectories of
+ <file>/etc/texmf/map/</file>, but the actual font files below
+ <file>/usr/share/texmf/</file> will be removed, rendering the fonts
+ unusable. Therefore, <var>package</var> has to make sure that its
+ <prgn>update-updmap</prgn> configuration files in
+ <file>/etc/texmf/updmap.d/</file> are ignored when it is in this
+ state. Besides, we want the <file>/etc/texmf/updmap.d/*.cfg</file>
+ files to be conffiles (unless we really have no other choice),
+ because then <prgn>dpkg</prgn> automatically handles upgrades and
+ preserves user modifications for them. As a consequence, moving the
+ <file>.cfg</file> files from <var>package</var> out of the way when
+ it is removed is not an option. Moreover, the user would wonder
+ where his configuration files have gone in such a case.
</p>
<p>
- The recommended way to implement the configuration scheme
- described in this section is to use the <prgn>debhelper</prgn>
- program <prgn>dh_installtexfonts</prgn> provided by
- <package>tex-common</package>. See <manref
- name="dh_installtexfonts" section="1"> for usage details.
+ The solution we chose was to add a little bit of logic into
+ <prgn>update-updmap</prgn>, so that whenever it sees a
+ <file>.cfg</file> file (let's call it <file>10foo.cfg</file>) that
+ has the "magic comment", it actually includes its contents into
+ <file>updmap.cfg</file> if, and only if <tt>10foo</tt> appears on a
+ line by itself in one of the <file>.list</file> files in
+ <file>/var/lib/tex-common/fontmap-cfg/</file>. Additionally, that
+ <file>.list</file> file should be
+ <file>/var/lib/tex-common/fontmap-cfg/<var>package</var>.list</file>
+ if <file>10foo.cfg</file> comes from <var>package</var>, for simple
+ reasons of tidiness.
</p>
+
+ <p>
+ With this little mechanism in place, all the rest follows as
+ expected:
+ <list>
+ <item>
+ When <var>package</var> is removed, but not purged,
+ <file><var>package</var>.list</file> is first removed by
+ <prgn>dpkg</prgn> from
+ <file>/var/lib/tex-common/fontmap-cfg/</file>, thus disabling
+ the the <file>.cfg</file> files shipped by <var>package</var>
+ as far as <prgn>update-updmap</prgn> is concerned. Then,
+ <file><var>package</var>.postrm</file> calls
+ <prgn>update-updmap</prgn>, <prgn>mktexlsr</prgn> and
+ <prgn>updmap-sys</prgn>, with the result that
+ <var>package</var>'s map files aren't listed anymore in the
+ final map files (<file>psfonts.map</file>,
+ <file>pdftex.map</file>...) generated by
+ <prgn>updmap-sys</prgn>.
+ </item>
+
+ <item>
+ If <var>package</var> is reinstalled later,
+ <file><var>package</var>.list</file> first reappears in
+ <file>/var/lib/tex-common/fontmap-cfg/</file>. Then,
+ <file><var>package</var>.postinst</file> runs
+ <prgn>update-updmap</prgn>, <prgn>mktexlsr</prgn> and
+ <prgn>updmap-sys</prgn>, and the <file>.cfg</file> files
+ shipped by <var>package</var> aren't ignored by
+ <prgn>update-updmap</prgn> this time, since they are
+ referenced in
+ <file>/var/lib/tex-common/fontmap-cfg/<var>package</var>.list</file>.
+ Thus, the map files shipped by <var>package</var> end up in
+ the final map files generated by <prgn>updmap-sys</prgn>.
+ </item>
+ </list>
+
+ All this with the <file>/etc/texmf/updmap.d/*.cfg</file> files
+ being simple conffiles, in order to let <prgn>dpkg</prgn> do the
+ tedious work of handling upgrades while preserving user
+ modifications.
+ </p>
</sect1>
<sect1>
More information about the Pkg-tetex-commits
mailing list