ConTeXt is a typesetting system based on
the .BR tex (1)
family of programs.
texmfstart
is a ConTeXt meta-script that can run subordinate
scripts (subscripts?) such
as
texexec(1),
ctxtools(1),
or
pdftools(1).
It can also generate short wrapper scripts to simplify common uses.
These scripts are often called
stubs
in the ConTeXt documentation. The options control
texmfstart's
behaviour, and the arguments are passed
to the program identified by
filename.
If the filename is a document, then
texmfstart
will start a viewer for that document. For example:
texmfstart showcase.pdf
will start an appropriate viewer for
showcase.pdf.
See the
EXAMPLES
section.
OPTIONS
General:
--help, --version
print version information, usage, and examples.
--verbose
print status and progress information, for example what commands are
being executed.
--clear
don't pass info about locations to child processes.
Running a program:
--arguments=str
an alternative for providing the arguments to be passed. For example,
texmfstart --arguments=b.tex texexec
will pass
b.tex
as the argument to
texexec.
--report
dry run: report what command would be run, but do not run it
--locate
dry run: like --report but doesn't print the trailing newline.
--browser
view the document in a web browser (for Windows).
--file=filename
an alternative way to specify the file (the program to run or document
to open).
--direct
run a program without searching for its location (assumes that the
program is on the PATH).
--execute
use the
ruby(1)
exec
function instead of its
system
function.
--program=str
the program space where
kpsewhich(1)
will search (default: context). This information is given to
kpsewhich
as its -progname option. Usually you don't need this option.
Creating startup scripts:
--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
all is given as the file, e.g.
texmfstart --make all
then make all the ConTeXt wrapper scripts (the stubs).
--windows
when making a wrapper script (stub), create a Windows batch (.bat) file.
Usually you
do not need to specify this option, as
texmfstart
will figure out what operating system you are using.
--linux
when making a wrapper script, create a Unix shell script. Usually you
do not need to specify this option, as
texmfstart
will figure out what operating system you are using.
--stubpath=path
specify where to put the wrapper scripts (stubs).
--indirect
always use
texmfstart
in the wrapper script (stub).
Document viewing:
--page=number
open the document at this page.
Environments and paths:
--path=str
change to the specified path.
--tree=str
use the given TEXMF tree.
--autotree
automatically determine the TEXMF tree to use (the default).
--environment=str
use the given environment file. Its syntax is given in the
mtexmfstart.pdf
manual.
--showenv
print the environment variables known at runtime
Conditional execution:
--iftouched=file1,file2
run only when the given files have different timestamps.
--ifchanged=str
run only when the given file has changed (based on its last-computed MD5
checksum).
Special features:
--edit
open the given file in an editor.
FILENAME PREFIXES
Optional prefixes determine the method used to search for the specified file:
bin:filename
expanded name based on the PATH environment variable
Locate the
texexec.rb
script and run it with
file.tex
as its argument. In other words, make
file.pdf
from
file.tex.
If
texexec(1)
is properly installed on your system,
this common invocation can be shortened to
texexec file.tex
texmfstart texexec file.tex
Locate the
texexec(1)
program (currently a
ruby(1)
script,
texexec.rb)
and run it with
file.tex
as its argument, producing
file.pdf.
This invocation can be shortened to
texexec file.tex
texmfstart ctxtools --updatecontext
Run the
ctxtools(1)
script, updating the ConTeXt installation. This
invocation is equivalent to
ctxtools --updatecontext
texmfstart pstopdf --method=3 cow.eps
Convert
cow.eps
to PDF using method 3 of
pstopdf(1).
This invocation is equivalent to
Make a wrapper script (stub), either a shell script
/usr/local/bin/texexec
on Unix, or a batch file \usr\local\bin\texexec.bat
on Windows. On Unix (and maybe on Windows?), you need to make
the script executable; see
chmod(1).
texmfstart --edit kpse:cont-sys.tex
Locate and edit the cont-sys.tex configuration file.
If the
whatever.mp
source file has changed since the last use of
--ifchanged,
then use the
echo(1)
command to tell the user to rerun MetaPost
(see mpost(1)).
This example shows that
texmfstart
can be used to run any script, not just ConTeXt scripts. The
bin: prefix tells
texmfstart
not to search for
echo
in the TEXMF tree(s), but to assume that it's an executable somewhere
on the PATH.
This invocation has the same effect as the preceding example, but
using --direct instead of the bin: prefix, again to tell
texmfstart
not to search for the
echo
command.
FILES
file.md5
MD5 checksum file used for the --ifchanged option.
ENVIRONMENT
PATH
For expanding filenames given with a
bin
prefix.
TEXMFSTART_EDITOR, EDITOR, editor
Editor to use with
--edit.
The environment variables are looked up in that order, with the first
setting found taking priority.
On Unix, opening a PDF document first tries
pdfopen
then
acroread,
neither of which may be present on your system.
The --report option doesn't work if you specify a filename
prefix (i.e. it does a real run instead of a dry run).
AUTHOR
ConTeXt is written and maintained by
Hans Hagen <URL: http://www.pragma-ade.com >.
This man page, which is in the public domain, was written by Sanjoy
Mahajan based on the
mtexmfstart.pdf
manual.