add start on sys-user documentation

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

1 files changed, 108 insertions, 0 deletions

diff --git a/Master/tlpkg/doc/sys-user.txt b/Master/tlpkg/doc/sys-user.txt
new file mode 100644
index 00000000000..26e8e2255a0
--- /dev/null
+++ b/Master/tlpkg/doc/sys-user.txt
@@ -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 
+practices:
+
+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.
+