Debian Codegraph @

texmf-dist/source/latex/repltext/repltext.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2014-2020 Scott Pakin <[email protected]>
4 % ----------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the conditions of
7 % the LaTeX Project Public License, either version 1.3c of this license
8 % or (at your option) any later version. The latest version of this
9 % license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3c or later is part of all distributions of LaTeX version
14 % 2006/05/20 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{repltext.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
23 %<package>\ProvidesPackage{repltext}
24 %<*package>
25 [2020/09/25 v1.1 PDF replacement text]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage[T1]{fontenc}
31 \usepackage{repltext}
32 \usepackage{graphicx}
33 \usepackage{color}
34 \usepackage{hypdoc}
35 \usepackage{hyperref}
36 \usepackage{hyperxmp}
37 \EnableCrossrefs
38 \CodelineIndex
39 \RecordChanges
40
41 % Specify this document's metadata.
42 \title{The \textsf{repltext} package\thanks{This document
43 corresponds to \textsf{repltext}~\fileversion, dated \filedate.}}
44 \author{Scott Pakin \\ \texttt{[email protected]}}
45 \hypersetup{%
46 pdftitle={The repltext package},
47 pdfauthor={Scott Pakin},
48 pdfsubject={LaTeX package for PDF replacement text},
49 pdfkeywords={LaTeX, PDF, replacement text, ActualText, copy and paste},
50 pdfcopyright={Copyright (C) 2014-2020 Scott Pakin},
51 pdflicenseurl={http://www.latex-project.org/lppl/},
52 pdfcaptionwriter={Scott Pakin},
53 pdfcontactemail={[email protected]},
54 pdfcontacturl={http://www.pakin.org/\xmptilde scott/},
55 pdflang={en-US},
56 baseurl={http://mirror.ctan.org/macros/latex/contrib/repltext/repltext.pdf},
57 %
58 colorlinks=false,
59 pdfstartview=Fit
60 }
61
62 \begin{document}
63 \DocInput{repltext.dtx}
64 \PrintChanges
65 \PrintIndex
66 \end{document}
67 %</driver>
68 % \fi
69 %
70 % \CheckSum{59}
71 %
72 % \CharacterTable
73 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
74 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
75 % Digits \0\1\2\3\4\5\6\7\8\9
76 % Exclamation \! Double quote \" Hash (number) \#
77 % Dollar \$ Percent \% Ampersand \&
78 % Acute accent \' Left paren \( Right paren \)
79 % Asterisk \* Plus \+ Comma \,
80 % Minus \- Point \. Solidus \/
81 % Colon \: Semicolon \; Less than \<
82 % Equals \= Greater than \> Question mark \?
83 % Commercial at \@ Left bracket \[ Backslash \\
84 % Right bracket \] Circumflex \^ Underscore \_
85 % Grave accent \` Left brace \{ Vertical bar \|
86 % Right brace \} Tilde \~}
87 %
88 %
89 % \changes{v1.0}{2014/04/11}{Initial version}
90 % \changes{v1.1}{2020/09/25}{Support modern Lua\protect\LaTeX\ versions}
91 %
92 % \GetFileInfo{repltext.dtx}
93 %
94 % \DoNotIndex{\{,\},\bgroup,\catcode,\def,\egroup,\expandafter,\global,\let}
95 % \DoNotIndex{\newcommand,\newenvironment,\protected,\providecommand,\the}
96 %
97 % ^^A Define some logical styles.
98 % \newcommand{\pkgname}[1]{^^A
99 % \textsf{#1}\SortIndex{#1}{\string\textsf{#1} (package)\encapchar usage}}
100 % \newcommand{\pdfname}[1]{^^A
101 % \textsf{#1}\SortIndex{#1}{\string\textsf{#1}\encapchar usage}}
102 % \newcommand{\acronym}[1]{^^A
103 % \textsc{\MakeLowercase{#1}}^^A
104 % \SortIndex{#1}{\string\textsc{\string\MakeLowercase{#1}}\encapchar usage}^^A
105 % }
106 % \DeclareRobustCommand{\cs}[1]{^^A
107 % \texttt{\char`\\#1}^^A
108 % \SpecialUsageIndex{#1}^^A
109 % }
110 %
111 % ^^A The following was derived from
112 % ^^A http://upload.wikimedia.org/wikipedia/en/a/af/Prince_logo.svg
113 % \newcommand{\Prince}{^^A
114 % \pdfliteral{
115 % q
116 % 0 0 1 rg
117 % 3.625 5.456 m 3.625 5.933 3.18 6.214 2.82 6.214 c 2.359 6.214 2.047 5.823
118 % 2.047 5.398 c 2.047 5.003 2.395 4.632 2.828 4.632 c 3.25 4.632 3.625 4.984
119 % 3.625 5.456 c h
120 % 1.457 5.452 m 1.457 6.394 2.23 6.8 2.828 6.8 c 3.582 6.8 4.199 6.198 4.199
121 % 5.456 c 4.199 4.905 4 4.515 3.637 4.304 c 4.004 4.331 4.383 4.378 4.719
122 % 4.515 c 5.07 4.652 5.375 4.882 5.633 5.112 c 5.574 4.816 5.445 4.437 5.441
123 % 4.069 c 5.434 3.694 5.516 3.39 5.695 3.109 c 5.742 3.027 5.66 3.034 5.633
124 % 3.081 c 4.957 3.948 4.023 3.882 3.117 3.882 c 3.117 2.835 l 3.383 2.835
125 % l 3.582 3.038 l 3.582 2.136 l 3.348 2.343 l 3.117 2.343 l 3.117 1.085 l
126 % 3.516 1.359 l 2.855 -0.001 l 2.164 1.37 l 2.57 1.085 l 2.57 2.343 l 2.301
127 % 2.343 l 2.078 2.136 l 2.078 3.038 l 2.277 2.835 l 2.57 2.835 l 2.57 3.882
128 % l 1.945 3.874 1.344 3.777 0.902 3.577 c 0.547 3.417 0.262 3.194 0.258 2.89
129 % c 0.254 2.624 0.324 2.398 0.633 2.398 c 0.934 2.398 1.008 2.542 1.008 2.648
130 % c 1.008 2.753 0.934 2.851 0.848 2.874 c 1.113 2.487 0.438 2.327 0.406 2.726
131 % c 0.387 3.003 0.641 3.069 0.836 3.069 c 1.035 3.069 1.211 2.855 1.234 2.632
132 % c 1.254 2.444 1.07 2.183 0.645 2.183 c 0.121 2.187 0 2.534 0 2.886 c 0
133 % 3.343 0.395 3.698 0.852 3.937 c 1.277 4.155 1.746 4.273 2.098 4.292 c 1.723
134 % 4.499 1.457 4.886 1.457 5.452 c h
135 % f
136 % Q
137 % }^^A
138 % \hspace*{5.7bp}^^A
139 % }
140 %
141 % ^^A A handy use of repltext is to make \LaTeX copy as "LaTeX", not "LATEX".
142 % \DeclareRobustCommand{\latex}[1][]{^^A
143 % \repltext{#1LaTeX}{#1\LaTeX}^^A
144 % \SortIndex{#1LaTeX}{#1\string\LaTeX\encapchar usage}^^A
145 % }
146 %
147 % ^^A Ditto for e-TeX...
148 % \DeclareRobustCommand{\etex}{^^A
149 % \repltext{e-TeX}{$\varepsilon$-\TeX}^^A
150 % \SortIndex{e-TeX}{$\string\varepsilon$-\string\TeX\encapchar usage}^^A
151 % }
152 %
153 % ^^A ...and plain, old TeX.
154 % \DeclareRobustCommand{\tex}{^^A
155 % \repltext{TeX}{\TeX}^^A
156 % \SortIndex{TeX}{\string\TeX\encapchar usage}^^A
157 % }
158 %
159 % ^^A The following environment was copied verbatim from ltxguide.tex.
160 % \makeatletter
161 % \DeleteShortVerb{\|}
162 % \newenvironment{decl}[1][]%
163 % {\par\small\addvspace{4.5ex plus 1ex}%
164 % \vskip -\parskip
165 % \ifx\relax#1\relax
166 % \def\@decl@date{}%
167 % \else
168 % \def\@decl@date{\NEWfeature{#1}}%
169 % \fi
170 % \noindent\hspace{-\leftmargini}%
171 % \begin{tabular}{|l|}\hline\ignorespaces}%
172 % {\\\hline\end{tabular}\nobreak\@decl@date\par\nobreak
173 % \vspace{2.3ex}\vskip -\parskip}
174 % \MakeShortVerb{\|}
175 % \makeatother
176 %
177 % ^^A The following definitions were adapted from ltxguide.tex.
178 % \renewcommand{\arg}[1]{\texttt{\char`\{}\meta{#1}\texttt{\char`\}}}
179 % \renewcommand{\oarg}[1]{\texttt{[}\meta{#1}\texttt{]}}
180 %
181 %
182 % \maketitle
183 %
184 % \section{Introduction}
185 %
186 % The \pkgname{repltext} packages exposes to \latex\ a relatively obscure
187 % \acronym{PDF} feature: replacement text. When replacement text is
188 % specified for a piece of text, it is the replacement text, not the
189 % typeset text that is copied and pasted. Try selecting and copying the
190 % following sentence and pasting it into some other document:
191 %
192 % \begin{center}
193 % \color{blue}
194 % I love to eat \repltext{ice cream}{celery}.
195 % \end{center}
196 %
197 % If your \acronym{PDF} reader supports replacement text---Adobe Acrobat
198 % and Acrobat Reader currently appear to be the only ones---the pasted
199 % text will say ``ice cream'' instead of ``celery''. Why is this
200 % useful? The \acronym{PDF} specification presents the following usage
201 % model~\cite{Adobe2008:PDF}:
202 %
203 % \begin{quote}
204 % Just as alternate descriptions can be provided for images and other
205 % items that do not translate naturally into text~\dots\ replacement
206 % text can be specified for content that does translate into text but
207 % that is represented in a nonstandard way. These nonstandard
208 % representations might include, for example, glyphs for ligatures or
209 % custom characters, or inline graphics corresponding to letters in
210 % an illuminated manuscript or to dropped capitals.
211 % \end{quote}
212 %
213 % Hence, one might imagine using replacement text in a sentence such as,
214 %
215 % \begin{center}
216 % \color{blue}
217 % Have you ever seen
218 % \repltext{The Artist Formerly Known as Prince}{\Prince}
219 % perform live in concert?
220 % \end{center}
221 %
222 % \noindent
223 % although in the context of \latex, mathematical typesetting
224 % may present a more practical use for replacement text:
225 % ^^A
226 % \[
227 % \color{blue}
228 % \repltext{sum as n goes from 1 to infinty of 1/n^2}{\sum_{n=1}^{\infty}\frac{1}{n^2}}
229 % \]
230 %
231 %
232 % \section{Usage}
233 % \label{sec:usage}
234 %
235 % The \pkgname{repltext} package works only with \latex[pdf] or
236 % \latex[Lua] as it requires certain primitives that only those
237 % \repltext{TeX}{\TeX} engines provide.
238 % To use \pkgname{repltext}, simply include |\usepackage{repltext}| in
239 % your document's prologue. There are currently no package options.
240 %
241 % \begin{decl}
242 % |\repltext|\SpecialUsageIndex{\repltext} \arg{replacement text} \arg{general text}
243 % \end{decl}
244 %
245 % This is the main command defined by \pkgname{repltext}. It takes two
246 % arguments: the replacement text that goes into the copy buffer and
247 % some arbitrary \latex\ code to which the replacement text corresponds.
248 % That \latex\ code is typeset as normal; only its behavior when copied
249 % and pasted is different.
250 %
251 % The replacement text is included verbatim; no characters have any
252 % special meaning to \latex\ with the exception that curly braces must
253 % appear as properly nested, open and close pairs.
254 % For example, \cs{repltext}|{$7| |or| |50%}{|\texttt{seven bucks or half
255 % the total}|}|, produces
256 %
257 % \bigskip
258 % \hfill
259 % {\color{blue}\repltext{$7 or 50%}{seven bucks or half the total}}
260 % \hfill
261 % \makebox[0pt][r]{$\Rightarrow$ \texttt{\$7 or 50\%}}
262 % \bigskip
263 %
264 % \noindent
265 % Because of \meta{replacement text}'s verbatim-like nature, if the
266 % ``|$|'' or ``|%|'' in the preceding \cs{repltext} command were
267 % backslashed, the replacement text would also include a literal
268 % backslash.
269 %
270 % \section{Limitations}
271 %
272 % \pkgname{repltext}'s most severe limitation is the dearth of
273 % \acronym{PDF} readers that support replacement text: as far as I know,
274 % only Adobe Acrobat and Acrobat Reader. A secondary limitation is
275 % that, in the Adobe programs, a selection backed by replacement text
276 % extends only to the first space or kern. This can be somewhat
277 % disconcerting to a person trying to select a piece of text. A
278 % workaround is to try to use only word-for-word substitutions and to
279 % prevent kerning by inserting ``|{}|'' at kerning points (which, alas,
280 % results in inferior typesetting). Contrast selecting ``\texttt{Zippy
281 % drinks \cs{repltext}}|{fine wines}{Valvoline}.|''
282 %
283 % \begin{center}
284 % \color{blue}Zippy drinks \repltext{fine wines}{Valvoline}.
285 % \end{center}
286 %
287 % \noindent
288 % with ``\texttt{Zippy drinks \cs{repltext}}|{fine wines}{V{}alv{}oline}.|''
289 %
290 % \begin{center}
291 % \color{blue}Zippy drinks \repltext{fine wines}{V{}alv{}oline}.
292 % \end{center}
293 %
294 % Yet another limitation, again in the Adobe programs, is that spurious
295 % spaces are sometimes, but not always, introduced into the copy
296 % buffer following a \cs{repltext}. I have yet to determine the source
297 % of those spaces and whether a workaround exists.
298 %
299 % Finally, like |\||verb|, \cs{repltext} does not behave as expected
300 % within an argument to another macro. \cs{repltext} does not currently
301 % detect and warn if it is being used as an argument, but the
302 % replacement text may be altered in surprising and undesirable ways.
303 % Consider, for example, |\fbox{\repltext{###| |BAD_BAD_BAD|
304 % |###}{terrible}}|:
305 %
306 % \bigskip
307 % \hfill
308 % {\color{blue}\fbox{\repltext{### BAD_BAD_BAD ###}{terrible}}}
309 % \hfill
310 % \makebox[0pt][r]{$\Rightarrow$ \texttt{\#\#\#\#\#\# BADBADBAD \#\#\#\#\#\#}}
311 % \bigskip
312 %
313 %
314 % \StopEventually{^^A
315 % \begin{thebibliography}{1}
316 % \bibitem{Adobe2008:PDF}
317 % Adobe Systems, Inc., San Jose, California.
318 % \newblock \emph{Document Management---Portable Document Format---Part 1:
319 % PDF~1.7}, July 2008.
320 % \newblock ISO \mbox{32000-1} standard document. Available from
321 % \url{http://wwwimages.adobe.com/www.adobe.com/content/dam/Adobe/en/devnet/pdf/pdfs/PDF32000_2008.pdf}.
322 % \end{thebibliography}
323 % }
324 %
325 % \section{Implementation}
326 %
327 % This section presents the documented source code for
328 % \pkgname{repltext}. Most users can ignore this section.
329 %
330 % \begin{macro}{\@ifdefined}
331 % I find \cs{@ifdefined} a more natural construct than \cs{@ifundefined}.
332 % \begin{macrocode}
333 \providecommand{\@ifdefined}[3]{\@ifundefined{#1}{#3}{#2}}
334 % \end{macrocode}
335 % \end{macro}
336 %
337 % \begin{macro}{\repl@literal}
338 % \pkgname{repltext} needs a mechanism to insert literal PDF code. This
339 % varies by \TeX\ engine so we have to define \cs{repl@literal} on an
340 % engine-by-engine basis.
341 % \changes{v1.1}{2020/09/25}{Add this macro}
342 % \begin{macrocode}
343 \@ifdefined{pdfliteral}{%
344 % \end{macrocode}
345 % \latex[pdf]
346 % \begin{macrocode}
347 \let\repl@literal=\pdfliteral
348 }{%
349 \@ifdefined{pdfextension}{%
350 % \end{macrocode}
351 % \latex[Lua]
352 % \begin{macrocode}
353 \protected\def\repl@literal{\pdfextension literal}%
354 }{%
355 % \end{macrocode}
356 % Other
357 % \begin{macrocode}
358 \PackageError{repltext}{Unrecognized TeX engine}{%
359 The repltext package currently works only with pdfLaTeX and\MessageBreak
360 LuaLaTeX.\space\space Please use of those engines to build your document.%
361 }%
362 }%
363 }%
364 % \end{macrocode}
365 % \end{macro}
366 %
367 % \pkgname{repltext} additionally needs a mechanism to escape
368 % backslashes and parentheses in a string to make it usable as a PDF
369 % string. This is easy in pdf\LaTeX, which provides
370 % \cs{pdfescapestring}. Unfortunately, to my knowledge, no other
371 % \TeX\ engine provides equivalent functionality. Rather than write our
372 % own function, we leverage \pkgname{hyperref}'s \cs{Hy@pstringdef},
373 % which provides similar functionality.
374 % \begin{macrocode}
375 \RequirePackage{etoolbox}
376 \AtEndPreamble{%
377 \@ifpackageloaded{hyperref}{}{\RequirePackage{hyperref}}%
378 }
379 % \end{macrocode}
380 %
381 % The \cs{repl@text@ii} macro invokes \cs{scalebox}, which is defined by
382 % the \pkgname{graphicx} package.
383 % \begin{macrocode}
384 \RequirePackage{graphicx}
385 % \end{macrocode}
386 %
387 % Replacement text is stored temporarily in \cs{repl@text@toks}.
388 % \begin{macrocode}
389 \newtoks\repl@text@toks
390 % \end{macrocode}
391 %
392 % \begin{macro}{\repltext}
393 % \begin{macro}{\do}
394 % The \cs{repltext} user macro nominally takes as arguments the
395 % replacement text and its visual representation. However, we want the
396 % first argument to be interpreted as text, not as \LaTeX\ code. For
397 % this to work, \cs{repltext} must in fact take no arguments. Instead,
398 % it marks all characters with category code~12 (``other'') except for
399 % curly braces, which retain their original roles. It ends by storing
400 % all characters from ``|{|'' to ``|}|'' (i.e.,~what appears to the
401 % document author to be the first argument to \cs{repltext}) in
402 % \cs{repl@text@toks} and transferring control to the \cs{repl@text@i}
403 % macro.
404 % \begin{macrocode}
405 \newcommand{\repltext}{%
406 \bgroup
407 \let\do=\@makeother
408 \dospecials
409 \catcode`\{=1
410 \catcode`\}=2
411 \afterassignment\repl@text@i
412 \global\repl@text@toks=%
413 }
414 % \end{macrocode}
415 % \end{macro}
416 % \end{macro}
417 %
418 % \begin{macro}{\repl@text@i}
419 % The \cs{repl@text@i} macro ends the group begun by \cs{repltext}.
420 % Doing so restores all characters to their previous category code. It
421 % then transfers control to the \cs{repl@text@ii} macro.
422 % \begin{macrocode}
423 \newcommand{\repl@text@i}{%
424 \egroup
425 \repl@text@ii
426 }
427 % \end{macrocode}
428 % \end{macro}
429 %
430 % \begin{macro}{\repl@text@ii}
431 % \begin{macro}{\repl@escaped}
432 % \cs{repl@text@ii} is the macro that finally outputs something. It
433 % takes ordinary \LaTeX\ code as its argument and writes a PDF
434 % marked-content sequence that uses an \pdfname{ActualText} entry to
435 % indicate that \cs{repltext}'s first argument (currently stored in
436 % \cs{repl@text@toks}) is the replacement text for \cs{repltext}'s
437 % second argument (\cs{repl@text@ii}'s |#1|~argument).
438 % \begin{macrocode}
439 \newcommand{\repl@text@ii}[1]{%
440 \Hy@pstringdef\repl@escaped{\the\repl@text@toks}%
441 \repl@literal{
442 /Span << /ActualText (\repl@escaped) >>
443 BDC
444 }%
445 #1%
446 % \end{macrocode}
447 % It seems that either Adobe Acrobat (or perhaps the \acronym{PDF}
448 % specification itself; I'm not sure) requires the spanned item to
449 % include true \acronym{PDF} text, not just graphics. We therefore
450 % include a microscopic piece of text to satisfy that requirement
451 % without being noticeable.
452 % \begin{macrocode}
453 \scalebox{0.000001}{-}%
454 \repl@literal{EMC}%
455 }
456 % \end{macrocode}
457 % \end{macro}
458 % \end{macro}
459 %
460 % \begin{macro}{\prevrepl}
461 % For the author's convenience we define \cs{prevrepl} to refer to the
462 % previous first argument of \cs{repltext}, interpreted as ordinary
463 % \LaTeX\ code. It is intended to be used in the second argument of
464 % \cs{repltext} to present typeset text that can be copied and pasted like
465 % \LaTeX\ source, as in \cs{repltext}|{$\sum_{i=1}^n|
466 % |\frac{1}{n^2}$}{|\cs{prevrepl}|}| (result:
467 % {\color{blue}\repltext{$\sum_{i=1}^n \frac{1}{n^2}$}{\prevrepl}}).
468 %
469 % Because \cs{prevrepl} requires \cs{scantokens}, this macro requires
470 % \etex\@. Fortunately, all modern \latex[pdf] and \latex[Lua] engines
471 % include \etex\ support.
472 %
473 % \cs{prevrepl} is not currently documented in the author documentation
474 % because I'm not sure it's a sufficiently useful macro to retain in
475 % \pkgname{repltext}. For the time being, I'm leaving it in on the off
476 % chance that someone requests a feature like what \cs{prevrepl} provides.
477 % \begin{macrocode}
478 \newcommand{\prevrepl}{%
479 \expandafter\scantokens\expandafter{\the\repl@text@toks}%
480 }
481 % \end{macrocode}
482 % \end{macro}
483 %
484 % \Finale
485 \endinput