texlive[43411] Master/tlpkg/doc/sys-user.txt: add start on sys-user

commits+preining at tug.org commits+preining at tug.org
Mon Mar 6 02:44:26 CET 2017

Revision: 43411
Author:   preining
Date:     2017-03-06 02:44:26 +0100 (Mon, 06 Mar 2017)
Log Message:
add start on sys-user documentation

Added Paths:

Added: trunk/Master/tlpkg/doc/sys-user.txt
--- trunk/Master/tlpkg/doc/sys-user.txt	                        (rev 0)
+++ trunk/Master/tlpkg/doc/sys-user.txt	2017-03-06 01:44:26 UTC (rev 43411)
@@ -0,0 +1,108 @@
+Usage and best practices for -sys and -user scripts in TeX Live
+Addition of fonts or formats to the set of TeX Live provided fonts
+and formats is done by two set of programs:
+	updmap / updmap-sys / updmap-user
+	fmtutil / fmtutil-sys / fmtutil-user
+These scripts work in either one of two modes: user or sys mode.
+Without any mode specification a warning is printed.
+System mode is selected by using either updmap-sys / fmtutil-sys or
+specifying the -sys command line option.
+User mode is selected by using either updmap-user / fmtutil-user or
+specifying the -user command line option.
+Before going into details about the differences, here some best 
+Best practices
+	Always use system mode (updmap-sys, fmtutil-sys)!
+There is practically never any reason to use the -user mode, but see
+below for valid use cases.
+Running *once* a program in user mode switches permanently, and all
+updates on the system side will be shadowed by files generated in
+the user directories.
+Think twice and read the documentation before running any of the -user scripts!
+We list some use cases together with options how to deal with them on
+different setups.
+Use case 1: single user computer - add fonts
+Probably the most common case. We suggest the following:
+* put the fonts into TEXMFLOCAL (following the TDS standard)
+* add the font map to TEXMFLOCAL/web2c/updmap.cfg (creating if necessary)
+* run once updmap-sys
+Advantages: Upgrades to new TeX Live versions will pick up the fonts
+automatically. No further manual intervention.
+Use case 2: multi user computer - add system wide fonts
+Typical case in a department/company with cooperate fonts that all
+users should have access to.
+Follow Use case 1.
+Use case 3: multi user computer - private user fonts
+This is the only case when user mode is required.
+* put fonts into TEXMFHOME (following TDS standard)
+* add the font map to TEXMFHOME/web2c/updmap.cfg (creating if necessary)
+* run updmap-user
+Important: changes in the font setup of the global installation
+will *not* be reflected unless updmap-user is run again.
+Please run updmap-user whenever you think there might be changes in
+the set of installed fonts.
+Use case 4: adding formats
+This is a very rare case, but basically follows the above layout.
+In particular most formats will not be private, so adding 
+	TEXMFLOCAL/web2c/fmtutil.cnf
+with only the new formats will suffice (above use case 1&2).
+Difference between the two modes
+There are two differences in operation:
+* location where files are generated:
+  user mode: TEXMFVAR
+  system mode: TEXMFSYSVAR
+* set of files being read
+  in user mode additional files are read, see updmap/fmtutil man pages
+  for details
+Since files in TEXMFVAR override the files in TEXMFSYSVAR, once files have
+been generated in TEXMFVAR (that is in the calling user's home directory)
+they will take precedence over files in TEXMFSYSVAR, which means that
+changes/updates in the system wide installation will *not* be available
+by the local user.
+Switching back to system mode
+Switching back to system mode involves removing files in
+TEXMFVAR, which normally is ~/.texliveYYYY/texmf-var
+For updmap the files in 
+	TEXMFVAR/fonts/map
+should be backuped and removed.
+For fmtutil the files in
+	TEXMFVAR/web2c
+should be backuped and removed.
+There *should*not* be any files that are not automatically generated, but
+make sure that no file you have put yourself there is removed.

More information about the tex-live-commits mailing list