update updmap doc

git-svn-id: svn://tug.org/texlive/trunk@26779 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 125 insertions, 33 deletions

diff --git a/Master/texmf/doc/man/man1/updmap-sys.man1.pdf b/Master/texmf/doc/man/man1/updmap-sys.man1.pdf
index 0f89f99b048..5c700c4c04c 100644
--- a/Master/texmf/doc/man/man1/updmap-sys.man1.pdf
+++ b/Master/texmf/doc/man/man1/updmap-sys.man1.pdf
diff --git a/Master/texmf/doc/man/man1/updmap.1 b/Master/texmf/doc/man/man1/updmap.1
index a89b4cdf766..e4a89cdefef 100644
--- a/Master/texmf/doc/man/man1/updmap.1
+++ b/Master/texmf/doc/man/man1/updmap.1
@@ -1,5 +1,5 @@
-.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.40.3.
-.TH UPDMAP "1" "June 2011" "TeX Live" "User Commands"
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.40.9.
+.TH UPDMAP "1" "June 2012" "TeX Live" "User Commands"
 .SH NAME
 updmap \- manage TeX font maps, per-user
 .br
@@ -11,21 +11,26 @@ updmap-sys \- manage TeX font maps, system-wide
 .B updmap-sys
 [\fIOPTION\fR] ... [\fICOMMAND\fR]
 .SH DESCRIPTION
-updmap (TeX Live) version $Id: updmap.pl 23034 2011\-06\-17 23:44:39Z karl $
+updmap (TeX Live, multi) version $Id: updmap.pl 26778 2012\-06\-01 17:36:30Z karl $
 .PP
 Update the default font map files used by pdftex, dvips, and dvipdfm(x),
-as determined by the configuration file updmap.cfg (the one returned by
-running "kpsewhich updmap.cfg").
+and optionally pxdvi, as determined by all configuration files updmap.cfg
+(the ones returned by running "kpsewhich \fB\-\-all\fR updmap.cfg", but see below).
 .PP
 Among other things, these map files are used to determine which fonts
 should be used as bitmaps and which as outlines, and to determine which
-fonts are included in the output.
+font files are included in the PDF or PostScript output.
 .PP
 By default, the TeX filename database (ls\-R) is also updated.
 .SH OPTIONS
 .TP
 \fB\-\-cnffile\fR FILE
 read FILE for the updmap configuration
+(can be given multiple times, in which case
+all the files are used)
+.TP
+\fB\-\-dvipdfmxoutputdir\fR DIR
+specify output directory (dvipdfm(x) syntax)
 .TP
 \fB\-\-dvipsoutputdir\fR DIR
 specify output directory (dvips syntax)
@@ -33,6 +38,9 @@ specify output directory (dvips syntax)
 \fB\-\-pdftexoutputdir\fR DIR
 specify output directory (pdftex syntax)
 .TP
+\fB\-\-pxdvioutputdir\fR DIR
+specify output directory (pxdvi syntax)
+.TP
 \fB\-\-outputdir\fR DIR
 specify output directory (for all files)
 .TP
@@ -61,28 +69,31 @@ show this message and exit
 \fB\-\-version\fR
 show version information and exit
 .TP
-\fB\-\-showoptions\fR ITEM
-show alternatives for options
+\fB\-\-showoption\fR OPTION
+show the current setting of OPTION
+.TP
+\fB\-\-showoptions\fR OPTION
+show possible settings for OPTION
 .TP
 \fB\-\-setoption\fR OPTION VALUE
-set option, where OPTION is one of:
-LW35, dvipsPreferOutline, dvipsDownloadBase35,
-or pdftexDownloadBase14
+set OPTION to value; option names below
 .TP
 \fB\-\-setoption\fR OPTION=VALUE
 as above, just different syntax
 .TP
 \fB\-\-enable\fR MAPTYPE MAPFILE
 add "MAPTYPE MAPFILE" to updmap.cfg,
