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.

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.