Debian Codegraph @

texmf-dist/doc/generic/memoize/memoize-extract.1.md

raw
1 ---
2 title: memoize-extract
3 section: 1
4 header: User Manual
5 footer: memoize-extract of Memoize v1.4.1
6 date: December 02, 2024
7 hyphenate: false
8 ---
9
10 # NAME
11 memoize-extract.pl, memoize-extract.py - Extract extern pages out of the PDF
12
13
14 # SYNOPSIS
15 **memoize-extract.pl** [*OPTIONS*] *document.mmz*
16
17 **memoize-extract.py** [*OPTIONS*] *document.mmz*
18
19
20 # DESCRIPTION
21
22 **memoize-extract** is a script accompanying Memoize, a TeX package which
23 allows the author to reuse the results of compilation-intensive code such as
24 TikZ pictures.
25
26 Memoize dumps the created externs (boxes containing the typeset material to be
27 reused) onto their own pages in the produced PDF file. It is the job of
28 **memoize-extract** to extract these extern pages into separate PDF files. At
29 subsequent compilations, Memoize will include those extern files into the
30 document, without compiling their source again.
31
32 Memoize communicates with **memoize-extract** through file *document.mmz*. When
33 *document.tex* is compiled to produce *document.pdf*, Memoize produces
34 *document.mmz*, which records which pages in the produced document are extern
35 pages and to which extern files they should be extracted. Therefore, after
36 compiling *document.tex*, the externs should be extracted by
37 **memoize-extract** *document.mmz*.
38
39 *document.mmz* may also be given as document* or *document.tex*. When
40 environment variable *TEXMF_OUTPUT_DIRECTORY* is set, this filename is relative
41 to the output directory specified by this variable.
42
43 *document.mmz* also records the expected width and height of each extern. In
44 case of a mismatch, **memoize-extract** refuses to extract the page and removes
45 the extern file if it already exist, and prints a warning message to the
46 standard error. The script also refuses to extract the page if a (c)c-memo
47 associated to the extern does not exist. See also section SECURITY.
48
49 The Perl (.pl) and the Python (.py) version of the script are functionally
50 equivalent. The Perl script requires library
51 [PDF::API2](https://metacpan.org/pod/PDF::API2), and the Python script requires
52 library [pdfrw2](https://pypi.org/project/pdfrw2).
53
54 # OPTIONS
55
56 **-P, \--pdf** *filename.pdf*
57 : The externs will be extracted from *filename.pdf*. By default,
58 they are extracted from *document.pdf*.
59
60 **-p, \--prune**
61 : Remove the extern pages from the PDF after extraction.
62
63 **-k, \--keep**
64 : Do not modify the *document.mmz* to mark the externs as extracted. By
65 default, they are commented out to prevent double extraction.
66
67 **-F, \--format** *latex*|*plain*|*context*
68 : When this option is given, the script assumes that it was called from within
69 a TeX compilation of a document in the given format: it prefixes all output
70 by the script name, and creates a log file *document.mmz.log*, which receives
71 any extraction-related warnings and errors.
72
73 **-f, \--force**
74 : Extract the extern even if the size-check fails.
75
76 **-q, \--quiet**
77 : Don't describe what's happening.
78
79 **-m, \--mkdir**
80 : 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.)
81
82 **-V, \--version**
83 : Show the Memoize version number and exit.
84
85 **-h, \--help**
86 : Show help and exit.
87
88 # SECURITY
89
90 This script respects the restrictions on file input and output imposed by the
91 TeX configuration, more precisely, the variables *openin_any* and *openout_any*
92 of the **kpathsea** library (https://tug.org/kpathsea). You can inspect the
93 values of these variables by executing `kpsewhich -var-value=openin_any` and
94 `kpsewhich -var-value=openout_any`. The interpretation is as follows:
95
96 **a** (or **y** or **1**) any
97 : Allows any file to be opened.
98
99 **r** (or **n** or **0**) restricted
100 : Means disallowing special file names.
101
102 **p** (or any other value) paranoid
103 : Means being really paranoid: disallowing special file names and restricting
104 input/output files to be in or below the working directory or the directory
105 specified by *TEXMFOUTPUT* or *TEXMF_OUTPUT_DIRECTORY*. *TEXMFOUTPUT* may be
106 set either in *texmf.cnf* (e.g. by **tlmgr**) or as an environment
107 variable. *TEXMF_OUTPUT_DIRECTORY* may only be set as an environment
108 variables; it is automatically set by TeX when called by *-output-directory*
109 option (starting in TeXLive 2024).
110
111 # EXIT STATUS
112
113 **0**
114 : The externs were successfully extracted. This exit code is returned even if
115 no externs need to be extracted, or if *document.mmz* does not exist.
116
117 **10**
118 : A warning also reported back to the compilation when given option
119 **\--format**. Currently, either: (i) size-mismatch; (ii) a non-existing
120 associated (c)c-memo file; or (iii) unavailable *kpsewhich*.
121
122 **11**
123 : An error also reported back to the compilation when given option
124 **\--format**. Currently, either: (i) a corrupted document PDF, or (ii)
125 a kpathsea permission error.
126
127 Other exit codes are as produced by the underlying scripting language (Perl of
128 Python).
129
130 # SEE ALSO
131
132 [Memoize manual](https://ctan.org/pkg/memoize), section 6.6.1.