doc changes

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

4 files changed, 49 insertions, 22 deletions

diff --git a/Build/source/texk/kpathsea/texmf.cnf b/Build/source/texk/kpathsea/texmf.cnf
index b3ec4fe9e26..9e11b1da01a 100644
--- a/Build/source/texk/kpathsea/texmf.cnf
+++ b/Build/source/texk/kpathsea/texmf.cnf
@@ -421,8 +421,15 @@ RUBYINPUTS   = .;$TEXMF/scripts/{$progname,$engine,}/ruby//
 % This definition isn't used from this .cnf file itself (that would be
 % paradoxical), but the compile-time default in paths.h is built from it.
 % The SELFAUTO* variables are set automatically from the location of
-% argv[0], in kpse_set_progname.
-%
+% argv[0], in kpse_set_program_name.
+% 
+% This main texmf.cnf file is installed, for a release YYYY, in a
+% directory such as /usr/local/texlive/YYYY/texmf/web2c/texmf.cnf.
+% Since this file is subject to future updates, the TeX Live installer
+% or human administrator may also create a file
+% /usr/local/texlive/YYYY/texmf.cnf; any settings in this latter file
+% will take precedence over the distributed one under texmf/web2c.
+% 
 % For security reasons, it is better not to include . in this path.
 %
 TEXMFCNF = {$SELFAUTOLOC,$SELFAUTODIR,$SELFAUTOPARENT}{,{/share,}/texmf{-local,}/web2c}
diff --git a/Master/install-tl b/Master/install-tl
index 0ef2c5cb5f7..a3948cc50e0 100755
--- a/Master/install-tl
+++ b/Master/install-tl
@@ -1084,27 +1084,31 @@ sub do_texmf_cnf {
       push @newtmf, $line;
     }
   }
+  my $TMF;
   if (!$vars{'from_dvd'}) {
-    open(TMF,">$vars{'TEXDIR'}/texmf.cnf")
-        or die("Can't open $vars{'TEXDIR'}/texmf.cnf for writing: $!\n");
+    $TMF = ">$vars{'TEXDIR'}/texmf.cnf";
+    open(TMF, $TMF) || die "open($TMF) failed: $!\n";
     print TMF <<EOF;
-%
 % This is the texmf.cnf file which contains only changes from the
-% distributed texmf.cnf in texmf/web2c/texmf.cnf
-% Please do NOT change values in texmf/web2c/texmf.cnf, they will be
-% overwritten by later updates.
-% If you want to configure something to a value different from the one
-% in texmf/web2c/texmf.cnf, just put the changed value here.
+% texmf.cnf distributed for the release of year YYYY, which is in
+% TLROOT/YYYY/texmf/web2c/texmf.cnf.
+% 
+% Please do NOT change values in this YYYY/texmf/web2c/texmf.cnf file,
+% as they may be overwritten by later updates of the kpathsea
+% package(s).
+% 
+% Instead, if you want to configure something to a value different from
+% the one in texmf/web2c/texmf.cnf, just put the changed value here.
 %
 EOF
 ;
     foreach (@changedtmf) { print TMF; }
   } else {
-    open(TMF,">$vars{'TEXMFSYSVAR'}/web2c/texmf.cnf")
-        or die("Can't open $vars{'TEXMFSYSVAR'}/web2c/texmf.cnf for writing: $!\n");
+    $TMF = ">$vars{'TEXMFSYSVAR'}/web2c/texmf.cnf";
+    open (TMF, $TMF) || die "open($TMF) failed: $!\n";
     foreach (@newtmf) { print TMF; }
   }
-  close(TMF);
+  close(TMF) || warn "close($TMF) failed: $!";
 }
 
 #
diff --git a/Master/texmf/scripts/texlive/tlmgr.pl b/Master/texmf/scripts/texlive/tlmgr.pl
index 2d5d06bc67d..1bbb737294b 100755
--- a/Master/texmf/scripts/texlive/tlmgr.pl
+++ b/Master/texmf/scripts/texlive/tlmgr.pl
@@ -1516,15 +1516,24 @@ Do not ask for confirmation, remove immediately.
 =item B<generate fmtutil>
 =item B<generate updmap>
 
-B<WARNING:> This action overwrites any manual changes made in
-the respective files: it recreates them from scratch.
+The I<generate> action overwrites any manual changes made in the
+respective files: it recreates them from scratch.
 
-This is especially questionable with updmap, because the result will be
-to disable all maps which have been manually installed via C<updmap-sys
---enable>, e.g., for proprietary or local fonts.  Only the changes in
-the C<--localcfg> file mentioned below are incorporated.  
+For fmtutil and the language files, this is normal, and both the TeX
+Live installer and C<tlmgr> routinely call I<generate> for them.
 
-In more detail, this action regenerates any of the four config files
+For updmap, however, neither the installer nor C<tlmgr> use I<generate>,
+because the result would be to disable all maps which have been manually
+installed via C<updmap-sys --enable>, e.g., for proprietary or local
+fonts.  Only the changes in the C<--localcfg> file mentioned below are
+incorporated by I<generate>.
+
+On the other hand, if you only use the fonts and font packages within
+TeX Live, there is nothing wrong with using I<generate updmap>.  Indeed,
+we use it to generate the C<updmap.cfg> file that is maintained in the
+live source repository.
+
+In more detail: I<generate> remakes any of the four config files
 C<language.dat>, C<language.def>, C<fmtutil.cnf>, and C<updmap.cfg> from
 the information present in the local TLPDB. If the files
 C<language-local.dat>, C<language-local.def>, C<fmtutil-local.cnf>, or
diff --git a/Master/texmf/web2c/texmf.cnf b/Master/texmf/web2c/texmf.cnf
index b3ec4fe9e26..9e11b1da01a 100644
--- a/Master/texmf/web2c/texmf.cnf
+++ b/Master/texmf/web2c/texmf.cnf
@@ -421,8 +421,15 @@ RUBYINPUTS   = .;$TEXMF/scripts/{$progname,$engine,}/ruby//
 % This definition isn't used from this .cnf file itself (that would be
 % paradoxical), but the compile-time default in paths.h is built from it.
 % The SELFAUTO* variables are set automatically from the location of
-% argv[0], in kpse_set_progname.
-%
+% argv[0], in kpse_set_program_name.
+% 
+% This main texmf.cnf file is installed, for a release YYYY, in a
+% directory such as /usr/local/texlive/YYYY/texmf/web2c/texmf.cnf.
+% Since this file is subject to future updates, the TeX Live installer
+% or human administrator may also create a file
+% /usr/local/texlive/YYYY/texmf.cnf; any settings in this latter file
+% will take precedence over the distributed one under texmf/web2c.
+% 
 % For security reasons, it is better not to include . in this path.
 %
 TEXMFCNF = {$SELFAUTOLOC,$SELFAUTODIR,$SELFAUTOPARENT}{,{/share,}/texmf{-local,}/web2c}