diff options
Diffstat (limited to 'Build/source/utils/mkjobtexmf/mkjobtexmf.txt')
-rw-r--r-- | Build/source/utils/mkjobtexmf/mkjobtexmf.txt | 251 |
1 files changed, 251 insertions, 0 deletions
diff --git a/Build/source/utils/mkjobtexmf/mkjobtexmf.txt b/Build/source/utils/mkjobtexmf/mkjobtexmf.txt new file mode 100644 index 00000000000..7e5dce464b8 --- /dev/null +++ b/Build/source/utils/mkjobtexmf/mkjobtexmf.txt @@ -0,0 +1,251 @@ +NAME + + mkjobtexmf -- Generate a texmf tree for a particular job + +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 + --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 + +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. + + --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. + +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. + + <jobname>.fls + Name of TeX's recorder file. + + <jobname>.strace + Log file where the result of strace is stored. + +AUTHOR + + Heiko Oberdiek, email: oberdiek at uni-freiburg.de + +COPYRIGHT AND LICENSE + + Copyright 2007 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. + |