path: root/Master/setuptl/TLPM/help.pm

# This file belongs to TLPM v2.14, TeX Live Package Manager
# Public Domain, P.Jackowski@gust.org.pl

# help

sub help
{
      my $arg = shift;
      $arg eq ''                  and return $heeelp -> ('tlpm')
      or &no_opt($arg)            and return $heeelp -> ($arg)
      or &is_opt($arg,'h','help') and return $heeelp -> ('help')
      or &is_opt($arg,'H','Help','readme') and return &readme()
      or &rem_opt($arg)           and return $error{'wrong_opt'} -> ($arg,'help --help')
}

$heeelp = sub
{
      my $topic = shift;
      if(defined $help{$topic})
      {
            $mess -> ($help{$topic} . "\n\n");
            return(1);
      }
      else
      {
            return $error{'wrong_cmd'} -> ($topic,'help');
      }
};

%help =
(
'tlpm_banner' => "This is TeX Live Package Manager, v$tlpm_version
Public Domain, P.Jackowski\@gust.org.pl",

'type_help'   => "Type 'help' or other command.",

'technical_notes' => "TECHNICAL NOTES:

* About TLPM
TLPM (TeX Live Package Manager) helps to search, trace dependencies, and install 
TeX Live packages. It works with TeX Live 2004-2006. Initially, TLPM was a Perl script 
just for controlling the mass of TeX Live packages repository. Since there were no 
win-installer on TeX Live 2004, TLPM became a rescue solution. Starting from version 2.11, 
TLPM works, with some restrictions, under Unix shells as well.

Since there is no consistent versioning system withing TeX Live distribution, TLPM does 
NOT support upgrades or downgrades. TLPM fully relies on the information retrieved from 
the TPM files (actually from text files stored in the 'texmf/lists' directory). If you don't 
trust TPMs, do NOT trust TLPM either!

All the configuration is beyond the scope of TLPM functionality. TLPM doesn't perform 
any post-installation actions such as setting of environment variables, building formats 
or updating fontmap files. All those tasks are made by TLPMGUI program written 
by Tomek \\{}Luczak.

* Usage
TLPM tries to detect the CD/DVD drive with TeX Live disk automagically. If the magic 
fails, TLPM prompts to provide a mounting point, unless one 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 installation directory can be specified with the '--directory' command-line
option or the 'tl_target' environment variable. If both are missing, one is prompted 
for the target directory during runtime (interactive mode) or it is initialized 
to current directory (batch mode).

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

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 from disk in each run.

TLPM is self documented -- 'help [<command>]' informs about usage details.

* Command line
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%' or '\$variable'.
Shell specific expansions are not performed.

* License
I have done my best to make TLPM 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.

* Thanks
Big THANK YOU to Jolanta Szelaty\\n{}ska, Staszek Wawrykiewicz, Tomek \\L{}uczak,
Jerzy Ludwichowski and all other nice souls for all their help.

* Bugs
Bugs reports and comments are welcome (tlpmgui\@gust.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
19.03.2006, 2.11 -- some experimental rework; allows to extract binaries for other 
                    platforms, can work under Linux, prompts for source drive
                    or mounting point unless found automatically
23.04.2006, 2.12 -- addedd installation from DVD support for Linux; still slow,
                    as in Windows
08.05.2006, 2.13 -- bugfix; changes 2.12 spoil installation from cd
04.06.2006, 2.14 -- code commented

* Known issues
1. Installation from DVD is much slower than from CD. Sorry...
2. Under Windows; if there are two CD drives (ie. 'E:\\' and 'F:\\') and TeX Live
disk is in the second one, system 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. The summary might be irrelevant if affected 
by grep or something.
4. While running via tlpmgui with DVD, installation (xcopy) hangs on Win98. Any ideas?
5. While installing from DVD, strange message 'Cannot perform INPAGE operation'. 
Hardly reproducable...

* Hope for the future
0. New TL package model
1. Shell-specific cmd-line expansion (?)
2. More robust and platform independent copying mechanism (DVD)",

'tlpm' =>
"USAGE:
tlpm [platforms] [-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 directory (just extract)
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 /usr/share/TeX
tlpm -d D:\\TeX

% set TeX Live source and target (current directory)
tlpm -s /mnt/cd -d .
tlpm -s E:\\ -d .

% respect binary packages for listed platforms (depends on TeX Live naming convention)
tlpm win32 i386-linux -s /mnt/cd
tlpm win32 i386-linux -s E:\\

% 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 \<dir\>
list coll* -d /usr/share/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 \<dir\>
inst collection-basic -d /usr/share/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 \<dir\>
uninst ltxmisc -j -d /ust/share/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 \<dir\>
check -d /usr/share/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",

'quit' =>
"USAGE:
quit

DESCRIPTION:
Leaves the program.

EXAMPLES:
% say goodbye
quit",

'cmd' =>
"USAGE:
cmd \<command\>

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

EXAMPLES:
% mount TeX Live source
cmd mount /dev/cd /mnt/cd

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

% clear screen
cmd clear"
);

sub readme
{
      my $z;
      my $sep = '#';
      my @topics = qw( technical_notes tlpm list incl blng inst uninst check help info cmd quit);
      $heeelp -> (shift @topics);
      $mess -> ("\n" . $sep x $row_length . "\n" . ' ' x 30 .  "COMMANDS IN DETAILS\n" . $sep x $row_length );
      foreach(@topics)
      {
            $z = $row_length - length($_) - 2;
            ($z % 2 == 1 ? $z = ($z-1)/2 : $z = $z/2);
            $mess -> ("\n\n" . $sep x $z . ' ' . $_ . ' ' . $sep x $z . "\n");
            $heeelp -> ($_);
      }
      $mess -> ("\n");
      return(1);
}

1;