1 files changed, 156 insertions, 1 deletions
diff --git a/Master/texmf/doc/man/man1/tlmgr.1 b/Master/texmf/doc/man/man1/tlmgr.1
index b6b0fba7059..a1118b5e79c 100644
--- a/Master/texmf/doc/man/man1/tlmgr.1
+++ b/Master/texmf/doc/man/man1/tlmgr.1
@@ -124,7 +124,7 @@
 .\" ========================================================================
 .\"
 .IX Title "TLMGR 1"
-.TH TLMGR 1 "2011-10-27" "perl v5.14.2" "User Contributed Perl Documentation"
+.TH TLMGR 1 "2012-04-17" "perl v5.14.2" "User Contributed Perl Documentation"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -592,6 +592,34 @@ updated, and will be mentioned as \fBforcibly removed\fR in the output of
 .IX Item "--dry-run"
 Nothing is actually removed; instead, the actions to be performed are
 written to the terminal.
+.SS "repositoy"
+.IX Subsection "repositoy"
+.IP "\fBrepository list\fR" 4
+.IX Item "repository list"
+.PD 0
+.IP "\fBrepository add \f(BIpath\fB [\f(BItag\fB]\fR" 4
+.IX Item "repository add path [tag]"
+.IP "\fBrepository remove \f(BIpath|tag\fB\fR" 4
+.IX Item "repository remove path|tag"
+.IP "\fBrepository set \f(BIpath\fB[#\f(BItag\fB] [\f(BIpath\fB[#\f(BItag\fB] ...]\fR" 4
+.IX Item "repository set path[#tag] [path[#tag] ...]"
+.PD
+This action manages the list of repositories. See \*(L"\s-1MULTIPLE\s0 \s-1REPOSITORIES\s0\*(R"
+below for detailed explanations.
+.Sp
+The first form list all configured repositories and the respective tags
+if set. The second form adds a repository (and optionally attaching a
+tag) to the list of repositories. The third from removes a repository,
+either by full path/url, or by tag. The last form sets the list
+of repositories to the items given on the command line, not keeping
+previous settings. Be reminded that one of the repositories has to
+be tagged as \fBmain\fR, otherwise all operations will fail.
+.SS "candidates"
+.IX Subsection "candidates"
+.IP "\fBcandidates \f(BIpkg\fB\fR" 4
+.IX Item "candidates pkg"
+Shows the list of available candidates for package \fIpkg\fR. See
+\&\*(L"\s-1MULTIPLE\s0 \s-1REPOSITORIES\s0\*(R" below for details.
 .SS "option"
 .IX Subsection "option"
 .IP "\fBoption [show]\fR" 4
@@ -1165,6 +1193,133 @@ respective command line options of the same name.
 \&\f(CW\*(C`gui\-expertmode\*(C'\fR switches between the full
 \&\s-1GUI\s0 and a simplified \s-1GUI\s0 with only the important and mostly used
 settings.
+.SH "MULTIPLE REPOSITORIES"
+.IX Header "MULTIPLE REPOSITORIES"
+Most packages are distributed via the main TeX Live repository, but
+sometimes local repositories are used to provide local packages
+(like commercial fonts, internal styles), as well as alternative
+package repositories for packages that cannot be included in
+proper TeX Live due to license or other reasons.
+.PP
+Without multiple repository support using these additional repositories
+needed an extra invocation and temporarily setting the installation
+source to this additional repository. By setting up all the
+repositories as sources of packages one does not need to
+use multiple invocations of tlmgr anymore.
+.PP
+\&\fBWarning:\fR Although support for multiple repositories has been
+tested extensively, it does not guarantee proper operation. If you
+want to be sure not to break anything, consider continuing
+using multiple invocations of tlmgr.
+.PP
+When using multiple repositories, one has to be the main repository,
+which distributes most of the TeX Live packages. If you convert
+from a single repository installation to a multiple repository
+installation (by calling tlmgr repository add), the previously
+set repository will be set as the main repository.
+.PP
+By default, even if multiple repositories are configured, packages
+are \fBonly\fR installed from the main repository, as long as
+packages are not explicitely pinned to a different repository.
+That also means by simply adding another repository you will
+\&\fBnot\fR be able to install the packages from there, you first
+have to specify which packages should be taken from a
+different repository by specifying some pinning rules.
+.SS "Pinning"
+.IX Subsection "Pinning"
+Pinning a package is done by editing (adding) a file
+.PP
+.Vb 1
+\&  TEXMFLOCAL/tlpkg/pinning.txt
+.Ve
+.PP
+which contains lines
+.PP
+.Vb 1
+\&  repo:pkg[,pkg]
+.Ve
+.PP
+In this line the \f(CW\*(C`repo\*(C'\fR is either the full \s-1URL\s0 saved in the
+list or repositories, or one of the tags given. The \f(CW\*(C`pkg\*(C'\fR
+are shell style globs for packages.
+.PP
+By default everything is pinned to the main repository, so
+you can imagine that at the end of the file pinning.txt there
+is a line
+.PP
+.Vb 1
+\&  main:*
+.Ve
+.PP
+If a package \f(CW\*(C`foo\*(C'\fR is pinned to a repository, any package
+\&\f(CW\*(C`foo\*(C'\fR in any other repository, even if it has a higher
+revision number, will not be considered as installable
+candidate.
+.SS "Usage example with tlcontrib"
+.IX Subsection "Usage example with tlcontrib"
+\&\- check current repository:
+.PP
+.Vb 3
+\& $ tlmgr repository list
+\& List of repositories (with tags if set):
+\&   /var/www/norbert/tlnet
+.Ve
+.PP
+\&\- add tlcontrib repository (and give it a short name)
+.PP
+.Vb 1
+\& $ tlmgr repository add http://tlcontrib.metatex.org/2011 tlcontrib
+.Ve
+.PP
+\&\- check repositories:
+.PP
+.Vb 4
+\& $ tlmgr repository list
+\& List of repositories (with tags if set):
+\&    http://tlcontrib.metatex.org/2011 (tlcontrib)
+\&    /var/www/norbert/tlnet (main)
+.Ve
+.PP
+\&\- add a pinning to get cowfont from tlcontrib:
+.PP
+.Vb 2
+\& $ mkdir \-p \`kpsewhich \-var\-value TEXMFLOCAL\`/tlpkg
+\& $ echo "tlcontrib:cowfont" > \`kpsewhich \-var\-value TEXMFLOCAL\`/tlpkg/pinning.txt
+.Ve
+.PP
+\&\- check that we can find cowfont:
+.PP
+.Vb 6
+\& $ tlmgr show cowfont
+\& tlmgr: using pinning file .../tlpkg/pinning.txt
+\& tlmgr: package repository /var/www/norbert/tlnet http://tlcontrib.metatex.org/2011
+\& package:     cowfont
+\& category:    Package
+\& ...
+.Ve
+.PP
+\&\- install cowfont and context (which is needed!)
+.PP
+.Vb 10
+\& $ tlmgr install context cowfont
+\& tlmgr: using pinning file .../tlpkg/pinning.txt
+\& tlmgr: package repository /var/www/norbert/tlnet http://tlcontrib.metatex.org/2011
+\& [1/11, ??:??/??:??] install: context.x86_64\-linux @main [84k]
+\& [2/11, 00:00/00:00] install: context @main [4274k]
+\& [3/11, 00:01/00:02] install: cowfont @tlcontrib [655k]
+\& [4/11, 00:05/00:09] install: metapost.x86_64\-linux @main [198k]
+\& [5/11, 00:05/00:09] install: metapost @main [72k]
+\& [6/11, 00:05/00:09] install: mptopdf.x86_64\-linux @main [1k]
+\& [7/11, 00:06/00:11] install: mptopdf @main [37k]
+\& [8/11, 00:06/00:11] install: stmaryrd @main [163k]
+\& [9/11, 00:07/00:12] install: xetex.x86_64\-linux @main [4442k]
+\& [10/11, 00:08/00:08] install: xetex @main [46k]
+\& [11/11, 00:08/00:08] install: xetexconfig @main [13k]
+\& ...
+.Ve
+.PP
+In the last part you see that the cowfont is installed from
+the tlcontrib part (@tlcontrib).
 .SH "TAXONOMIES"
 .IX Header "TAXONOMIES"
 tlmgr allows searching and listing of various categorizations, which we