Directory support/runtex

runtex 0.1.0
Copyright (c) 2005 by Bernd Becker
(runtex is public domain)

A Win32 program(me) that tries to guess the number of times - if you
neglected to tell it how often - the TeX variant of your choice should
be executed and which other utilities - detected by the suffixes of files
in the same directory of the document you want to be processed - if at all,
are run between TeX runs.
If runtex.ini is found in the directory of the document those values set
will override the ones in runtex's default, which is in the same directory
as runtex.

--------------

A. Installation:
Copy the .exe and .ini into your path - your TeX's binary directory would
probably be just fine.

1. runtex ini entries explained
	see the runtex.ini which came with the .exe for an example
-> t
	TeX's name.
-> t_cmd
	additional command-line switches you want to pass to TeX.
	(default=file name only)
-> l
	LaTeX's name.
-> l_cmd
	additional command-line switches you want to pass to LaTeX.
	(default=file name only)
-> e
	eTeX's name.
-> e_cmd
	additional command-line switches you want to pass to eTeX.
	(default=file name only)
-> p
	pdfTeX's name.
-> p_cmd
	additional command-line switches you want to pass to pdfTeX.
	(default=file name only)
-> el
	eLaTeX's name.
-> el_cmd
	additional command-line switches you want to pass to eLaTeX.
	(default=file name only)
-> pe
	pdfeTeX's name.
-> pe_cmd
	additional command-line switches you want to pass to pdfeTeX.
	(default=file name only)
-> pl
	pdfLaTeX's name.
-> pl_cmd
	additional command-line switches you want to pass to pdfLaTeX.
	(default=file name only)
-> pel
	pdfeLaTeX's name.
-> pel_cmd
	additional command-line switches you want to pass to pdfeLaTeX.
	(default=file name only)
-> idx_type=1
	makeindex will be run - default
	-> idx=name of makeindex
	-> idx_cmd=additional command-line switches for makeindex.
	(default=file name only)
-> idx_type=2
	convert .idx and then run xindy
		(when no changes to TeX index commands by packages)
	-> idx=path to xindy (*without* name of executable)
	directory separator at end of path will be added if missing
	-> idx_cmd=ignored
	(default=the whole thing needed)
-> idx_type=3
	xindy will be run (.raw instead of .idx generated)
	-> idx=path to xindy (*without* name of executable)
	directory separator at end of path will be added if missing
	-> idx_cmd=.xdy file to use, as no guesses can be made which
	one you want to use
-> glo
	name of makeindex
-> glo_cmd
	additional command-line switches you want to pass to makeindex.
	(default=-s gglo.ist -o %s.gls %s.glo, where %s is the \jobname)
-> bib
	name of BibTeX
-> bib_cmd
	command-line switches you want to pass to BibTeX.
-> mf
	name of MetaFONT
-> mf_cmd
	command-line switches you want to pass to MetaFONT.
-> mp
	name of MetaPOST
-> mp_cmd
	command-line switches you want to pass to MetaPOST.
-> refresh
	name of file to refresh the file database for TeX
-> refresh_cmd
	command-line switches needed for the refresh to be done.
-> local_texmf
	path to your local texmf directory
	directory separator at end of path will be added if missing
-> local_packages
	path from your local texmf to the directory containing the
	locally installed packages
	directory separator at end of path will be added if missing
-> local_doc
	path from your local texmf to the directory containing documentation
	of the locally installed packages
	directory separator at end of path will be added if missing

--------------

B. Known Problems

1. If you have several documents in the same directory and
there are .mp or .mf files not belonging to the document to be processed,
runtex still runs the external utilities on them because it has no way of
knowing that this is not necessary.
If none of them are needed for this document you should pass it
the '-n' switch.

2. if the document is split up in several files and there are only
"\citation{" commands in .aux files created for included files, BibTeX
will *not* be executed.

3. if the filename of the document has several suffixes, chances are
the detection of support files (created by the first TeX run, or otherwise)
for it will fail. (I only check for the last suffix, if the file name
contains at least one)

4. you can screw up the .ini file parsing very easily, so be careful about
how you change/write the .ini file(s), or you will get an error as soon as
runtex tries to do anything with the options set in the file or even when
reading the files.
Rules to keep in mind:
	a. Don't use white space except spaces in xxx_cmd strings to delimit
		options for the program xxx.
	b. Always end a line with a return, even the last one.
	c. It doesn't matter if the entry is not in the file or has no value.
		(the example runtex.ini has all entries so default values for all
		options can be defined, but if some won't be used ever you can delete
		them even there, no problem)
		This enables one to only set those variables in the local .ini which
		one wishes to change.

