path: root/Master/setup-win32/tlpm.readme

# This file belongs to TLPM v2.10, TeX Live Package Manager for Windows. 
# Public Domain, P.Jackowski@gust.org.pl                              
                                                                      
TECHNICAL NOTES:
TLPM works with TeX Live 2004-2005. It does NOT support upgrades or downgrades.
All the configuration is beyond the scope of TLPM functionality. It does not
perform any post-installation actions such as setting of environment variables,
building formats or updating fontmap files. Please read the 'tlpm.winconf' file
to learn how to configure the system manually.

TLPM is Windows related. It simply ignores (binary) packages for other
platforms since there are custom installers available.

TLPM tries to detect the CD/DVD drive automatically unless you use the 
'--source' command-line option or the 'tl_source' environment variable 
(which might be useful while installing from local hard drive resources). 
The target directory can be specified with the '--directory' command-line 
option or the 'tl_target' environment variable. If both are missing, you 
will be prompted for the target directory during runtime (interactive mode) 
or it will be initialized to current directory (batch mode).

TLPM can be run in batch mode. In such a case, each not empty line of the batch
file is treated as a command, unless it starts with the '%' or '#' characters.
The range of commands and options available in batch mode is the same as in
interactive mode.

TLPM respects quotations (both double quotes and single quotes) used in command
line. Quotation is necessary while using path names with spaces (strongly not
recommended!) or other strange characters that may conflict with the command
syntax. If so, please quote the entire phrase. Whenever analysing the command,
TLPM also resolves environment variables expressed as '%variable%'.

TLPM is fully based on the information retrieved from the TPM files (actually
from text files stored in the 'texmf/lists' directory). If you do not trust
TPMs, do NOT trust TLPM either!

The history of installed and uninstalled packages is saved in the tlpm.log file
stored in the TeX Live target directory. TLPM does not reuse this file and
reads the current installation state in each run.

TLPM is a temporary rather than a final solution. However, I hope that it is
better than nothing. I have done my best to make it functional and reliable,
but can NOT warrant anything. If you like TLPM, feel free to redistribute it
without any restrictions. TLPM is in Public Domain.

Big THANK YOU to Jolanta Szelatyñska, Staszek Wawrykiewicz, Tomek £uczak, Jacek
Kmiecik, Jerzy Ludwichowski and all other nice souls for all their help!

Please reports bugs to P.Jackowski.org.pl

HISTORY:
23.02.2005, 1.00 -- first beta release
06.04.2005, 1.01 -- bugfix; 'inst' function couldn't be executed twice
                    because of incorrect error code returned
06.05.2005, 1.02 -- bugfix; some of messages redirected to files were stored in
                    texmf/lists instead of the runtime directory
15.09.2005, 1.03 -- TLPM seems to work fine with TL2005; changed messages.
30.09.2005, 1.04 -- tiny changes in CD detection routine
05.10.2005, 2.00 -- general rework; mostly in messaging system and installation;
                    now TLPM supports also TeX Live DVD (slooow...)
06.10.2005, 2.01 -- again, changes in CD/DVD detction routine because of removing
                    tlpm(gui) stuff from TL root directory
08.10.2005, 2.02 -- bugfix; while removing standalone packages, uninstall
                    routine was performed twice
