summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man/man1/texmfstart.1
blob: e99ab230bd1dce6de207180865b564d5dcb9abdf (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
.TH "TEXMFSTART" "1" "December 2006" "texmfstart 2.0" "ConTeXt" 
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.de EX
.in +3
.nf
.ft CW
..
.de EE
.in -3
.ft R
.fi
..

.SH "NAME" 
texmfstart \- run ConTeXt scripts, make ConTeXt wrapper scripts, view documents

.SH "SYNOPSIS" 
\fB texmfstart\fP [ \fIoptions ...\fP ] [ \fIfilename\fP ] [ \fIarguments ...\fP ]

.SH "DESCRIPTION" 
ConTeXt is a typesetting system based on the
.BR tex (1)
family of programs.
.B texmfstart
is a ConTeXt meta-script that can run subordinate
scripts (subscripts?) such as 
.BR texexec (1),
.BR ctxtools (1),
or
.BR pdftools (1).  
It can also generate short wrapper scripts to simplify common uses.
These scripts are often called
.I stubs
in the ConTeXt documentation.  The options control
.BR texmfstart 's
behaviour, and the arguments are passed
to the program identified by
.IR filename .

If the filename is a document, then 
.B texmfstart
will start a viewer for that document.  For example:
.EX
texmfstart showcase.pdf
.EE
will start an appropriate viewer for
.IR showcase.pdf .
See the
.B EXAMPLES
section.

.SH OPTIONS

.SS General:
.TP
.B --help, --version
print version information, usage, and examples.
.TP
.B --verbose
print status and progress information, for example what commands are
being executed.
.TP
.B --clear
don't pass info about locations to child processes.

.SS Running a program:
.TP
.B --arguments=\fIstr\fP
an alternative for providing the arguments to be passed.  For example,
.EX
texmfstart --arguments=b.tex texexec
.EE
will pass
.I b.tex
as the argument to
.BR texexec .
.TP
.B --report
dry run: report what command would be run, but do not run it
.TP
.B --locate
dry run: like \f(CW--report\fP but doesn't print the trailing newline.
.TP
.B --browser
view the document in a web browser (for Windows).
.TP
.B --file=\fIfilename\fP
an alternative way to specify the file (the program to run or document
to open).
.TP
.B --direct
run a program without searching for its location (assumes that the
program is on the PATH).
.TP
.B --execute
use the 
.BR ruby (1)
.I exec
function instead of its
.I system
function.
.TP
.B --program=\fIstr\fP
the program space where
.BR kpsewhich (1)
will search (default: context).  This information is given to
.B kpsewhich
as its \f(CW-progname\fP option.  Usually you don't need this option.

.SS Creating startup scripts:
.TP
.B --make
create a wrapper script or batch file to run the given file.
The wrapper scripts are put in the current path, which usually means
the current directory.  If
\fIall\fP is given as the file, e.g.
.EX
texmfstart --make all
.EE
then make all the ConTeXt wrapper scripts (the stubs).
.TP
.B --windows
when making a wrapper script (stub), create a Windows batch (.bat) file.
Usually you
do not need to specify this option, as 
.B texmfstart
will figure out what operating system you are using.
.TP
.B --linux
when making a wrapper script, create a Unix shell script.  Usually you
do not need to specify this option, as 
.B texmfstart
will figure out what operating system you are using.
.TP
.B --stubpath=\fIpath\fP
specify where to put the wrapper scripts (stubs).
.TP
.B --indirect
always use
.I texmfstart
in the wrapper script (stub).

.SS Document viewing:
.TP
.B --page=\fInumber\fP
open the document at this page.

.SS Environments and paths:
.TP
.B --path=\fIstr\fP
change to the specified path.
.TP
.B --tree=\fIstr\fP
use the given TEXMF tree.
.TP
.B --autotree
automatically determine the TEXMF tree to use (the default).
.TP
.B --environment=\fIstr\fP
use the given environment file.  Its syntax is given in the 
.I mtexmfstart.pdf
manual.
.TP
.B --showenv
print the environment variables known at runtime

.SS Conditional execution:
.TP
.B --iftouched=\fIfile1,file2\fP
run only when the given files have different timestamps.
.TP
.B --ifchanged=\fIstr\fP
run only when the given file has changed (based on its last-computed MD5
checksum).

.SS Special features:
.TP
.B --edit
open the given file in an editor.

.SH "FILENAME PREFIXES"
.SS
Optional prefixes determine the method used to search for the specified file:
.TP
.I bin:filename
expanded name based on the PATH environment variable
.TP
.I kpse:filename
expanded name based on
.BR kpsewhich (1)
result
.TP
.I rel:filename
expanded name relative to the current directory
.TP
.I env:name
expanded pathname based on environment variable
.I name
.TP
.I path:filename
path part of filename as located by 
.BR kpsewhich (1)

.SH EXAMPLES
.TP
\f(CWtexmfstart texexec.rb file.tex\fP
Locate the
.I texexec.rb
script and run it with 
.I file.tex
as its argument.  In other words, make 
.I file.pdf
from 
.IR file.tex .
If 
.BR texexec (1)
is properly installed on your system,
this common invocation can be shortened to 
.EX
\f(CWtexexec file.tex\fP
.EE
.TP
\f(CWtexmfstart texexec file.tex\fP
Locate the
.BR texexec (1)
program (currently a 
.BR ruby (1)
script, 
.IR texexec.rb )
and run it with 
.I file.tex
as its argument, producing 
.I file.pdf.
This invocation can be shortened to 
.EX
texexec file.tex
.EE
.TP
\f(CWtexmfstart ctxtools --updatecontext\fP
Run the 
.BR ctxtools (1)
script, updating the ConTeXt installation.  This
invocation is equivalent to
.EX
ctxtools --updatecontext
.EE
.TP
\f(CWtexmfstart pstopdf --method=3 cow.eps\fP
Convert
.I cow.eps
to PDF using method 3 of
.BR pstopdf (1).
This invocation is equivalent to 
.EX
pstopdf --method=3 cow.eps
.EE
.TP
\f(CWtexmfstart --make --stubpath=/usr/local/bin texexec\fP
Make a wrapper script (stub), either a shell script
.I /usr/local/bin/texexec
on Unix, or a batch file \fI\\usr\\local\\bin\\texexec.bat\fP
on Windows.  On Unix (and maybe on Windows?), you need to make
the script executable; see 
.BR chmod (1).
.TP
\f(CWtexmfstart --edit kpse:cont-sys.tex\fP
Locate and edit the \fIcont-sys.tex\fP configuration file.
.TP
\f(CWtexmfstart --ifchanged=whatever.mp texexec --mpgraphic whatever.mp\fP
Rerun
.B texexec
if
.I whatever.mp
has changed since the last use of 
.IR --ifchanged .
.TP
\f(CWtexmfstart --ifchanged=whatever.mp bin:echo rerun MetaPost\fP
If the
.I whatever.mp
source file has changed since the last use of 
.IR --ifchanged ,
then use the 
.BR echo (1)
command to tell the user to rerun MetaPost
.RB "(see " mpost (1)).
This example shows that 
.B texmfstart
can be used to run any script, not just ConTeXt scripts.  The
\f(CWbin:\fP prefix tells 
.B texmfstart
not to search for 
.I echo
in the TEXMF tree(s), but to assume that it's an executable somewhere 
on the PATH.
.TP
\f(CWtexmfstart --ifchanged=whatever.mp --direct echo rerun MetaPost\fP
This invocation has the same effect as the preceding example, but
using \f(CW--direct\fP instead of the \f(CWbin:\fP prefix, again to tell 
.B texmfstart
not to search for the 
.I echo
command.

.SH FILES
.TP
.I file.md5
MD5 checksum file used for the \f(CW--ifchanged\fP option.

.SH ENVIRONMENT
.TP
PATH
For expanding filenames given with a
.I bin
prefix.
.TP
TEXMFSTART_EDITOR, EDITOR, editor
Editor to use with
.IR --edit .
The environment variables are looked up in that order, with the first
setting found taking priority.

.SH "SEE ALSO" 
.PP
.BR ctxtools (1),
.BR kpsewhich (1),
.BR makempy (1),
.BR mpost (1),
.BR pdftools (1),
.BR pstopdf (1),
.BR texexec (1),
.BR texfont (1),
.BR texutil (1).
.PP
.URL "http://www.contextgarden.net" "ConTeXt wiki" .
.PP
The
.B texmfstart
manual,
.IR mtexmfstart.pdf ,
available from
.URL "http://www.pragma-ade.com/dir/general/manuals/" "PRAGMA ADE" .

.SH BUGS
On Unix, opening a PDF document first tries
.B pdfopen
then 
.BR acroread ,
neither of which may be present on your system.

The \f(CW--report\fP option doesn't work if you specify a filename
prefix (i.e. it does a real run instead of a dry run).

.SH "AUTHOR" 
ConTeXt is written and maintained by 
.URL "http://www.pragma-ade.com" "Hans Hagen" .
This man page, which is in the public domain, was written by Sanjoy
Mahajan <sanjoy@mit.edu> based on the
.I mtexmfstart.pdf
manual.