--------------

C. Notes:

1. Entries in a local runtex.ini will *overwrite* the default values !!
	*not* add to them.

2. There *has* to be a runtex.ini in the same directory the .exe is in.
	It is used to setup default values, so do *not* delete it.

4. TeX variants known
	TeX: default
	eTeX: -t e
	LaTeX: -t l
	pdfTeX: -t p
	eLaTeX: -t el
	pdfeTeX: -t pe
	pdfLaTeX: -t pl
	pdfeLaTeX: -t pel
If some/all names of the variant executables are not set in any runtex.ini
the respective TeX variant(s) can not be used, obviously.

5. Suffixes recognized and their effects
a. filename without suffix passed (\jobname) plus
	"brf" -> TeX run again
	"loa" -> TeX run again
	"lof" -> TeX run again
	"lol" -> TeX run again
	"lot" -> TeX run again
	"thm" -> TeX run again
	"toc" -> TeX run again
	"out" -> TeX run again
	"mtc*" -> TeX run again
	"mlf*" -> TeX run again
	"mlt*" -> TeX run again
	"ptc*" -> TeX run again
	"plf*" -> TeX run again
	"plt*" -> TeX run again
	"stc*" -> TeX run again
	"slf*" -> TeX run again
	"slt*" -> TeX run again
	"idx" -> Index utility run, TeX run again
	"glo" -> makeindex utility run with mandatory options, TeX run again
b. any filename plus
	"mp" -> MetaPost run, TeX run again
	"mf" -> MetaFont run, TeX run again
c. BibTeX
	the file \jobname.aux is searched for "\citation{" and if found, and
	enabled, the BibTeX command is executed with \jobname.
	TeX run twice

6. Examples
a. runtex -d -t pel design.tex
	Executes pdfeLaTeX, searches for files that may need to be processed
	by utilities and doing so if found (design.(idx|raw),design.glo,
	design.aux,*.mf,*.mp), and if not searches for files
	that may make it necessary to run pdfeLaTeX again regardless
	(design.(lot|lof|loa|toc|brf...)). And if any of the files were found
	pdfeLaTeX is run again.
	The temporary files created by utilities/pdfeLaTeX are deleted.

b. runtex -n -r 3 -t l design
	Executes LaTeX three times on design.tex without trying to find out
	if utils may need to be executed - and therefore won't - on their
	respective files.

c. runtex -s -t e design.tex
	Executes eTeX, searches for files that may need to be processed
	by utilities and doing so if found (design.idx,design.aux,*.mf,*.mp),
	and if not searches for files that may make it necessary to run
	eTeX again regardless (design.(lot|lof|loa|toc|brf...)), printing
	a message at every step it takes to let the user know what it
	currently does.

--------------

D. Usage:
	runtex [OPTIONS] FILE

Options:
	-d
delete temporary files after last TeX run
	-h
print help text
	-i
try to install package in filename.ins/dtx
	-n
don't execute utilities even if files matching the suffixes searched for are
in the directory
	-r (1-4)
1:> execute TeX once
2:> execute TeX once, execute utilities if deemed necessary,
execute TeX again
(default if no BibTeX files are found)
3:> execute TeX once, execute utilities if deemed necessary,
execute TeX twice
(default if BibTeX files are found. may be needed for some TeX files not
using BibTeX as well)
4:> execute TeX once, execute utilities if deemed necessary,
execute TeX thrice
(may be needed for some documents using BibTeX (and others??))
(<=0) || (>4):> ignored. runtex will determine the number itself.
not passed:> execute TeX once, execute utilities if deemed necessary,
execute TeX again if certain files are found.
	-t [p][e][l]
the TeX variant to use:
	p => pdf...
	e => e...
	l => LaTeX
if l is not given => TeX (default)
	-s
print which TeX variant is executed, which files are found that
runtex thinks have something to do with the document to be processed, and
what it will do because of it
	-v
print program version

File:
	May be with or without suffix (.ins or .tex/.ltx depending if you want
to install a package or not).

--------------

E. Missing stuff and ideas:

1. Maybe find a way to analyze .aux or .log or whatever to find out when
to run the TeX variant 3 times. (possible?)
2. Maybe find a way to analyze .aux or .log or whatever to find out if
.mf/.mp actually are being used by the document to be processed.
(search document rather, but if inclusion is hidden in a macro not in
the document ??)
3. switch for directory to search for .mp/.mf files ???

--------------

F. Contact:

If you think you found a bug, or want a TeX variant added because you do not
have a compiler, or...
send an e-mail to munin@munin.inka.de. TIA.