Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 % vim: textwidth=75
3 %<*internal>
4 \iffalse
5 %</internal>
6 %<*readme>
7 |
8 ---------:| ---------------------------------------------------------------
9 proofread:| Commands for inserting annotations
10 Author:| Wybo Dekker
11 E-mail:| [email protected]
12 License:| Released under the LaTeX Project Public License v1.3c or later
13 See:| http://www.latex-project.org/lppl.txt
14
15 Short description:
16 The proofread package defines a few LaTeX commands that are useful
17 when you proofread a latex document. These allow you to easily highlight
18 text and add comments in the margin. Vim escape sequences are provided
19 for inserting these LaTeX commands in the source. The package is based
20 on code for a text highlighting command that was published by Antal
21 Spector-Zabusky in http://tex.stackexchange.com/questions/5959. The main file,
22 proofread.dtx, is self-extracting, so you can generate the style file by
23 compiling proofread.dtx with pdflatex.
24 %</readme>
25 %<*internal>
26 \fi
27 \def\nameofplainTeX{plain}
28 \ifx\fmtname\nameofplainTeX\else
29 \expandafter\begingroup
30 \fi
31 %</internal>
32 %<*install>
33 \input docstrip.tex
34 \keepsilent
35 \askforoverwritefalse
36 \preamble
37 ---------:| ---------------------------------------------------------------
38 proofread:| Commands for inserting annotations
39 Author:| Wybo Dekker
40 E-mail:| [email protected]
41 License:| Released under the LaTeX Project Public License v1.3c or later
42 See:| http://www.latex-project.org/lppl.txt
43
44 \endpreamble
45 \postamble
46
47 Copyright (C) 2017 by Wybo Dekker <[email protected]>
48
49 This work may be distributed and/or modified under the
50 conditions of the LaTeX Project Public License (LPPL), either
51 version 1.3c of this license or (at your option) any later
52 version. The latest version of this license is in the file:
53
54 http://www.latex-project.org/lppl.txt
55
56 This work is "maintained" (as per LPPL maintenance status) by
57 Wybo Dekker.
58
59 This work consists of the file proofread.dtx and a Makefile.
60 Running "make" generates the derived files README, proofread.pdf and
61 proofread.sty.
62 Running "make inst" installs the files in the user's TeX tree.
63 Running "make install" installs the files in the local TeX tree.
64
65 \endpostamble
66
67 \usedir{tex/latex/proofread}
68 \generate{
69 \file{\jobname.sty}{\from{\jobname.dtx}{package}}
70 }
71 %</install>
72 %<install>\endbatchfile
73 %<*internal>
74 \usedir{source/latex/proofread}
75 \generate{
76 \file{\jobname.ins}{\from{\jobname.dtx}{install}}
77 }
78 \nopreamble\nopostamble
79 \usedir{doc/latex/proofread}
80 \generate{
81 \file{README.txt}{\from{\jobname.dtx}{readme}}
82 }
83 \ifx\fmtname\nameofplainTeX
84 \expandafter\endbatchfile
85 \else
86 \expandafter\endgroup
87 \fi
88 %</internal>
89 % \fi
90 %
91 % \iffalse
92 %<*driver>
93 \ProvidesFile{proofread.dtx}
94 %</driver>
95 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
96 %<package>\ProvidesPackage{proofread}
97 %<*package>
98 [2019/04/25 v1.04 Commands for inserting annotations]
99 %</package>
100 %<*driver>
101 \documentclass{ltxdoc}
102 \usepackage[a4paper,margin=25mm,left=50mm,nohead]{geometry}
103 \usepackage[numbered]{hypdoc}
104 \usepackage{microtype}
105 \usepackage{\jobname}
106 \EnableCrossrefs
107 \CodelineIndex
108 \RecordChanges
109 \parindent0pt\parskip2ex
110 \makeatletter
111 \def\com#1{\relax}
112 \begin{document}
113 \DocInput{\jobname.dtx}
114 \end{document}
115 %</driver>
116 % \fi
117 %
118 % \GetFileInfo{\jobname.dtx}
119 % \DoNotIndex{\AtBeginDocument, \DeclareOption, \DeclareRobustCommand,
120 % \DoubleSpacing, \OnehalfSpacing, \PackageError, \ProcessOptions,
121 % \RequirePackage, \advance, \baselineskip, \begin, \bgroup, \coordinate, \def,
122 % \discretionary, \egroup, \else, \end, \endinput, \endpgfextra, \fi, \fill,
123 % \footnotesize, \global, \hbox, \hilite, \ifdef, \ifdim, \ifx, \let, \marginpar,
124 % \marginparmargin, \marginparpush, \mbox, \newbox, \newcommand, \newcount,
125 % \newdimen, \newif, \p, \path, \pgfextra, \raggedright, \renewcommand, \sbox,
126 % \setSpacing, \setstretch, \st, \the, \tikz, \tikzset, \undefined, \usebox,
127 % \usetikzlibrary,\y,
128 % }
129 %
130 %\title{\textsf{proofread} --- Commands for inserting annotations\thanks{This file
131 % describes version \fileversion, last revised \filedate.}
132 %}
133 %\author{Wybo Dekker\thanks{E-mail: [email protected]}}
134 %\date{Released \filedate}
135 %
136 %\maketitle
137 %
138 %\changes{v1.00}{2015/09/06}{First public release}
139 %\changes{v1.01}{2015/12/07}{running counter was sometimes not advanced}
140 %\changes{v1.02}{2017/02/28}{- Now works in tables, footnotes, minipages and more\\
141 % - package options frame, corrected, uncorrected added\\
142 % - package options doublespacing, onehalfspacing added\\
143 % - skp command for manual moving down marginnotes\\
144 % - vim commands are provided for removing notes,\\
145 % either honoring or undoing the correction.}
146 %\changes{v1.03}{2018/07/31}{added warning to use xetex or luatex for non-ASCII
147 % source.}
148 %\changes{v1.04}{2019/04/25}{removed overstriking in the \del command, as
149 % it forces the text on a single line.}
150 %
151 % \begin{abstract}\noindent
152 % The |proofread| package defines a few \LaTeX\ commands that are useful when
153 % you proofread a latex document. These allow you to easily highlight text and
154 % add comments in the margin. Vim escape sequences are provided for inserting or
155 % removing these \LaTeX\ commands in the source. The package is based on code
156 % for a text highlighting command that was published by Antal Spector-Zabusky in
157 % \href{http://tex.stackexchange.com/questions/5959}{StackExchange}.
158 %
159 % Options are provided for displaying the document with extra line spacing,
160 % and for display of it in either uncorrected or corrected state, both
161 % without margin notes.
162 % \end{abstract}
163 %
164 % \section{Usage}
165 % Note: this package is based on the |soul| package, so if you plan to
166 % highlight non-ASCII characters, you must compile your source with either
167 % |xetex|- or |luatex|-based compilers.
168
169 % The commands described below display a highlighted phrase in your
170 % compiled document and place a comment in the margin, prefixed with a
171 % counter, which is indicated with |n| in the following. This
172 % counter is useful in the communication with the author of the document.
173 %
174 % Previous versions of this package used the standard \LaTeX\ |\marginpar| to
175 % create notes in the margin. However, although these will not overwrite each
176 % other, they can not be used in tables, minipages, footnotes and more.
177 % Therefore, this version creates margin notes using the |marginnote| package,
178 % in order to make them work in tables, minipages, footnotes and more. This
179 % implies that margin notes are placed at the vertical position where they are
180 % called, instead of being automatically stacked. So if several notes are
181 % generated on the same line, they overwrite each other. You can prevent this by
182 % \DescribeMacro{skp}
183 % prefixing the second note on the line with |\skp| or |\skp[1]|, the third note
184 % with |\skp[2]| and so on. Multiline notes may need larger numbers.
185 %
186 % The following supposes that you have installed vim-facilities as
187 % described in section~\ref{inst} (``Installing the Vim commands'').
188 %
189 % \DescribeMacro{\del}
190 % |\del{phrase}| displays \del{phrase} and places |n: delete| in the
191 % margin. In the |vim| editor, you can generate this code by selecting the
192 % \DescribeMacro{esc d}
193 % phrase and typing |<escape>d|. After typing this escape sequence, you
194 % will be in normal mode, behind the closing brace.
195 % \DescribeMacro{\yel}
196 % |\yel[comment]{phrase}| displays \yel{phrase} and places
197 % |n: comment| in the margin. In the |vim| editor, you can generate
198 % \DescribeMacro{esc y}
199 % this code by selecting the phrase and typing |<escape>y|.
200 % After typing this escape sequence, you will be in insert mode between the
201 % square bracket pair, ready to insert the \textit{comment}.
202 %
203 % \DescribeMacro{\add}
204 % |\add{phrase}| displays \add{phrase} and places |n: add| in the
205 % margin. In the |vim| editor, you can generate this code \emph{after} the
206 % \DescribeMacro{esc a}
207 % current cursor position by typing |<escape>a|, or \emph{before} the cursor
208 % \DescribeMacro{esc i}
209 % position with |<escape>i|. After typing these escape sequences, you will
210 % be in insert mode between the braces pair, ready to type what should be
211 % added.
212 %
213 % \DescribeMacro{\rep}
214 % |\rep{phrase}{replacement}| displays \rep{phrase}{replacement} and places
215 % |n: was: phrase| in the margin. In the |vim| editor, you can
216 % \DescribeMacro{esc r}
217 % generate this code by selecting the phrase and typing |<escape>r|.
218 % After typing this escape sequence, you will be in insert mode between
219 % the second pair of braces, ready to insert the new content.
220 %
221 % \DescribeMacro{\com}
222 % |\com{comment}| is used by |\del|, |\yel|, |\add|, and |\rep| to place
223 % |n: comment| in the margin. You can use it to place comment in the
224 % margin without text highlighting. In the |vim| editor, you can insert the
225 % \DescribeMacro{esc c}
226 % command by typing |<escape>c|.
227 % After typing this escape sequence, you will be in insert mode between the
228 % braces pair, ready to type your comment.
229 %
230 % \DescribeMacro{\hilite}
231 % |\hilite[options]{phrase}| is the command on which the above commands are
232 % based. It was published by Antal Spector-Zabusky in
233 % \href{http://tex.stackexchange.com/questions/5959}{StackExchange}.
234 % It highlights the phrase with the default colour, yellow, using the
235 % default fill opacity, 0.25; but using the options, you can change this.
236 % For example,
237 % \hilite[fill=blue,draw=yellow,opacity=.5,line width=3pt]{this phrase}
238 % was highlighted with blue, with a 3pt width line in yellow around it,
239 % with the command:
240 %
241 % |\hilite[fill=blue,draw=yellow,opacity=.5,line width=3pt}|
242 %
243 % Both the fill color and the draw color get 50\% opacity, but you can set
244 % each individually with the |fill opacity| and |draw opacity| options.
245 % See the documentation of the tikz package for more options.
246 %
247 % \section{Installing the Vim commands}\label{inst}
248 % The |proofread| distribution comes with a Vimball archive named
249 % |proofread.vmb|. Edit that file in vim and run the command: |:so %|. This will
250 % install the necessary files in your |~/.vim| directory, plus the Ruby executable
251 % |proofread| in your |~/bin| directory. The latter should be in your |PATH| of
252 % course, and you'll have to set its executable flag (|chmod +x ~/bin/proofread|).
253 % Finally, in order to use these facilities, you'll have to add this line
254 % at the end of your Latex source: |% vim: syntax=proofread|.
255 %
256 % The majority of the escape commands that are installed by this
257 % procedure have been described above. However, there are two others:
258 % \DescribeMacro{esc u}
259 % The vim sequence |<escape>u| will \emph{undo} the nearest of the three
260 % letter commands (|\del, \add, \yel, \rep, \com|) described above, which
261 % starts \emph{before} the current cursor position (which may be even on
262 % the first character after the starting |\|). So if it sees
263 % |\del{something}| it will replace that with |something|, and if it sees
264 % |\add{something}| it will remove that.
265 %
266 % \DescribeMacro{esc h}
267 % The counterpart is the |<escape>h| sequence, which will \emph{honor} the
268 % first command found before the cursor. If it sees |\del{something}| it will
269 % remove it, and if it sees |\add{something}| it will replace it with
270 % |something|.
271 % The following table illustrates what happens with these two escape
272 % sequences:
273 %
274 % \begin{tabular}{@{}lll@{}}
275 % &after |<escape>u|&after |<escape>h| \\
276 % |\del{something}| & something & \\
277 % |\add{something}| & &something \\
278 % |\yel{something}| &something &something \\
279 % |\yel[remark]{something}| &something &something \\
280 % |\com{something}| & & \\
281 % |\rep{old}{new}| &old &new \\
282 % \end{tabular}
283 %
284 % As you see, both sequences simply undo |\yel| and |\com| commands, because
285 % they are comments, not corrections.
286 %
287 % \section{Package options}
288 % Options are provided, displaying the document in various spacing and
289 % correction modes.
290 % \DescribeMacro{onehalfspacing}
291 % The |onehalfspacing| option displays the document with 1.5 times the
292 % normal line spacing,
293 % \DescribeMacro{doublespacing}
294 % The |doublespacing| option displays the document with doubled
295 % line spacing.
296 % \DescribeMacro{uncorrected}
297 % The |uncorrected| displays the document in its uncorrected state, without
298 % notes in the margin.
299 % \DescribeMacro{corrected}
300 % The |corrected| displays the document in its corrected state, without
301 % notes in the margin.
302 % \DescribeMacro{frame}
303 % Finally, the |frame| option is provided for visually handicapped users;
304 % it causes .5pt black borders to be drawn around the colored backgrounds
305 % around \hilite[draw=black,line width=.5pt]{marked} texts.
306 %\StopEventually{^^A
307 % \PrintChanges
308 % \clearpage
309 % \PrintIndex
310 %}
311 %
312 % \section{Implementation}
313 %
314 % \begin{macrocode}
315 %<*package>
316 % \end{macrocode}
317 % Option handling:
318 % For the |onehalfspacing| and |doublespacing| options we need the setspace
319 % package, but the memoir class has its own version for this. So if
320 % |\DoubleSpacing| is defined, we redefined the other commands needed.
321 % The |PR@spaced| remembers if margin notes need a shift up.
322 % \begin{macrocode}
323 \RequirePackage{marginnote}
324 \ifx\undefined\DoubleSpacing
325 \RequirePackage{setspace}
326 \else
327 \let\setstretch\setSpacing
328 \let\onehalfspacing\OnehalfSpacing
329 \let\doublespacing\DoubleSpacing
330 \fi
331 \newif\ifPR@spaced\PR@spacedfalse
332 \newdimen\PR@unit\[email protected]\baselineskip
333 \DeclareOption{onehalfspacing}{\onehalfspacing\PR@spacedtrue\[email protected]\baselineskip}
334 \DeclareOption{doublespacing}{\doublespacing\PR@spacedtrue\[email protected]\baselineskip}
335 % \end{macrocode}
336 % The default is to show corrections; the |corrected| and |uncorrected|
337 % options will show the document without those in either corrected of
338 % uncorrected state.
339 % \begin{macrocode}
340 \newif\ifPR@corrected\PR@correctedfalse
341 \newif\ifPR@uncorrected\PR@uncorrectedfalse
342 \DeclareOption{corrected}{\PR@correctedtrue}
343 \DeclareOption{uncorrected}{\PR@uncorrectedtrue}
344 % \end{macrocode}
345 % The frame option draws a black 0.5pt frame around colored areas for
346 % the visually disabled.
347 % \begin{macrocode}
348 \newif\ifPR@frame\PR@framefalse
349 \newdimen\PR@lw\PR@lw=0pt
350 \DeclareOption{frame}{\PR@lw=.5pt\PR@frametrue}
351 \ProcessOptions
352 % \end{macrocode}
353 % The following code for a text highlighting command (here renamed to
354 % |\hilite| was published by Antal Spector-Zabusky in
355 % \href{http://tex.stackexchange.com/questions/5959}{StackExchange}.
356 % \begin{macrocode}
357 \RequirePackage{soul}
358 \RequirePackage{tikz}
359 \usetikzlibrary{calc}
360 \usetikzlibrary{decorations.pathmorphing}
361
362 \newcommand{\PR@defhiliter}[3][]{%
363 \tikzset{every hiliter/.style={fill=#2,fill opacity=#3, #1}}%
364 }
365
366 \PR@defhiliter{yellow}{.25}
367
368 \newcommand{\PR@hilite@Dohilite}{
369 \fill [ decoration = {random steps, amplitude=1pt, segment length=15pt}
370 , outer sep = -15pt, inner sep = 0pt, decorate
371 , every hiliter, this hiliter ]
372 ($(begin hilite)+(0,8pt)$) rectangle ($(end hilite)+(0,-3pt)$) ;
373 }
374
375 \newcommand{\PR@hilite@Beginhilite}{
376 \coordinate (begin hilite) at (0,0) ;
377 }
378
379 \newcommand{\PR@hilite@Endhilite}{
380 \coordinate (end hilite) at (0,0) ;
381 }
382
383 \newdimen\PR@hilite@previous
384 \newdimen\PR@hilite@current
385 % \end{macrocode}
386
387 % \begin{macro}{\hilite}
388 % \begin{macrocode}
389 \DeclareRobustCommand*\hilite[1][]{%
390 \ifPR@frame%
391 \tikzset{this hiliter/.style={#1,draw=black,line width=\PR@lw}}%
392 \else%
393 \tikzset{this hiliter/.style={#1}}%
394 \fi
395 \SOUL@setup
396 %
397 \def\SOUL@preamble{%
398 \begin{tikzpicture}[overlay, remember picture]
399 \PR@hilite@Beginhilite
400 \PR@hilite@Endhilite
401 \end{tikzpicture}%
402 }%
403 %
404 \def\SOUL@postamble{%
405 \begin{tikzpicture}[overlay, remember picture]
406 \PR@hilite@Endhilite
407 \PR@hilite@Dohilite
408 \end{tikzpicture}%
409 }%
410 %
411 \def\SOUL@everyhyphen{%
412 \discretionary{%
413 \SOUL@setkern\SOUL@hyphkern
414 \SOUL@sethyphenchar
415 \tikz[overlay, remember picture] \PR@hilite@Endhilite ;%
416 }{%
417 }{%
418 \SOUL@setkern\SOUL@charkern
419 }%
420 }%
421 %
422 \def\SOUL@everyexhyphen##1{%
423 \SOUL@setkern\SOUL@hyphkern
424 \hbox{##1}%
425 \discretionary{%
426 \tikz[overlay, remember picture] \PR@hilite@Endhilite ;%
427 }{%
428 }{%
429 \SOUL@setkern\SOUL@charkern
430 }%
431 }%
432 %
433 \def\SOUL@everysyllable{%
434 \begin{tikzpicture}[overlay, remember picture]
435 \path let \p0 = (begin hilite), \p1 = (0,0) in \pgfextra
436 \global\PR@hilite@previous=\y0
437 \global\PR@hilite@current =\y1
438 \endpgfextra (0,0) ;
439 \ifdim\PR@hilite@current < \PR@hilite@previous
440 \PR@hilite@Dohilite
441 \PR@hilite@Beginhilite
442 \fi
443 \end{tikzpicture}%
444 \the\SOUL@syllable
445 \tikz[overlay, remember picture] \PR@hilite@Endhilite ;%
446 }%
447 \SOUL@
448 }
449 % \end{macrocode}
450 % \end{macro}
451 % Reduce minimum vertical space between margin paragraphs; if the memoir
452 % class is active, use the outer margin:
453 % \begin{macrocode}
454 \AtBeginDocument{\marginparpush2pt}
455 \ifx\undefined\marginparmargin\else\marginparmargin{outer}\fi
456 % \end{macrocode}
457 % We need a save box and a counter for prefixing the margin paragraphs:
458 % \begin{macrocode}
459 \newcount\PR@markerno\PR@markerno=1
460 % \end{macrocode}
461 % \begin{macro}{\com}
462 % Make a raggedright margin note, in footnote fontsize, prefixed with the counter
463 % plus a colon:
464 % \begin{macrocode}
465 \newcommand{\com}[1]{%
466 \marginnote{%
467 \setstretch{1}%
468 \raggedright%
469 \footnotesize%
470 \the\PR@markerno: #1%
471 }[\PR@skip]%
472 \global\PR@skip0pt
473 \global\advance\PR@markerno1%
474 }
475 % \end{macrocode}
476 % \end{macro}
477 % \begin{macro}{\skp}
478 % \begin{macrocode}
479 \newdimen\PR@skip\PR@skip0\PR@unit
480 \newcommand{\skp}[1][1]{%
481 \PR@skip#1\PR@unit%
482 }
483 % \end{macrocode}
484 % \end{macro}
485 % \begin{macro}{\del}
486 % \begin{macrocode}
487 \newcommand{\del}[1]{%
488 \com{delete}%
489 \hilite[red]{#1}%
490 }
491 % \end{macrocode}
492 % \end{macro}
493 % \begin{macro}{\yel}
494 % \begin{macrocode}
495 \newcommand{\yel}[2][]{%
496 \com{#1}%
497 \hilite{#2}%
498 }
499 % \end{macrocode}
500 % \end{macro}
501 % \begin{macro}{\add}
502 % \begin{macrocode}
503 \newcommand{\add}[1]{%
504 \com{add}%
505 \hilite[green]{#1}%
506 }
507 % \end{macrocode}
508 % \end{macro}
509 % \begin{macro}{\rep}
510 % \begin{macrocode}
511 \newcommand{\rep}[2]{%
512 \com{was: #1}%
513 \hilite[blue]{#2}%
514 }
515 % \end{macrocode}
516 % If one of the |corrected| or |uncorrected| options is used, redefine the
517 % above commands accordingly:
518 % \begin{macrocode}
519 \ifPR@uncorrected
520 \ifPR@corrected
521 \PackageError{proofread}{You may not use both the corrected and uncorrected options}
522 \fi
523 \def\com#1{} \def\add#1{} \def\del#1{#1} \def\rep#1#2{#1}
524 \renewcommand{\yel}[2][]{#2}\renewcommand{\hilite}[2][]{#2}
525 \else
526 \ifPR@corrected
527 \def\com#1{} \def\add#1{#1} \def\del#1{} \def\rep#1#2{#2}
528 \renewcommand{\yel}[2][]{#2}\renewcommand{\hilite}[2][]{#2}
529 \fi
530 \fi
531
532 \endinput
533 %</package>
534 % \end{macrocode}
535 % \end{macro}
536 %\Finale