NAME
texmfstart - run ConTeXt scripts, make ConTeXt wrapper scripts, view
documents
SYNOPSIS
texmfstart [ options ... ] [ filename ] [ arguments ... ]
DESCRIPTION
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
kpse:filename
expanded name based on kpsewhich(1) result
rel:filename
expanded name relative to the current directory
env:name
expanded pathname based on environment variable name
path:filename
path part of filename as located by kpsewhich(1)
EXAMPLES
texmfstart texexec.rb file.tex
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
pstopdf --method=3 cow.eps
texmfstart --make --stubpath=/usr/local/bin texexec
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.
texmfstart --ifchanged=whatever.mp texexec --mpgraphic whatever.mp
Rerun texexec if whatever.mp has changed since the last use of
--ifchanged.
texmfstart --ifchanged=whatever.mp bin:echo rerun MetaPost
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.
texmfstart --ifchanged=whatever.mp --direct echo rerun MetaPost
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.
SEE ALSO
· ctxtools(1), kpsewhich(1), makempy(1), mpost(1), pdftools(1),
pstopdf(1), texexec(1), texfont(1), texutil(1).
· ConTeXt wiki 〈http://www.contextgarden.net〉.
· The texmfstart manual, mtexmfstart.pdf, available from PRAGMA
ADE 〈http://www.pragma-ade.com/dir/general/manuals/〉.
BUGS
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
〈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.