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