summaryrefslogtreecommitdiff
path: root/support/mkjobtexmf/mkjobtexmf.txt
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/mkjobtexmf/mkjobtexmf.txt
Initial commit
Diffstat (limited to 'support/mkjobtexmf/mkjobtexmf.txt')
-rw-r--r--support/mkjobtexmf/mkjobtexmf.txt308
1 files changed, 308 insertions, 0 deletions
diff --git a/support/mkjobtexmf/mkjobtexmf.txt b/support/mkjobtexmf/mkjobtexmf.txt
new file mode 100644
index 0000000000..e64edeec07
--- /dev/null
+++ b/support/mkjobtexmf/mkjobtexmf.txt
@@ -0,0 +1,308 @@
+NAME
+
+ mkjobtexmf -- Generate a texmf tree for a particular job
+
+VERSION
+
+ 2011-11-10 v0.8
+
+SYNOPSIS
+
+ The progam mkjobtexmf runs a program and tries to find the used file
+ names. Two methods are available, option "-recorder" of TeX (Web2C) or
+ the program strace.
+
+ Then it generates a directory with a texmf tree. It checks the found
+ files and tries sort them in this texmf tree.
+
+ It can be used for archiving purposes or to speed up following TeX runs.
+
+ mkjobtexmf [options]
+
+ This runs TeX that can be configured by options. Both methods for
+ getting the used file names are available.
+
+ mkjobtexmf [options] -- <cmd> [args]
+
+ The latter form runs program *cmd* with arguments *args* instead of TeX.
+ As method only program strace is available.
+
+ Options:
+
+ --jobname <name> Name of the job (mandatory).
+ Usually this is the TeX file
+ without extension
+ --texname <file> Input file for TeX. Default is the
+ job name with extension '.tex'
+ --texopt <option> Option for TeX run
+ --destdir <directory> Destination directory,
+ default is `<jobname>.mjt'
+ --output Add also output files
+ --strace Use strace instead of TeX's
+ option -recorder
+ --copy Copy files instead of creating
+ symbol links
+ --flat Junk paths, do not make directories
+ inside the destination directory
+ --(no)texhash Run texhash, use --notexhash for MiKTeX
+ --exclude-ext <ext> Exclude files with extension <ext>.
+ --cmd-tex <cmd> Command for the TeX compiler
+ --cmd-kpsewhich <cmd> Command for kpsewhich
+ --cmd-texhash <cmd> Command for texhash
+ --cmd-strace <cmd> Command for strace
+ --verbose Verbose output
+ --help Brief help message
+ --man Full documentation
+ --version Print version identification
+
+DESCRIPTION
+
+ Running the program
+
+ First mkjobtexmf runs a program, usually TeX. The TeX compiler is
+ configured by option "--cmd-tex". Option "--texname" can be used, if the
+ file name extension differs from .tex:
+
+ mkjobtexmf --jobname foo --texname foo.ltx
+
+ Even more complicate cases are possible:
+
+ mkjobtexmf --jobname foo --texname '\def\abc{...}\input{foo}'
+
+ If another program than TeX should be used (dvips, ...), then this
+ program can be given after "--":
+
+ mkjobtexmf --jobname foo -- dvips foo
+
+ File recording
+
+ Two methods are available to get the used file names:
+
+ Recorder of TeX
+ Some TeX distributions (e.g. Web2C) support the option -recorder for
+ its TeX compilers. Then the TeX compiler generates a file with
+ extension .fls that records the used input and output files.
+
+ Program strace
+ This program traces system calls and signals. It is used here to log
+ the used files.
+
+ Analyze and link/copy found files
+
+ The result directory *jobname*.mjt is generated. Inside the result TEXMF
+ tree is created. Each found file is compared against a list of paths of
+ TEXMF trees. If a match is found, the file is linked/copied into the
+ TEXMF tree. The list of paths is generated by program kpsewhich.
+
+ If the file cannot be mapped to a TEXMF tree and the file is a relative
+ file name, then it is directly linked/copied into the result directory
+ *jobname*.mjt. Absolute file names are not supported and neither paths
+ with links to parent directories.
+
+ Symbolic links are created by default. The files are copied if option
+ "--copy" is given or symbolic linking is not available.
+
+OPTIONS
+
+ --jobname=<*jobname*>
+ It is the name of the job. `<*jobname*>.tex' serves as default for
+ the TeX file and <*jobname*> is used for naming various directories
+ and files. See section "FILES".
+
+ --texname=<*name*>
+ The name of the TeX input file, if it differs from <*jobname*>.tex.
+
+ --texopt=<*opt*>
+ Additional option for the TeX compiler, examples are "--ini" or
+ "--shell-escape". This option can be given more than once.
+
+ --destdir=<*directory*>
+ Specifies the name of the destination directory where the result is
+ collected. As default a directory is generated in the current
+ directory with the job name and extension `.mjt'.
+
+ --output
+ Also add output files.
+
+ --strace
+ Use method with program strace, see "DESCRIPTION".
+
+ --copy
+ Files are copied instead of creating symbolic links.
+
+ --flat
+ Files are linked or copied without path elements. The destination
+ directory will contain a flat list of files or links without
+ directory.
+
+ The files `ls-R' and `aliases' are ignored.
+
+ --exclude-ext=<*ext*>
+ Files with extension <*ext*> are excluded. The option can be given
+ several times or a comma separated list of extensions can be used.
+ Examples:
+
+ --exclude-ext aux --exclude-ext log --exclude-ext toc
+
+ is the same as
+
+ --exclude-ext aux,log,toc
+
+ --(no)texhash
+ As default the file `ls-R' is generated in the `texmf' tree, because
+ this is the file name database that might be used in TeX Live.
+ Because MiKTeX uses a different mechanism, its `texhash' does not
+ generate the `ls-R' files and "--notexhash" suppresses the call of
+ `texhash'.
+
+ --cmd-tex=<*cmd*>
+ Command for the TeX compiler. Default is pdflatex.
+
+ --cmd-kpsewhich=<*cmd*>
+ Command for kpsewhich.
+
+ --cmd-texhash=<*cmd*>
+ Command for updating the file name database of the generated texmf
+ tree. Default is texmf.
+
+ --cmd-strace=<*cmd*>
+ Command for strace.
+
+ --verbose
+ Verbose messages.
+
+ --help
+ Display help screen.
+
+ -B(-man>
+ Print manual page.
+
+ --version
+ Print version identification and exit.
+
+EXAMPLES
+
+ TeX file test.tex using TeX's recorder method:
+
+ mkjobtexmf --jobname test
+
+ TeX file test.tex using LaTeX:
+
+ mkjobtexmf --jobname test --cmd-tex latex
+
+ Format generation:
+
+ mkjobtexmf --jobname test --texopt -ini --texname pdflatex.ini
+
+ Example, how the new texmf tree (Linux/bash) can be used:
+
+ TEXMF=!!test.mjt/texmf pdflatex test
+
+ Example for generating a zip archive (Linux/bash):
+
+ (cd test.mjt && zip -9r ../test .)
+
+ Example for generating a tar archive:
+
+ tar cjhvf test.tar.bz2 -C test.mjt .
+
+UNSOLVED ISSUES, CAVEATS, TODOS
+
+ Experimental software
+ Options, defaults, how the program works might change in future
+ versions.
+
+ texmf.cnf
+ Currently the method with strace records this files. TeX's recorder
+ does not. Useful are texmf.cnf files for variable settings. Because
+ we have just one TEXMF tree, the path sections should probably
+ rewritten.
+
+ Settings in environment variables
+ They are not stored at all.
+
+ Collisions
+ The program uses one destination directory and at most one TEXMF
+ tree for the result. However, the source files can come from
+ different directories and TEXMF trees. Therefore name collisions are
+ possible.
+
+ The program follows the strategy not to delete files in the
+ destination directory. That allows to collect files from differnt
+ runs. Thus collisions are resolved in the manner that the first
+ entry that is made in the destination directory wins.
+
+ Configuration file
+ It would save the user from retyping the same options again and
+ again.
+
+ Uncomplete recording
+ Bugs in TeX's file recording might result in incomplete file
+ recording (e.g. pdfTeX 1.40.3 does not record .pfb and .pk files).
+
+ ...
+
+FILES
+
+ <jobname>.mjt/
+ Directory where the resulting texmf tree and symbol links are
+ stored. It can be changed by option "--destdir".
+
+ <jobname>.fls
+ Name of TeX's recorder file.
+
+ <jobname>.strace
+ Log file where the result of strace is stored.
+
+AUTHOR
+
+ Heiko Oberdiek, email: heiko.oberdiek at googlemail.com
+
+COPYRIGHT AND LICENSE
+
+ Copyright 2007, 2008, 2011 by Heiko Oberdiek.
+
+ This library is free software; you may redistribute it and/or modify it
+ under the same terms as Perl itself (Perl Artistic License/GNU General
+ Public License, version 2).
+
+HISTORY
+
+ 2007/04/16 v0.1
+
+ * First experimental version.
+
+ 2007/05/09 v0.2
+
+ * Typo in option name fixed.
+
+ 2007/09/03 v0.3
+
+ * New options: "--copy", "--flat", "--destdir"
+
+ 2007/09/04 v0.4
+
+ * Bug fix in map_files_texmf.
+
+ 2007/09/06 v0.5
+
+ * Support for `configure' added. (Thanks to Norbert Preining for
+ writing a first version of the configure stuff.)
+
+ 2008/04/05 v0.6
+
+ * Tiny fix in target `uninstall' in file `Makefile.in'. (Thanks to
+ Karl Berry)
+
+ 2008/06/28 v0.7
+
+ * Fix for unknown option `"--cmd-strace"'. (Thanks to Juho Niemelä)
+
+ 2011/11/10 v0.8
+
+ * Remove colon from drive specification when making directories.
+ * Option "--(no)texhash" added.
+ * Some support for MiKTeX (thanks Ulrike Fischer).
+ * Various fixes in the generation of the documentation.
+ * Options "--exclude-ext" and "--version" added.
+