summaryrefslogtreecommitdiff
path: root/Master/setuptl/TLPM/help.pm
blob: 48a97364ab2665e1beb256438c3378a1e6def4cf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
# 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;