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

# This file belongs to TLPM v2.20, 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, 2005, 2006/07 
editions. Initially, TLPM was just my private Perl script 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.

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 actions are 
accomplished by a pretty nice TLPMGUI front-end written by Tomek \\{}Luczak.

Since there is no (not yet) consistent versioning system within TeX Live 
distribution, TLPM does NOT support upgrades or downgrades, neither of 
packages, nor of the entire distribution. 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!

* Usage
TLPM tries to detect the CD/DVD drive with TeX Live disk automagically (this 
heuristic is performed not performed on Unix shells). 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 TeX Live 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 analyzing the command,
TLPM also resolves environment variables expressed as '%variable%' or '\$variable'.

To ensure possibly similar behaviour for different platforms, TLPM interprets 
all the command line (including '>file' and '|stream' redirection) on its 
own. Hence, some shell specific expansion may not work as normally expected.

* 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 detection 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 installation 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 -- added 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
07.01.2007, 2.15 -- help update for TeX Live 2006/07 edition
08.01.2007, 2.16 -- bugfix; typing 'version' command was causing a program crash;
                    there is no such a command available anymore; program version
                    is displayed in the banner and command prompt
09.01.2007, 2.17 -- code comments, readme changes
12.01.2007, 2.18 -- since 'cmd set...' does not work as expected (the variable is 
                    not kept in the environment during TLPM session), we introduce 
                    new 'set' command
12.01.2007, 2.19 -- protection from defining variables of empty name
21.01.2007, 2.20 -- modified source detection heuristic; .mkisofsrc file is no longer
                    checked, since as hidden, it can be easily missed while copying;
                    debug messages added for detection; release date added to 
                    welcome message

* 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 -> versioning system -> upgrading -> via net installation
1. Shell-specific cmd-line expansion (probably I'll give up cmdline parsing on my own)
2. More robust and platform independent copying mechanism (especially important for DVD)",

'tlpm' =>
"USAGE:
tlpm [platforms] [-s \<source\>] [-d \<target\>] [-b \<batch\>]

DESCRIPTION:
TLPM help searching for, installing and uninstalling TeX Live packages.

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
set               set environment variable for current TLPM session
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",

'set' =>
"USAGE:
set \<key-val list\>

DESCRIPTION:
(Re)Sets environment variable for the current TLPM session.

EXAMPLES:
set TEXMFCNF=D:/TeX/texmf/web2c LOFO=.;lofo//"
);

sub readme
{
      my $z;
      my $sep = '#';
      my @topics = qw( technical_notes tlpm list incl blng inst uninst check help info set 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;