10.10.2005, 2.03 -- bugfix; now paths are internally separated by `\' ($chr_dirsep)
                    because of win98 archeology
11.10.2005, 2.04 -- debug version made to fix hanging under win98
12.10.2005, 2.05 -- yet another temporary debug version
13.10.2005, 2.06 -- experimental progress info while installing from DVD
14.10.2005, 2.07 -- progress info while installing from CD and DVD
                    and --quiet option for 'inst' command
25.10.2005, 2.08 -- give up to with hanging on DVD instalation under Win98;
                    just note added
26.10.2005, 2.09 -- yet another slight correction
27.10.2005, 2.10 -- Karl confirmed that 'texlive2005' directory
                    need no longer to be checked

KNOWN ISSUES:
1. Installation from DVD is much slower than from CD. Sorry...
2. When there are two CD drives (ie. 'E:\' and 'F:\') and TeX Live disk is in
the second one, Windows may throw 'Insert CD to E:\' message and block the
program. Can't help that... Put the CD into 'F:\' instead, use '--source'
option or 'tl_source' environment variable.
3. While sending the command output to pipe (ie. 'list | grep' or 'incl | more')
by design no summary is displayed. Summary might be irrelevant after processing
with grep or something.
4. While running via tlpmgui with DVD, installation (xcopy) hangs on Win98. Any ideas?


################################################################################
                              COMMANDS IN DETAILS
################################################################################

##################################### tlpm #####################################
USAGE:
tlpm [-s <source>] [-d <target>] [-b <batch>]

DESCRIPTION:
TLPM help searching for, installing and uninstalling TeX Live packages. It
should be used in conjunction with the TeX Live 2004-2005 CD/DVD.

COMMANDS:
list              list packages or files with names matching the given phrase
incl              list packages or files included in the given bundle
blng              show to which bundle the given package or file belongs
inst              install a package in specified target (TeX root) directory
uninst            uninstall a package from specified target directory
check             check installation dependencies and consistency
info              show package info
help              show this help or the given command description
cmd               execute a system command
quit              leave the program

Type 'help <command>' for details.

OPTIONS:
-s --source       set default TeX Live source path
-d --directory    set default TeX Live target path
-b --batch        enter batch mode
-h --help         display this help and quit
-H --Help         display the entire readme and quit
-v --version      display the version info and quit

EXAMPLES:
% start in interactive mode
tlpm

% start in batch mode reading commands from 'file.lst'
tlpm -b file.lst

% set TeX Live target directory (do not prompt during runtime)
tlpm -d D:\TeX

% set TeX Live source and target
tlpm -s E:\ -d D:\Tex

% execute just one TLPM <command> and quit
echo <command> | tlpm



##################################### list #####################################
USAGE:
list [-pfe] [<phrase>] [-d <dir>]

DESCRIPTION:
Lists files or packages from TeX Live CD/DVD or installation directory.

OPTIONS:
-p --packages     search for packages matching <phrase> (default)
-f --files        search for files matching <phrase>
-e --expression   treat <phrase> as a Perl regular expression (regex)
-d --directory    list packages or files installed in the <dir> directory

EXAMPLES:
% display a list of all packages available on TeX Live CD/DVD
list

% the same via a pager
list -p * | more

% output all PFB file names on the CD/DVD into font.log
list -f *.pfb >font.log

% the same, but matching regex instead of a mask
list -fe ^.*\.pfb>font.log

% list package collections installed in D:\TeX
list coll* -d D:\TeX

% the same, assuming that the target directory has already been specified
list coll* -d

% yet one more alternative via grep
list -d | grep coll



##################################### incl #####################################
USAGE:
incl <package> [-pferj] [<phrase>]

DESCRIPTION:
Displays a list of <package> requirements and contents.

OPTIONS:
-p --packages     show required packages matching <phrase> (default)
-f --files        show included files matching <phrase>
-e --expression   treat <phrase> as a Perl regex
-r --recurse      follow dependencies recursively (default)
-j --justone      do not recurse

EXAMPLES:
% display all packages required by collection-basic (via pager)
incl collection-basic | more

% display packages directly required by the collection-basic
incl collection-basic -j

% write all TFM files included in the collection-basic to tfms.lst
incl collection-basic -f *.tfm > tfms.lst

% display a list of collections included in the GUST scheme
incl scheme-gust.scheme -p coll



##################################### blng #####################################
USAGE:
blng [-pf] <name>

DESCRIPTION:
Shows parent bundle(s) of a package or file given by <name> (not <phrase>).

OPTIONS:
-p --package      treat <name> as a package (default)
-f --file         treat <name> as a file

EXAMPLES:
% show bundles that include collection-context
blng collection-context

% show the package that contains the 'manfnt.tfm' file
blng -f manfnt.tfm



##################################### inst #####################################
USAGE:
inst <package> [-rjou] [-d <dir>]

DESCRIPTION:
Install <package> in the specified target directory.
By default, already installed packages are skipped.

OPTIONS:
-r --recurse      follow dependencies recursively (default)
-j --justone      do not recurse
-o --overwrite    reinstall existing packages
-u --update       refresh older, create missing files (implies --overwrite)
-d --directory    install the packages in <dir> directory
-q --quiet        disable progress info

EXAMPLES:
% install entire collection-basic in D:\TeX
inst collection-basic -d D:\TeX

% reinstall collection-basic and prompt for the target directory (if not given already)
inst collection-basic -o

% just update the ComputerModern fonts package
inst cm -ju



#################################### uninst ####################################
USAGE:
uninst <package> [-rjiI] [-d <dir>]

DESCRIPTION:
Uninstalls <package> from the specified target directory.

OPTIONS:
-r --recurse      follow dependencies recursively (default)
-j --justone      do not recurse
-i --ignore       ignore dependencies
-I --Ignore       ignore dependencies indeed
-d --directory    uninstall packages from <dir> directory

EXAMPLES:
% remove the LaTeX collection with all components, unless required by other packages
uninst collection-latex

% force removal of the LaTeX collection but leave shared packages untouched
uninst collection-latex -i

% force removal of the LaTeX collection and all its components, even if shared (dangerous)
uninst collection-latex -I

% remove just the 'ltxmisc' package from D:\TeX
uninst ltxmisc -j -d D:\TeX



#################################### check ####################################
USAGE:
check [-pf][-d <dir>]

DESCRIPTION:
Check installation dependencies and consistency.

OPTIONS:
-p --packages     check packages (default)
-f --files        check files
-d --directory    check given <dir> directory

EXAMPLES:
% display packages missing from D:\TeX
check -d D:\TeX

% almost the same (prompt for directory, if not specified already)
check

% display files that should exist but can not be found
check -f



##################################### help #####################################
USAGE:
help [<command>]

DESCRIPTION:
Displays general help or usage details for a given command.

OPTIONS:
-H --Help         display the entire readme

EXAMPLES:
% display general help (via pager)
help | more

% tell me more about the 'inst' command
help inst

% exactly the same
inst --help



##################################### info #####################################
USAGE:
info <package>

DESCRIPTION:
Displays the information available for a given package.

EXAMPLES:
% tell me something about ConTeXt
info context



##################################### cmd #####################################
USAGE:
cmd <command>

DESCRIPTION:
Executes a system command without exiting the TLPM session.

EXAMPLES:
% test TeX
cmd tex \input story \end

% clear screen
cmd cls



##################################### quit #####################################
USAGE:
quit

DESCRIPTION:
Leaves the program.

EXAMPLES:
% say goodbye
quit