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