summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context/manuals/reference/en/pr-texmfstart.tex
blob: 243353005c1e1a2a29d844f1236001e6ac6c52c8 (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
471
472
473
474
475
476
477
478
479

\startcomponent pr-texmfstart

\environment contextref-env
\product contextref

\chapter[texmfstart]{texmfstart manual}

\subject{Introduction}

This manual is about a small (\RUBY) script that can be used to run
a script or open a document which is located somewhere in the \type
{texmf} tree. This scripts evolved out of earlier experiments and
is related to scripts and programs like \type {runperl}, \type
{runruby} and \type {irun}.

One of the main reasons for \type {texmfstart} to exist is that it
enables us to be downward compatible when using a \TEX\ based
environment. \TEX\ itself is pretty stable, but this is not true
for the whole collection of files that comes with a distribution
and the way they are organized. We will see some other reasons for
using this script as well.

We can also use this script for lanching applications that need access
to resources in the \TEX\ tree but that lack the features to locate
them.

The script has a few dependencies on libraries. This means that
relocating the script to a bin path may give problems. One can
make a self||contained version by saying:

\starttyping
texmfstart --selfmerge
\stoptyping

One can undo this with the \type {--selfclean} option. Normally
users don't have to worry about this because in the \CONTEXT\
distribution the merged version is shipped. A \MSWINDOWS\ (pseudo)
binary can be made with \type {exerb} or one can simply associate
the \type {.rb} suffix with the \RUBY\ program.

\starttyping
FTYPE RubyScript=c:\data\system\ruby\bin\ruby.exe %%1 %%*

ASSOC .rb=RubyScript
ASSOC .rbw=RubyScript
\stoptyping

On \UNIX\ one can make a copy without suffix:

\starttyping
cp texmfstart.rb /path/to/bin/texmfstart
chmod +x texmfstart
\stoptyping

Alternative approaches have been discussed on the \CONTEXT\ and
\TEX Live mailing lists and can be found in their archives.

\subject{Launching programs}

The primary usage of \type {texmfstart} is to launch programs and
scripts. We can start the \type{texexec} \PERL\ script with:

\starttyping
texmfstart texexec.pl --pdf somefile
\stoptyping

We can also start the \type{pstopdf} \RUBY\ script:

\starttyping
texmfstart pstopdf.rb --method=3 cow.eps
\stoptyping

However, we can omit the suffix:

\starttyping
texmfstart texexec --pdf somefile
texmfstart pstopdf --method=3 cow.eps
\stoptyping

The suffixless method is slower unless the scripts are known.  For
familiar \CONTEXT\ scripts it's best not to use the suffix since
this permits us to change the scripting language. \CONTEXT\ related
scripts are known. Because in the meantime \type {texexec} has become a
\RUBY\ script, users who use the suffixless method automatically will
get the right version.

You can also say:

\starttyping
texmfstart --file=pstopdf --method=3 cow.eps
\stoptyping

When locating a file to run, several methods are applied, one being
\type {kpsewhich}. You can control the path searching by providing a
program space, which by default happens to be \type {context}.

\starttyping
texmfstart --program=context --file=pstopdf --method=3 cow.eps
\stoptyping

The general pattern is:

\starttyping
texmfstart switches filename arguments
\stoptyping

Here \type {switches} control \type {texmfstart}'s behaviour, and
\type {arguments} are passed to the program identified by \type
{filename}.

Sometimes the operating system will spoil our little game of passing
arguments. In the following case we want the output of \type
{texexec} to be written to a log file. By using quotes, we can pass the
redirection without problems.

\starttyping
texmfstart texexec "somefile.tex > whatever.log"
\stoptyping

\subject{Generating stubs}

One of the reasons for writing \type {texmfstart} is that it permits
us to write upward compatible scripts (batch files), so instead of

\starttyping
texexec --pdf somefile
texexec --pdf anotherfile
\stoptyping

We prefer to use:

\starttyping
texmfstart texexec --pdf somefile
texmfstart texexec --pdf anotherfile
\stoptyping

Instead of using \type {texmfstart} directly you can also use it in a
stub file. For \MSWINDOWS\ such a file looks like:

\starttyping
@echo off
texmfstart texexec %*
\stoptyping

In this case, the file itself is named \type {texexec.cmd}. Now, given that
no new functionality of \type {texmfstart} itself is needed, one will
automatically use the version of \type {texexec} that is present in the
(latest) installed \CONTEXT\ tree.

It is possible to generate stubs automatically. You can provide a path
where the stub will be written. This permits tricks like the following.
Say that on a \CDROM\ we have the following structure:

\starttyping
tex/texmf-mswin/bin/texexec.bat
tex/texmf-linux/bin/texexec
tex/texmf-local/scripts/context/ruby/texexec.rb
\stoptyping

If we are on the main \type {tex} path, we can run \type
{texmfstart} as follows:

\starttyping
texmfstart --make --windows --stubpath=tex/texmf-mswin/bin \
    ../../texmf-local/scripts/context/ruby/texexec.rb
texmfstart --make --unix    --stubpath=tex/texmf-linux/bin \
    ../../texmf-local/scripts/context/ruby/texexec.rb
\stoptyping

This will generate start up scripts that point directly to the \PERL\
script. Such a link may fail when files get relocated. In that case
you can use the \type {--indirect} directive, which will force the
\type {texmfstart} into the stub file.

\starttyping
texmfstart --make --windows --indirect --stubpath=tex/texmf-mswin/bin \
    ../../texmf-local/scripts/context/ruby/texexec.rb
texmfstart --make --unix    --indirect --stubpath=tex/texmf-linux/bin \
    ../../texmf-local/scripts/context/ruby/texexec.rb
\stoptyping

However, the prefered way and most simple way to generate the stubs
for the scripts that come with \CONTEXT\ is:

\starttyping
texmfstart --make all
\stoptyping

This will generate stubs suitable for the current operating system in
the current path.

\subject{Documents}

You can use \type {texmfstart} to open a document.

\starttyping
texmfstart showcase.pdf
\stoptyping

This will open the document \type {showcase.pdf}, when found. The
chance is minimal that such a document can be located by
\type {kpsewhich}. In that case, \type {texmfstart} will search the
tree itself.

Given that it is supported on your platform, you can also open a
\PDF\ file on a given page.

\starttyping
texmfstart --page=2 showcase.pdf
\stoptyping

On \MSWINDOWS\ the following command will open the \PDF\ file in a
web browser. This is needed when you want support for form
submission.

\starttyping
texmfstart --browser examplap.pdf
\stoptyping

\subject{Search strategy}

In a first attempt, \type {kpsewhich} will be used to locate a file.
When \type {kpsewhich} cannot locate the file, the following
environment variables will be used:

\starttabulate[|T||]
\NC RUBYINPUTS   \NC ruby   scripts   with suffix \type {rb}  \NC \NR
\NC PERLINPUTS   \NC perl   scripts   with suffix \type {pl}  \NC \NR
\NC PYTHONINPUTS \NC python scripts   with suffix \type {py}  \NC \NR
\NC JAVAINPUTS   \NC java   archives  with suffix \type {jar} \NC \NR
\NC PDFINPUTS    \NC pdf    documents with suffix \type {pdf} \NC \NR
\stoptabulate

It using them fails as well, the whole tree is searched, which will take
some time.

When a file found, its location is remembered and passed on to nested
runs. So, in general, a nested run will start faster.

\subject{Directives}

The script accepts a few directives. Some are rather general:

\starttabulate[|T||]
\NC --verbose   \NC report some status and progress information             \NC \NR
\NC --arguments \NC an alternative for providing the arguments to be passed \NC \NR
\NC --clear     \NC don't pass info about locations to child processes      \NC \NR
\stoptabulate

Directives that concern starting an application are:

\starttabulate[|T||]
\NC --program=str \NC the program space where \type {kpsewhich} will search \NC \NR
\NC --locate      \NC report the call as it should happen (no newline)      \NC \NR
\NC --report      \NC report the call as it should happen (simulated)       \NC \NR
\NC --browser     \NC start the document in a web browser                   \NC \NR
\NC --file        \NC an alternative for providing the file                 \NC \NR
\NC --direct      \NC run a program without searching for it's location     \NC \NR
\NC --execute     \NC use \RUBY's 'exec' instead of 'system'                \NC \NR
\NC --batch       \NC {\em not yet implemented}                             \NC \NR
\stoptabulate

You can create startup scripts by providing one of the following
switches in combination with a filename.

\starttabulate[|T||]
\NC --make     \NC create a start script or batch file for the given program \NC \NR
\NC --windows  \NC when making a startup file, create a windows batch file   \NC \NR
\NC --linux    \NC when making a startup file, create a unix script          \NC \NR
\NC --stubpath \NC destination of the startup file                           \NC \NR
\NC --indirect \NC always use \type {texmfstart} in a stub file              \NC \NR
\stoptabulate

Some directives can be accompanied by specifications, like:

\starttabulate[|T||]
\NC --page=n          \NC open the document at this page                 \NC \NR
\NC --path=str        \NC change from the current path to the given path \NC \NR
\NC --before=str      \NC {\em not yet implemented}                      \NC \NR
\NC --after=str       \NC {\em not yet implemented}                      \NC \NR
\NC --tree=str        \NC use the given \TEX\ tree                       \NC \NR
\NC --autotree        \NC automatically determine the \TEX\ tree to use  \NC \NR
\NC --environment=str \NC use the given tmf environment file             \NC \NR
\stoptabulate

Conditional directives are:

\starttabulate[|T||]
\NC --iftouched=str,str \NC only run when the given files have different time stamps \NC \NR
\NC --ifchanged=str     \NC only run when the given file has changed (md5 check)     \NC \NR
\stoptabulate

Special features:

\starttabulate[|T||]
\NC --showenv \NC show the environment variables known at runtime \NC \NR
%NC --serve   \NC act as a kpse server (distributed \RUBY)        \NC \NR
\NC --edit    \NC open the given file in an editor                \NC \NR
\stoptabulate

In addition, there are prefixes for filenames:

\starttabulate[|T||]
\NC bin:filename  \NC expanded name, based on \type {PATH} environment variable        \NC \NR
\NC kpse:filename \NC expanded name, based on \type {kpsewhich} result                 \NC \NR
\NC rel:filename  \NC expanded name, backtracking on current path (\type {. .. ../..}) \NC \NR
\NC env:name      \NC expanded name, based on environment variable \type {name}        \NC \NR
\NC path:filename \NC pathpart of \type {filename} as located by \type {kpsewhich}     \NC \NR
\stoptabulate

\subject {Performance}

The performance of the indirect call is of course less than a direct
call. You can gain some time by setting the environment variables or
by using a small \TEX\ tree.

The script tries to be clever. First it tries to honor a given path,
and if that fails it will strip the path part and look on the
current path. When this fails, it will consult the environment
variables. Then it will use \type {kpsewhich} and when that fails as
well, it will start searching the \TEX\ trees. This may take a
while, especially when you have a complete tree, like the one on
\TEX\ Live. \footnote {On my computer I use multiple trees parallel
to the latest \TEX\ Live tree. This results in a not that
intuitively and predictable search process. The cover of this manual
reflects state of those trees.}

If you want, you can use the built in \type {kpsewhich} functionality
(written in \RUBY) by setting the environment variable \type {KPSEFAST}
to \type {yes}. The built in handler is a bit faster and maintains its own
file database. Such a database is generated with:

\starttyping
tmftools --reload
\stoptyping

\subject {Using prefixes}

You can also use \type {texmfstart} to launch other programs that
need files in one of the \TEX\ trees:

\starttyping
texmfstart --direct xsltproc kpse:somescript.xsl somefile.xml
\stoptyping

or shorter:

\starttyping
texmfstart bin:xsltproc kpse:somescript.xsl somefile.xml
\stoptyping

In both cases \type {somescript.xsl} will be resolved and in the
second case \type {bin:} will be stripped. The \type {--direct}
switch and \type {bin:} prefix tell \type {texmfstart} not to search
for the program, but to assume that it is a binary. The \type
{kpse:} prefix also works for previously mentioned usage.

A convenient way to edit your local context system setup file is the
following; we don't need to go to the path where the file resides.

\starttyping
texmfstart bin:scite kpse:cont-sys.tex
\stoptyping

Because editing is happening a lot, you can also say:

\starttyping
texmfstart --edit kpse:cont-sys.tex
\stoptyping

You can set the environment variable \type {TEXMFSTART_EDITOR} to
your favourite editor.

\subject{Conditional processing}

A bit obscure feature is triggered with \type {--iftouched}, for
instance:

\starttyping
texmfstart --iftouched=normal.pdf,lowres.pdf \
    downsample.rb --verylow normal.pdf lowres.pdf
\stoptyping

Here, \type {downsample.rb} is only executed when \type {normal.pdf} and
\type {lowres.pdf} have a different modification time. After execution,
the times are synchronized. This feature is rather handy when you want
to minimize runtime. We use it in the resource library tools.

\starttyping
texmfstart --iftouched=foo.bar,bar.foo convert_foo_to_bar.rb
\stoptyping

A similar option is \type {ifchanged}:

\starttyping
texmfstart --ifchanged=whatever.mp texexec --mpgraphic whatever.mp
\stoptyping

This time we look at the MD5 checksum, when the sum is changed, \type
{texexec} will be run, otherwise we continue.

\subject {\TEX\ trees}

There are a few more handy features built in. The reason for putting those
into this launching program is that the sooner they are executed, the less
runtime is needed later in the process.

Imagine that you have installed your tree on a network attached storage
device. In that case you can say:

\starttyping
texmfstart --tree=//nas-1/tex texexec --pdf yourfile
\stoptyping

There should be a file \type {setuptex.tmf} in the root of the tree. An
example of such a file is part of the \CONTEXT\ distribution (minimal
trees). This feature permits you to have several trees alongside and run
specific ones. You can also specify additional environments, using \type
{--environment}.

Such an environment file is platform independent and looks as follows. The
\type {%VAR%} variables will be replaced by their meaning, while the \type
{$VAR} variables are left untouched. The \type {=} sets a value, while
\type {>} and \type {<} prepend and append the given value to the current
value.

\starttyping
# author: Hans Hagen - PRAGMA ADE - Hasselt NL - www.pragma-ade.com
#
# usage: texmfstart --tree=f:/minimal/tex ...
#
# this assumes that calling script sets TEXPATH without a trailing
# slash; %VARNAME% expands to the environment variable, $VARNAME
# is left untouched; we also assume that TEXOS is set.

TEXMFMAIN    = %TEXPATH%/texmf
TEXMFLOCAL   = %TEXPATH%/texmf-local
TEXMFFONTS   = %TEXPATH%/texmf-fonts
TEXMFEXTRA   = %TEXPATH%/texmf-extra
TEXMFPROJECT = %TEXPATH%/texmf-project
VARTEXMF     = %TMP%/texmf-var
HOMETEXMF    =

TEXMFOS      = %TEXPATH%/%TEXOS%
# OSFONTDIR  = %SYSTEMROOT%/fonts

TEXMFCNF     = %TEXPATH%/texmf{-local,}/web2c
TEXMF        = {$TEXMFOS,$TEXMFPROJECT,$TEXMFFONTS,
                    $TEXMFLOCAL,$TEXMFEXTRA,!!$TEXMFMAIN}
TEXMFDBS     = $TEXMF

TEXFORMATS   = %TEXMFOS%/web2c/{$engine,}
MPMEMS       = %TEXFORMATS%
TEXPOOL      = %TEXFORMATS%
MPPOOL       = %TEXPOOL%

PATH         > %TEXMFOS%/bin
PATH         > %TEXMFLOCAL%/scripts/perl/context
PATH         > %TEXMFLOCAL%/scripts/ruby/context

RUBYLIB      > %TEXMFLOCAL%/scripts/ruby/context

TEXINPUTS    =
MPINPUTS     =
MFINPUTS     =
\stoptyping

When you only want to set a variable that has no value yet, you can use an \type
{?}. These symbols have alternatives as well:

\starttabulate[|T|T|l|]
\NC = \NC << \NC  assign a value to the variable \NC \NR
\NC ? \NC ?? \NC  only assign a valuehen the variable is unset \NC \NR
\NC < \NC += \NC  append a value to the current value of the variable \NC \NR
\NC > \NC =+ \NC  prepend a value to the current value of the variable \NC \NR
\stoptabulate

\stopcomponent