summaryrefslogtreecommitdiff
path: root/support/runtex/README
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/runtex/README
Initial commit
Diffstat (limited to 'support/runtex/README')
-rw-r--r--support/runtex/README287
1 files changed, 287 insertions, 0 deletions
diff --git a/support/runtex/README b/support/runtex/README
new file mode 100644
index 0000000000..497a699c2e
--- /dev/null
+++ b/support/runtex/README
@@ -0,0 +1,287 @@
+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.