-where MAPTYPE is either Map or MixedMap
+where MAPTYPE is Map, MixedMap, or KanjiMap
 .TP
 \fB\-\-enable\fR Map=MAPFILE
 add "Map MAPFILE" to updmap.cfg
 .HP
 \fB\-\-enable\fR MixedMap=MAPFILE add "MixedMap MAPFILE" to updmap.cfg
+.HP
+\fB\-\-enable\fR KanjiMap=MAPFILE add "KanjiMap MAPFILE" to updmap.cfg
 .TP
 \fB\-\-disable\fR MAPFILE
-disable MAPFILE, whether Map or MixedMap
+disable MAPFILE, of whatever type
 .TP
 \fB\-\-listmaps\fR
 list all active and inactive maps
@@ -96,11 +107,12 @@ disable unavailable map files in updmap.cfg
 .PP
 Explanation of the map types: the (only) difference between Map and
 MixedMap is that MixedMap entries are not added to psfonts_pk.map.
-The purpose is to help users with printers that render Type 1 outline
+The purpose is to help users with devices that render Type 1 outline
 fonts worse than mode\-tuned Type 1 bitmap fonts.  So, MixedMap is used
 for fonts that are available as both Type 1 and Metafont.
+KanjiMap entries are added to psfonts_t1.map and kanjix.map.
 .PP
-Explanation of the \fB\-\-setoption\fR possibilities:
+Explanation of the OPTION names for \fB\-\-showoptions\fR, \fB\-\-showoptions\fR, \fB\-\-setoption\fR:
 .TP
 dvipsPreferOutline
 true|false  (default true)
@@ -108,7 +120,7 @@ true|false  (default true)
 Whether dvips uses bitmaps or outlines, when both are available.
 .TP
 dvipsDownloadBase35
-true|false  (default false)
+true|false  (default true)
 .IP
 Whether dvips includes the standard 35 PostScript fonts in its output.
 .TP
@@ -117,6 +129,19 @@ true|false   (default true)
 .IP
 Whether pdftex includes the standard 14 PDF fonts in its output.
 .TP
+pxdviUse
+true|false  (default false)
+.IP
+Whether maps for pxdvi (Japanese\-patched xdvi) are under updmap's control.
+.TP
+kanjiEmbed
+(any string)
+.TP
+kanjiVariant
+(any string)
+.IP
+See below.
+.TP
 LW35
 URWkb|URW|ADOBEkb|ADOBE  (default URWkb)
 .IP
@@ -131,12 +156,77 @@ do not know anything about them.  They work by changing the default map
 file which the programs read, so they can be overridden by specifying
 command\-line options or configuration files to the programs, as
 explained at the beginning of updmap.cfg.
+.IP
+The options kanjiEmbed and kanjiVariant specify special replacements
+in the map lines.  If a map contains the string @kanjiEmbed@, then
+this will be replaced by the value of that option; similarly for
+kanjiVariant.  In this way, users of Japanese TeX can select different
+fonts to be included in the final output.
 .SH ENVIRONMENT
 .PP
 Explanation of trees and files normally used:
 .IP
