add tlmgr user mode specification

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

1 files changed, 188 insertions, 0 deletions

diff --git a/Master/tlpkg/doc/tlmgr-usermode-specification.txt b/Master/tlpkg/doc/tlmgr-usermode-specification.txt
new file mode 100644
index 00000000000..7647bf50566
--- /dev/null
+++ b/Master/tlpkg/doc/tlmgr-usermode-specification.txt
@@ -0,0 +1,188 @@
+Using the TeX Live Manager in Usermode
+======================================
+(to be discussed and implemented)
+
+0. Contents
+-----------
+
+0. Contents
+1. Rational and definition
+2. General layout
+3. Description of actions
+4. Open questions
+5. Changes to the infrastructure
+
+---------------------------------------------------------------
+
+1. Rationale and definition
+---------------------------
+
+The idea behind developing a user mode for the TeX Live Manager is
+providing a tool to manage different texmf trees for users without
+write permissions to the system TeX Live installation on a multi user
+system.
+
+If a user without write permissions to the main installation
+tree is calling tlmgr, or it is called with --user (name to be decided)
+command line argument, then tlmgr will work in "usermode" and will behave
+as specified here.
+
+Already supported actions (where no write permissions are needed):
+	help, version, search, show, list, check, print-arch
+
+Actions that behave differently in usermode:
+	install, update, remove, option, paper, generate, backup, restore
+	uninstall, symlinks
+
+Actions that are not supported in usermode:
+	arch
+
+Actions I am not sure by now
+	gui
+
+------------------------------------------------------------
+
+2. General layout
+-----------------
+
+In usermode tlmgr manages a different texmf tree. By default it is TEXMFHOME
+but can be changed with --user-tree ... (name to be decided) (which implies
+automatically --user). The so managed texmf tree TREE contains a new toplevel
+directory 
+	TREE/tlpkg
+which in turns contains the tlpdb, and the sub directory tlpkg/tlpobj.
+
+The file
+	TREE/tlpkg/texlive.tlpdb
+contains only the packages that have been installed into the user tree TREE
+plus additional options in the virtual package 00texlive.installation
+(like with the main installation's texlive.tlpdb).
+
+Management in user mode is only possible for "relocatable" packages, that are
+packages that share the common prefix
+	$TeXLive::TLConfig::RelocPrefix
+which is set to
+	texmf-dist
+That means that only a package where all files are from the texmf-dist tree
+can be managed in usermode.
+
+These packages' containers are created relocatable, that is, the files in
+the tar file do not have the "texmf-dist" part included, thus can be
+unpacked directly into TEXMFHOME. In the tlpdb this fact is advertised
+in a TLPOBJ with the new field
+	relocated 1
+As an example:
+	name 12many
+	category Package
+	revision ...
+	relocated 1
+	shortdesc ...
+	...
+	docfiles size=98
+	 doc/latex/12many/12many.pdf
+	 doc/latex/12many/README
+	...
+	srcfiles size=6
+	 source/latex/12many/12many.dtx
+	 source/latex/12many/12many.ins
+	runfiles size=1
+	 tex/latex/12many/12many.sty
+	...
+
+The normal installation procedure of TeX Live (i.e., currently
+TLUtils::install_package) will take care that when unpacking these
+relocated containers the missing "texmf-dist" is added.
+
+-----------------------------------------------
+
+3. Description of actions
+-------------------------
+
+install:
+  in usermode the tlmgr action install will check that the package
+  and all depending packages are either all relocated, or those that
+  are not relocated are already installed in the system installation.
+  If this is true it will unpack all containers to be installed into
+  the user tree (TEXMFHOME or the value of --user-tree) and add the
+  respective packages to the user texlive.tlpdb (creating it if there
+  has non be created till now).
+
+  Open question: Should we support installation of dependencies at all
+  or should install only work on single package in user mode. If only
+  on single package, what to do with collections and other dependencies?
+  Maybe the user has to install all packages by hand?
+
+backup, restore, remove, update:
+  in usermode the tlmgr action update will check that all packages
+  to be updated are installed in the user tree, otherwise it behaves
+  exactely like the system tlmgr.
+ 
+option:
+  only acts upon the user's texlive.tlpdb
+
+paper:
+  changes configuration files in user tree
+
+generate:
+  creates configuration files in user tree
+
+uninstall:
+  will remove all packages from the user's texlive.tlpdb, and then
+  remove the tlpkg directory in the user tree
+
+symlinks:
+  takes the settings from the user's texlive.tlpdb, other then that
+  it behaves the same way
+
+gui:
+  the GUI should be adapted to do (at least):
+  - if in usermode show all packages with specification whether it is
+    from user tree or system tree
+  - show packags that have versions in the user tree and the system tree
+  - other actions work as described above
+
+arch:
+  is simply not supported because it needs access to the binary directories
+  which are not in the texmf-dist prefix, so no operation is allowed
+
+-----------------------------------------------------------------------
+
+4. Open questions
+-----------------
+
+a. Post install actions:
+   what should be done with post install actions:
+   - fileassoc -> ignore
+   - shortcuts -> make them only for the user?
+   - TLPackageConfigurations (should it go anyway) ?
+   - post install code scripts: we could pass the "user" argument
+     so scripts can react on that
+
+b. Behaviour if system tree has been updated and provides newer packages:
+   - warn the user
+   - automatically remove packages in the user tree that are older NO!!!
+
+c. Currently user mode is only when installing from CD/NET, but not
+   from svn/DVD. Should this be fixed?
+
+--------------------------------------------------------------------------
+
+5. Changes to the infrastructure (those already known)
+--------------------------------
+
+- texlive.tlpdb:
+  entries can now files without any leading texmf tree, but then the
+  package has to contain the "relocated 1" key/value pair
+- TLPOBJ.pm: accept new key "relocated"
+- tl-update-container: 
+  . add cmd line option for $opt_relative
+  . adjust the tlpobj if the container was build relocatable so that
+    texmf-dist prefix is removed from the files
+- TLUtils.pm
+  install_package(s): check for relocatable and adjust $target by
+    adding $RelocPrefix
+- tlmgr.pl
+  too many to actually list them
+
+---------------------------------------------------------------------------
+np, last changed 2009-05-02