Debian Codegraph @

texmf-dist/doc/man/man1/memoize-extract.1

raw
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.