-updmap both reads and writes TEXMFCONFIG/web2c/updmap.cfg, according to
-the actions specified.
+If \fB\-\-cnffile\fR is specified on the command line (possibly multiple
+times), its value(s) are used.  Otherwise, updmap reads all the
+updmap.cfg files found by running `kpsewhich \fB\-all\fR updmap.cfg',
+in the order returned by kpsewhich.  If multiple updmap.cfg files are
+found, all the maps mentioned in all the updmap.cfg files are merged.
+.IP
+There is one exception to keep upgradability from earlier versions of
+TeX Live: if a file TEXMFLOCAL/web2c/updmap\-local.cfg exists (formerly
+used by tlmgr to merge local fonts), then the file
+TEXMFLOCAL/web2c/updmap.cfg is ignored (if it exists) and the
+updmap\-local.cfg is used instead.  In this case, updmap recognizes the
+previous syntax for disabling map files in updmap\-local.cfg (this
+syntax is different from what is used now).
+.IP
+According to the actions, updmap might write to one of the given files
+or create a new updmap.cfg, described further below.
+.IP
+Where changes are saved: if config files are given on the command
+line, then the first one given will be used to save any changes from
+\fB\-\-setoption\fR, \fB\-\-enable\fR or \fB\-\-disable\fR.  If the config files are taken
+from kpsewhich output, then the algorithm is more complex:
+.IP
+1) If $TEXMFHOME/web2c/updmap.cfg or $TEXMFCONFIG/web2c/updmap.cfg
+appears in the list of used files, then the one listed first by
+kpsewhich \fB\-\-all\fR (equivalently, the one returned by kpsewhich
+updmap.cfg), is used.
+.IP
+2) If neither of the above two are present and changes are made, a
+new config file is created in $TEXMFCONFIG/web2c/updmap.cfg.
+.IP
+Multiple definitions of a font:
+.IP
+If a font is defined in more than one map file, then the definition
+coming from the first\-listed updmap.cfg is used.  If a font is
+defined multiple times in the same map file, one is chosen
+arbitrarily.  In both cases a warning is issued.
+.IP
+Disabling maps:
+.IP
+updmap.cfg files with higher priority (listed earlier) can disable
+maps mentioned in lower priority (listed later) updmap.cfg files by
+writing, e.g.,
+.IP
+#! Map mapname.map
+.IP
+or
+.IP
+#! MixedMap mapname.map
+.IP
+in the higher\-priority updmap.cfg file.
+.IP
+As an example, suppose you have a copy of MathTime Pro fonts
+and want to disable the Belleek version of the fonts; that is,
+disable the map belleek.map.  You can create the file
+$TEXMFCONFIG/web2c/updmap.cfg with the content
+.IP
+#! Map belleek.map
+Map mt\-plus.map
+Map mt\-yy.map
+.IP
+and call updmap.
 .IP
 updmap writes the map files for dvips (psfonts.map) and pdftex
 (pdftex.map) to the TEXMFVAR/fonts/map/updmap/{dvips,pdftex}/
@@ -145,13 +235,14 @@ directories.
 The log file is written to TEXMFVAR/web2c/updmap.log.
 .IP
 When updmap\-sys is run, TEXMFSYSCONFIG and TEXMFSYSVAR are used
-instead.  This is the only difference between updmap\-sys and updmap.
+instead of TEXMFCONFIG and TEXMFVAR, respectively.  This is the only
+difference between updmap\-sys and updmap.
 .IP
-Other locations can be used if overridden on the command line, or these
-trees don't exist, or you are not using the original TeX Live.
+Other locations may be used if you give them on the command line, or
+these trees don't exist, or you are not using the original TeX Live.
 .IP
 To see the precise locations of the various files that
-will be read and written, give the \fB\-n\fR option (or read the man page).
+will be read and written, give the \fB\-n\fR option (or read the source).
 .SH EXAMPLES
 .PP
 For step\-by\-step instructions on making new fonts known to TeX, read
@@ -162,7 +253,8 @@ Configuration and input files:
 .IP "\fIupdmap\&.cfg\fP"
 Main configuration file\&.  In
 \fItexmf/web2c\fP by default, but may be located elsewhere
-depending on your distribution\&.
+depending on your distribution\&.  Each texmf tree read should have its
+own \fIupdmap.cfg\fP.
 .IP "\fIdvips35\&.map\fP"
 Map file for standard 35 PostScript fonts for
 use with \fBdvips\fP(1)\&.
diff --git a/Master/texmf/doc/man/man1/updmap.man1.pdf b/Master/texmf/doc/man/man1/updmap.man1.pdf
index 11b298c7d69..58805dd3b0b 100644
--- a/Master/texmf/doc/man/man1/updmap.man1.pdf
+++ b/Master/texmf/doc/man/man1/updmap.man1.pdf
diff --git a/Master/texmf/scripts/tetex/updmap.pl b/Master/texmf/scripts/tetex/updmap.pl
index f9c43672f3d..d405072e113 100755
--- a/Master/texmf/scripts/tetex/updmap.pl
+++ b/Master/texmf/scripts/tetex/updmap.pl
@@ -1,6 +1,6 @@
 #!/usr/bin/env perl
 # mupdmap: utility to maintain map files for outline fonts.
-# $Id: updmap.pl 26744 2012-05-31 19:48:49Z karl $
+# $Id: updmap.pl 26778 2012-06-01 17:36:30Z karl $
 # 
 # Copyright 2011, 2012 Norbert Preining
 # This file is licensed under the GNU General Public License version 2
@@ -33,7 +33,7 @@ BEGIN {
 }
 
 
-my $version = '$Id: updmap.pl 26744 2012-05-31 19:48:49Z karl $';
+my $version = '$Id: updmap.pl 26778 2012-06-01 17:36:30Z karl $';
 
 use Getopt::Long qw(:config no_autoabbrev ignore_case_always);
 use strict;
@@ -43,7 +43,7 @@ use TeXLive::TLUtils qw(mkdirhier mktexupd win32 basename dirname
 #use Data::Dumper;
 #$Data::Dumper::Indent = 1;
 
-my $prg = basename($0);
+(my $prg = basename($0)) =~ s/\.pl$//;
 
 # sudo sometimes does not reset the home dir of root, check on that
 # see more comments at the definition of the function itself
@@ -1687,10 +1687,10 @@ sub read_updmap_file {
       if ($b eq "Map" || $b eq "MixedMap" || $b eq "KanjiMap") {
         my $c = shift @rest;
         if (!defined($c)) {
-          warning("updmap: apparently not a real disable line, ignored: $_\n");
+          warning("$prg: apparently not a real disable line, ignored: $_\n");
         } else {
           if (defined($data{'maps'}{$c})) {
-            warning("updmap: double mentioning of $c in $fn\n");
+            warning("$prg: double mention of $c in $fn\n");
           }
           $data{'maps'}{$c}{'status'} = 'disabled';
           $data{'maps'}{$c}{'type'} = $b;
@@ -1700,25 +1700,25 @@ sub read_updmap_file {
       next;
     }
     if (@rest) {
-      warning("updmap: line $i in $fn contains a syntax error, more than two words!\n");
+      warning("$prg: line $i in $fn contains a syntax error, more than two words!\n");
     }
     if (defined($settings{$a})) {
       if (check_option($a, $b)) {
         $data{'setting'}{$a}{'val'} = $b;
         $data{'setting'}{$a}{'line'} = $i;
       } else {
-        warning("updmap: unknown setting for $a: $b, ignored!\n");
+        warning("$prg: unknown setting for $a: $b, ignored!\n");
       }
     } elsif ($a eq "Map" || $a eq "MixedMap" || $a eq "KanjiMap") {
       if (defined($data{'maps'}{$b}) && $data{'maps'}{$b}{'type'} ne $a) {
-        warning("updmap: double mentioning of $b with conflicting types in $fn\n");
+        warning("$prg: double mention of $b with conflicting types in $fn\n");
       } else {
         $data{'maps'}{$b}{'type'} = $a;
         $data{'maps'}{$b}{'status'} = 'enabled';
         $data{'maps'}{$b}{'line'} = $i;
       }
     } else {
-      warning("updmap: unrecognized line $i in $fn: $_\n");
+      warning("$prg: unrecognized line $i in $fn: $_\n");
     }
   }
   return \%data;
@@ -1876,7 +1876,7 @@ sub merge_data {
 sub reset_root_home {
   if (!win32() && ($> == 0)) {  # $> is effective uid
     my $envhome = $ENV{'HOME'};
-    # if $HOME isn't an existing directory, that's ok; TLU does this.
+    # if $HOME isn't an existing directory, we don't care.
     if (defined($envhome) && (-d $envhome)) {
       # we want to avoid calling getpwuid as far as possible, so if
       # $envhome is one of some usual values we accept it without worrying.