diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/memoize/memoize-extract.1.md')
-rw-r--r-- | Master/texmf-dist/doc/generic/memoize/memoize-extract.1.md | 82 |
1 files changed, 60 insertions, 22 deletions
diff --git a/Master/texmf-dist/doc/generic/memoize/memoize-extract.1.md b/Master/texmf-dist/doc/generic/memoize/memoize-extract.1.md index 434f2fea2f6..f3f3d52ad0f 100644 --- a/Master/texmf-dist/doc/generic/memoize/memoize-extract.1.md +++ b/Master/texmf-dist/doc/generic/memoize/memoize-extract.1.md @@ -2,8 +2,8 @@ title: memoize-extract section: 1 header: User Manual -footer: memoize-extract of Memoize v1.0.0 -date: October 10, 2023 +footer: memoize-extract of Memoize v1.1.0 +date: January 02, 2024 hyphenate: false --- @@ -34,17 +34,17 @@ Memoize communicates with **memoize-extract** through file *document.mmz*. When *document.mmz*, which records which pages in the produced document are extern pages and to which extern files they should be extracted. Therefore, after compiling *document.tex*, the externs should be extracted by -**memoize-extract** *document.mmz*. +**memoize-extract** *document.mmz*. + +*document.mmz* may also be given as document* or *document.tex*. When +environment variable *TEXMF_OUTPUT_DIRECTORY* is set, this filename is relative +to the output directory specified by this variable. *document.mmz* also records the expected width and height of each extern. In case of a mismatch, **memoize-extract** refuses to extract the page and removes the extern file if it already exist, and prints a warning message to the -standard error. The script furthermore refuses to extract the page if a -(c)c-memo associated to the extern does not exist, and to write to any file -whose absolute path does not occur under the current directory or the directory -set by TEXMFOUTPUT (in *texmf.cnf* or as an environment variable); TEXMFOUTPUT -is also not allowed to point to the root directory, except on Windows, where it -can only point to a drive root. +standard error. The script also refuses to extract the page if a (c)c-memo +associated to the extern does not exist. See also section SECURITY. The Perl (.pl) and the Python (.py) version of the script are functionally equivalent. The Perl script requires library @@ -64,30 +64,68 @@ library [pdfrw2](https://pypi.org/project/pdfrw2). : Do not modify the *document.mmz* to mark the externs as extracted. By default, they are commented out to prevent double extraction. +**-F, \--format** *latex*|*plain*|*context* +: When this option is given, the script assumes that it was called from within + a TeX compilation of a document in the given format: it prefixes all output + by the script name, and creates a log file *document.mmz.log*, which receives + any extraction-related warnings and errors. + **-f, \--force** : Extract the extern even if the size-check fails. -**-l, \--log** *filename* -: Log size mismatches to *filename* rather than to the standard error. - -**-w, \--warning-template** *string* -: Wrap the size mismatch warning text into the given template: \\warningtext in - the template will be replaced by the warning text. - **-q, \--quiet** : Don't describe what's happening. -**-e, \--embedded** -: Prefix all messages to the standard output with the script name. - **-m, \--mkdir** -: A paranoid *mkdir -p*. (No extraction occurs, *document.mmz* is interpreted as a directory name.) +: A paranoid *mkdir -p*. (No extraction occurs, *document.mmz* is interpreted as a directory name, which may end in any suffix; no suffix mangling is performed.) + +**-V, \--version** +: Show the Memoize version number and exit. **-h, \--help** : Show help and exit. -**-V, \--version** -: Show the Memoize version number and exit. +# SECURITY + +This script respects the restrictions on file input and output imposed by the +TeX configuration, more precisely, the variables *openin_any* and *openout_any* +of the **kpathsea** library (https://tug.org/kpathsea). You can inspect the +values of these variables by executing '**kpsewhich** -var-value=openin_any' and +'**kpsewhich** -var-value=openout_any'. The interpretation is as follows: + +**a** (or **y** or **1**) any +: Allows any file to be opened. + +**r** (or **n** or **0**) restricted +: Means disallowing special file names. + +**p** (or any other value) paranoid +: Means being really paranoid: disallowing special file names and restricting + input/output files to be in or below the working directory or the directory + specified by *TEXMFOUTPUT* or *TEXMF_OUTPUT_DIRECTORY*. *TEXMFOUTPUT* may be + set either in *texmf.cnf* (e.g. by **tlmgr**) or as an environment + variable. *TEXMF_OUTPUT_DIRECTORY* may only be set as an environment + variables; it is automatically set by TeX when called by *-output-directory* + option (starting in TeXLive 2024). + +# EXIT STATUS + +**0** +: The externs were successfully extracted. This exit code is returned even if + no externs need to be extracted, or if *document.mmz* does not exist. + +**10** +: A warning also reported back to the compilation when given option + **\--format**. Currently, either: (i) size-mismatch; (ii) a non-existing + associated (c)c-memo file; or (iii) unavailable *kpsewhich*. + +**11** +: An error also reported back to the compilation when given option + **\--format**. Currently, either: (i) a currupted document PDF, or (ii) + a kpathsea permission error. + +Other exit codes are as produced by the underlying scripting language (Perl of +Python). # SEE ALSO |