summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/memoize/memoize-extract.1.md
diff options
context:
space:
mode:
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.md82
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