Debian Codegraph @

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

raw
1 % \iffalse
2 % This is versonotes.dtx, which supports adding notes on verso pages,
3 % opposite annotation on the recto pages. Still sketchy
4 %%
5 %% Release version 0.5, 2023 December 31.
6 %%
7 %% Copyright 2014, 2015, 2019, 2023 Norman Gray <https://nxg.me.uk>
8 %%
9 %% This work may be distributed and/or modified under the
10 %% conditions of the LaTeX Project Public License, either version 1.3
11 %% of this license or (at your option) any later version.
12 %% The latest version of this license is in
13 %% http://www.latex-project.org/lppl.txt
14 %% and version 1.3 or later is part of all distributions of LaTeX
15 %% version 2005/12/01 or later.
16 %%
17 %% This work has the LPPL maintenance status `maintained'.
18 %%
19 %% The Current Maintainer of this work is Norman Gray
20 %%
21 %% This work consists of the files versonotes.dtx and versonotes.ins
22 %% and the derived file versonotes.sty.
23 %%
24 %%%% File: versonotes.dtx
25
26 %<+package|driver|example>%%%% Source: b86314fff92e, 2023-12-31T14:55:52+00:00
27 %%
28 %<+package>\NeedsTeXFormat{LaTeX2e}
29 %<+package>\ProvidesPackage{versonotes}[2023/12/31 v0.5]
30 %
31 %<*driver>
32 \documentclass{ltxdoc}
33 \title{versonotes: Notes on verso pages}
34 \author{Norman Gray\\\url{https://nxg.me.uk}}
35 \date{Release 0.5, 2023 December 31}
36 \usepackage{url}
37 \newcommand\Lopt[1]{\textsf {#1}} % options
38 \newcommand\file[1]{\texttt {#1}}
39 \newcommand\Lcount[1]{\textsl {\small#1}}
40 \newcommand\Lenv[1]{\texttt{\{#1\}}} %environments
41 \newcommand\Lpackage[1]{\{\textsf{#1}\}} %packages
42 %Make command strings easier to write
43 %{\catcode`\<=\active \gdef<#1>{\meta{#1}}}
44 {\catcode`\<=\active
45 \gdef<#1>{{\ensuremath\langle\normalfont\textsl{#1}\ensuremath\rangle}}}
46 \def\cmd{\begingroup
47 \catcode`\\=12 \catcode`\{=12 \catcode`\}=12
48 \catcode`\<=\active \catcode`\|=12
49 \docmd}
50 \def\docmd|#1|{\texttt{#1}\endgroup}
51 %%% \url macro (url.sty does this better)
52 %\def\setpathdots{\discretionary{.}{}{.}}
53 %\def\setpathslash{\discretionary{/}{}{/}}
54 %{\catcode`\.=\active
55 % \catcode`\/=\active
56 % \gdef\pathcats{%
57 % \catcode`\%=12 \catcode`\~=12
58 % \catcode`\.=\active \let.\setpathdots
59 % \catcode`\/=\active \let/\setpathslash
60 % \catcode`\#=12 \catcode`\_=12}%
61 % }
62 %\def\setpath#1{\ttfamily <\nobreak #1\nobreak>\endgroup}
63 %\def\url{\begingroup\pathcats\setpath}
64
65 \def\bs{$\backslash$}
66
67 \begin{document}
68 \maketitle
69 %\tableofcontents
70 %\bigskip
71 \DocInput{versonotes.dtx}
72 \end{document}
73 %</driver>
74 %
75 % \fi
76 %
77 % \noindent This package allows you to place notes on the verso pages
78 % of an otherwise single-sided document. If, in the run
79 % of text, you include a call to the macro
80 % |\versonote{This is a remark}|,
81 % then that text will be placed on the opposite (ie, `verso') page,
82 % lined up with the macro call.
83 % The notes may contain more than one paragraph.
84 %
85 % All the pages in the document appear as recto pages
86 % (ie, right-hand pages),
87 % and are numbered as such;
88 % the document should be formatted with that in mind.
89 %
90 % Since there is no page opposite the first page, any notes which are
91 % positioned to appear opposite page 1 are silently discarded.
92 %
93 % To invoke the package, use the command |\usepackage{versonotes}|.
94 %
95 % It is possible to start the document other than on page one. To do
96 % this, you can call |\setcounter{page}{|\emph{n}|}| as usual, but it
97 % must be done \emph{before} the line |\usepackage{versonotes}|. The
98 % package may get confused if the page number is changed at other times.
99 %
100 % If two notes come too close after one another, the second would
101 % overprint the first if we did not take steps to avoid this. By
102 % default, they are separated from each other by a short horizontal
103 % line, but if the \Lopt{mergecollisions} option is provided when
104 % loading the package, then such notes are instead merged into a
105 % single block of text. If a sequence of notes needs to be merged,
106 % then they will be added to the merged block one at a time in
107 % successive \LaTeX\ runs, since merging one note may make it
108 % unnecessary to merge the next. If a large block of such notes need
109 % to be merged, it will therefore take several runs before the package
110 % finds a stable state. If you find yourself inconvenienced by this,
111 % it sounds as if you are preparing a critical edition, and you might
112 % want to venture into a closer relationship with the
113 % \Lpackage{reledmac}
114 % package.\footnote{\texttt{https://www.ctan.org/pkg/reledmac} -- this
115 % is the current incarnation, as of 2023, of the eledmac, ledmac and
116 % edmac packages for scholarly editions.}.
117 %
118 % \emph{Note}:
119 % If we have a long versonote at the bottom of a page, then we
120 % don't try to spill over onto the next (that would be possible to
121 % implement, but would be a significant jump in complication). We
122 % regard this situation as one for the user to work out for themself,
123 % perhaps with some strategic page-breaks.
124 %
125 % The dimensions |\versoleftmargin| and |\versotextwidth| specify the
126 % position of the text block on the verso page. The defaults for
127 % these are based on the |\textwidth| and |\evensidemargin| of the
128 % document \emph{at the time the package is loaded}.
129 % By default, verso paragraphs are set ragged-left; with the
130 % declarations in |\versolayout| setting the paragraph parameters.
131 % You may reset the first two dimensions with for example
132 % |\versoleftmargin=4cm|, and use |\renewcommand\versolayout{...}| to
133 % override the paragraph formatting (this will typically require
134 % changing |\rightskip|, |\leftskip| and |\parfillskip|). For more
135 % elaborate effects (for example changing the note font size and
136 % spacing), you will need to redefine |\versolayout|.
137 %
138 % \subsection*{Recto notes}
139 %
140 % If the package is invoked with the \Lopt{rectonotes} option, then it
141 % runs in a complementary mode in which the notes are placed on the
142 % recto page (the right-hand one) instead of the verso. The default
143 % |\versolayout| in this case (which of course is really a recto
144 % layout) is slightly different, and is based on the preexisting
145 % document |\oddsidemargin|. All the pages in the document (apart
146 % from the front page) are then formatted as verso pages, though still
147 % only the non-note pages are numbered.
148 %
149 % In this mode, the `add a note' command is still called
150 % |\versonote|. You may find it convenient to rename that with
151 % |\let\rectonote = \versonote| or |\let\sidenote = \versonote|.
152 %
153 % \subsection*{Notes}
154 % \begin{itemize}
155 % \item The package uses the |\pdfsavepos| primitive (or the
156 % Lua\TeX\ equivalent), and so requires \texttt{pdflatex},
157 % \texttt{xelatex}, or \texttt{lualatex}. In practice, this should
158 % mean that it will work with any reasonably current \LaTeX\ engine.
159 %
160 % \item The notes are handled using the |.aux| file, and so (i) they will
161 % only appear on the second and subsequent runs; and (ii) they will be
162 % located opposite the position where the |\versonote| macro was
163 % called on the \emph{previous} run.
164 %
165 % \item If notes collide, you may well have to re-run \LaTeX\ several
166 % times. There is quite a lot of state in the |.aux| file.
167 %
168 % \item The package is available on CTAN at
169 % \texttt{macros/latex/contrib/versonotes/}. The source is hosted at
170 % \url{https://heptapod.host/nxg/versonotes/}.
171 %
172 % \end{itemize}
173 %
174 % \subsection*{Acknowledgements, and release notes}
175 %
176 % \iffalse @RELEASENOTES@ \fi
177 %
178 %
179 % Thanks to Thomas H. Luxon for permission to include the
180 % Dartmouth Milton text\footnote{\url{https://milton.host.dartmouth.edu/}} of
181 % ‘Paradise Lost’ notes in the sample text.
182 %
183 % \begin{description}
184 % \item[Version 0.5, 2023 December 31]\relax
185 % \leavevmode\begin{itemize}
186 % \item Now compatible with LuaTeX.
187 % \item Now uses L3-style hooks, but retains compatibility with pre-2020 engines.
188 % \item Updated the links to the repository, and to the Dartmouth Milton text.
189 % \end{itemize}
190 % \item[Version 0.4, 2019 July 6]\relax
191 % Support changing the initial page number
192 % (thanks to P J Couch for the suggestion).
193 % \item[Version 0.3, 2015 December 8]\relax
194 % \leavevmode\begin{itemize}
195 % \item Minor documentation adjustments.
196 % \item Added the [rectonotes] option
197 % (thanks to Axel Berger for this suggestion).
198 % \end{itemize}
199 % \item[Version 0.2, 2015 February 16]\relax
200 % Initial public release.
201 % \end{description}
202 %
203 %
204 % \StopEventually{}
205
206 % \newpage
207 % \section{Implementation}
208 %
209 % \begin{macrocode}
210 %<*package>
211 % \end{macrocode}
212 %
213 % The package contains a single user-visible command, and three
214 % configuration parameters.
215 %
216 % The normal behaviour of this package is to place notes on the verso
217 % page (ahem, hence the name). But we can swap that around.
218 % \begin{macrocode}
219 \newif\if@verso@notesonleft
220 \@verso@notesonlefttrue
221 % \end{macrocode}
222 %
223 % Define configuration options for the user:
224 % \begin{macrocode}
225 \def\verso@resetmergestate{\verso@mergestate=2}
226 \DeclareOption{mergecollisions}{\def\verso@resetmergestate{\verso@mergestate=0}}
227 \DeclareOption{rectonotes}{\@verso@notesonleftfalse}
228 \ProcessOptions
229 % \end{macrocode}
230 %
231 % The single user-visible command is |\versonote|.
232 % Use |\unexpanded| (from e-\TeX) so that macros in the argument are
233 % not expanded into the aux file.
234 % \begin{macrocode}
235 \long\def\versonote#1{\@bsphack
236 \pdfsavepos
237 \write\@auxout{\string\verso@note{\the\c@page}{\the\pdflastypos sp}\unexpanded{{#1}}}%
238 \@esphack}
239 % \end{macrocode}
240 %
241 % \subsection{Housekeeping: sizes and sentinels}
242 %
243 % Now the layout parameters, and defaults.
244 % The dimensions |\versoleftmargin| and |\versotextwidth| specify the
245 % position of the text block on the verso page, and the declarations
246 % in |\versolayout| set the paragraph parameters.
247 % \begin{macrocode}
248 \newdimen\versotextwidth
249 \versotextwidth=\textwidth
250 \newdimen\versoleftmargin
251 \versoleftmargin=\paperwidth
252 \advance\versoleftmargin -\textwidth
253 \advance\versoleftmargin -\hoffset
254 \advance\versoleftmargin -1in
255 \if@verso@notesonleft
256 \advance\versoleftmargin -\evensidemargin
257 \def\versolayout{
258 \leftskip=0pt plus 1fil
259 \rightskip=0pt
260 \parfillskip=0pt
261 \parindent=0pt
262 \parskip=\medskipamount
263 }
264 \else
265 \advance\versoleftmargin -\oddsidemargin
266 \def\versolayout{
267 \leftskip=0pt
268 \rightskip=0pt plus 4em
269 \parindent=0pt
270 \parskip=\medskipamount
271 }
272 \fi
273 % \end{macrocode}
274 %
275 % Add a sentinel at the end of the document
276 % \begin{macrocode}
277 \def\end@versonote{%
278 \write\@auxout{\string\verso@note{\the\c@page}{-1pt}{}}}
279 \AtEndDocument{\end@versonote}
280 % \end{macrocode}
281 %
282 % Define various bits of working storage.
283 %
284 % The |\verso@pages| token list needs to have an extra leading `page'
285 % since the logic in |\verso@processonepage@| can skip it.
286 % \begin{macrocode}
287 \newtoks\verso@pages
288 \if@verso@notesonleft
289 \verso@pages={}
290 \else
291 \verso@pages={{}}
292 \fi
293 % \end{macrocode}
294 % Notes on a single page (which is kept track of by
295 % |\verso@currentpagenum| are assembled into |\verso@currentpage|
296 % before being transferred as a unit into |\verso@pages|.
297 % \begin{macrocode}
298 \newtoks\verso@currentpage
299 % \end{macrocode}
300 % We keep track of page numbers when invoking |\verso@note| below. We
301 % initialise this to be the current page number (typically~1). Doing
302 % this this way means that if the document sets the current page
303 % number using |\setcounter{page}{n}| \emph{before} loading the
304 % package, then we will respect that. We will get confused if the
305 % page number is changed at other points.
306 % \begin{macrocode}
307 \newcount\verso@currentpagenum
308 \verso@currentpagenum=\c@page
309 \newcount\verso@currentnotenum
310 \verso@currentnotenum=0
311 \newdimen\verso@spacerskip
312 \verso@spacerskip=10pt
313 % \end{macrocode}
314 % Flag |\if@verso@processversonotes| is set true if there are any
315 % |\verso@note|s found in the aux file. If there are none -- so that
316 % this is still false at the first |\shipout| -- then the package
317 % carefully does nothing.
318 % \begin{macrocode}
319 \newif\if@verso@processversonotes
320 \@verso@processversonotesfalse
321 % \end{macrocode}
322 %
323 % We need to be able to calculate our position on the page.
324 % The |\verso@pagebottom| is the position of the bottom of the page,
325 % in the same coordinates as |\verso@currentposition|, and is
326 % (textheight + top margin + \dots).
327 % \begin{macrocode}
328 \newdimen\verso@pagebottom
329 \verso@pagebottom=1in
330 \advance\verso@pagebottom \topskip
331 \advance\verso@pagebottom \topmargin
332 \advance\verso@pagebottom \headheight
333 \advance\verso@pagebottom \headsep
334 \advance\verso@pagebottom \textheight
335 \newdimen\verso@currentposition
336 % \end{macrocode}
337 % The paper size options to class files set |\paperheight| but not (or
338 % not necessarily) |\pdfpageheight|. If we don't set this, then
339 % output vertical positions will come out incorrectly if the latter
340 % parameter doesn't default to the right value. Lua\TeX\ and pdf\TeX\
341 % (which includes Xe\TeX\ for this purpose) have slightly different
342 % ways of organising page sizes, so we do have to conditionalise.
343 % Here, we assume that everything that isn't Lua\TeX\ is pdf\TeX-like
344 % enough that it has |\pdfpageheight|.
345 % \begin{macrocode}
346 \RequirePackage{iftex}
347 \ifluatex
348 \typeout{Detected LuaTeX}
349 \pageheight=\paperheight
350 \let\pdfsavepos=\savepos
351 \let\pdflastypos=\lastypos
352 \else
353 \pdfpageheight=\paperheight
354 \fi
355 % \end{macrocode}
356 %
357 % \subsection{Core logic}
358 %
359 % Macro |\verso@note| is what's written to the aux file, and so is
360 % what we process on the next run, to discover the set of verso-notes
361 % we need to produce.
362 % \begin{macrocode}
363 \long\def\verso@note#1#2#3{%
364 \global\@verso@processversonotestrue
365 % \end{macrocode}
366 % Store the target page number. It would be nice to issue a warning if this is
367 % indicated to appear on the (ignored) first page; such notes are
368 % silently discarded below. However detecting this here requires that
369 % |\@tempcnta| is equal to~1 on the call of this, and we can't
370 % guarantee this if we support calling |\setcounter{page}{x}| before
371 % loading the package.
372 % \begin{macrocode}
373 \@tempcnta=#1
374 % \end{macrocode}
375 % Gather pages from the .aux file, assembling them into a single list
376 % in |\verso@pages| with one group per page, each containing a
377 % sequence of |\\{...}| note specifications. This inserts empty
378 % groups for pages which have no verso-notes.
379 % \begin{macrocode}
380 \@tempdima=#2 % #2 < 0pt is the end-of-document flag
381 \loop
382 \@tempswafalse
383 \ifnum\@tempcnta > \verso@currentpagenum
384 \@tempswatrue
385 \fi
386 \ifdim\@tempdima < 0pt
387 \@tempswatrue
388 \@tempdima=0pt
389 \fi
390 \if@tempswa
391 \edef\@tempa{\the\verso@pages {\the\verso@currentpage}}
392 \global\verso@pages=\expandafter{\@tempa}
393 \advance\verso@currentpagenum 1
394 \verso@currentpage={}
395 \repeat
396 \verso@currentpage=\expandafter{\the\verso@currentpage \\{{#1}{#2}{#3}}}
397 % \end{macrocode}
398 % The last time around, add an extra pair of tokens at the end of the
399 % |\verso@pages| list. These provide the arguments to
400 % |\verso@processonepage@| on the last time it's called.
401 % \begin{macrocode}
402 \ifdim\@tempdima=0pt
403 \global\verso@pages=\expandafter{\the\verso@pages {}{}}
404 \fi
405 }
406 % \end{macrocode}
407 %
408 % Disable |\verso@note| in time for the end-document aux reading.
409 % This isn't quite necessary, but it's tidy.
410 % \begin{macrocode}
411 \AtEndDocument{\long\def\verso@note#1#2#3{}}
412 % \end{macrocode}
413 %
414 % Test whether we want to merge the current note with the following
415 % one. The arguments to this macro are the contents of
416 % |\verso@mergenotelist|, which is assembled from the
417 % |\verso@mergenote| commands read from the aux file.
418 % \begin{macrocode}
419 \def\verso@testmergenote#1,#2\@nil{
420 \def\@tempa{#1}
421 \ifx\@tempa\@empty
422 \@tempcnta=-1
423 \else
424 \@tempcnta=#1
425 \fi
426 \advance\@tempcnta -1
427 \ifnum\@tempcnta=\verso@currentnotenum
428 % \end{macrocode}
429 % Set |\if@tempswa| true, set |\verso@mergenotelist| to the tail of
430 % the list, and ensure that this note is merged next time round.
431 % \begin{macrocode}
432 \@tempswatrue
433 \xdef\verso@mergenotelist{#2}
434 \immediate\write\@auxout{\string\verso@mergenote{#1}}
435 \else
436 \@tempswafalse
437 \fi
438 }
439 % \end{macrocode}
440 %
441 % The macro |\verso@setnote| is the one which does the work of
442 % positioning a single note on the (verso) page. We potentially work
443 % quite hard to avoid notes overwriting each other here. If
444 % |\verso@mergestate| is greater than one (by default, it's
445 % initialised to~2, but any number greater than~1 would be equivalent)
446 % then when two notes collide, we simply put a horizontal bar between
447 % them, and hope for the best. Each time we have a collision we
448 % increment this number, and if we find it has a value~1 (ie, the
449 % first collision) we we record in the aux file that this note should
450 % be merged with its predecessor, by writing a |\verso@mergenote|
451 % command. Next time round, when we are about to set the note
452 % \emph{before} that one, we avoid setting it, and instead start
453 % accumulating the text of such merged notes, in the token register
454 % |\verso@accumulatenote|. We only add a single note to the list of
455 % merged notes on each \LaTeX\ run, since merging one note may make it
456 % unnecessary to merge any more. The only way to delete the
457 % collections of merged notes is to delete the aux file.
458 % \begin{macrocode}
459 \newcount\verso@mergestate
460 \verso@resetmergestate
461 \newtoks\verso@accumulatenote
462 \verso@accumulatenote={}
463 % \end{macrocode}
464 %
465 % Set the note. The arguments are (1) the page number, (2) the
466 % position on the page, and (3) the text of the note.
467 % \begin{macrocode}
468 \long\def\verso@setnote#1#2#3{
469 \@tempdima=\paperheight \advance\@tempdima -#2
470 % target position; will become skip to add
471 \@tempdimb=\verso@currentposition
472 \global\advance\verso@currentnotenum 1
473 % \end{macrocode}
474 % Check whether we're to merge the following note into this one.
475 % \begin{macrocode}
476 \expandafter\verso@testmergenote\verso@mergenotelist,\@nil
477 \if@tempswa
478 \verso@accumulatenote=\expandafter{%
479 \the\verso@accumulatenote
480 #3%
481 \quad\P~\nobreak}
482 %\PackageInfo{versonotes}{\typeout{Merging notes on p#1}}
483 \else
484 % \end{macrocode}
485 % No merging: set the current note, possibly along with any
486 % accumulated notes, in a box, and then start to work out where to put it.
487 % \begin{macrocode}
488 \setbox0=\vtop{
489 \versolayout
490 \the\verso@accumulatenote
491 #3\par}
492 \verso@accumulatenote={}
493 % \end{macrocode}
494 % We now know how big this box is (|\ht0|), how far down the page the
495 % accumulated boxes are (|\verso@currentposition|), and where the box
496 % is to appear, as an offset from the top of the paper (|\@tempdima|).
497 % Work how how much of a skip we have to add to get there.
498 % \begin{macrocode}
499 \ifdim\@tempdima>\verso@currentposition
500 % \end{macrocode}
501 % The target position is below the current position; add a skip. This
502 % is the straightforward case, and leaves the skip in |\@tempdima| and
503 % the new current position in |\@tempdimb|.
504 % \begin{macrocode}
505 \advance\@tempdima -\verso@currentposition
506 \advance\@tempdima -\ht0
507 \advance\@tempdimb \@tempdima
508 \verso@resetmergestate
509 \else
510 % \end{macrocode}
511 % Or the target position is above the current position;
512 % thus the new material will have to be moved down
513 % (I'm not sure how best to handle the case where this skip results
514 % in the note hitting the bottom of the page. Should it be merged
515 % with that case below, somehow?).
516 % \begin{macrocode}
517 % note: \PackageWarning seems to produce odd effects here
518 \message{^^Jversonotes warning: Moved versonote text on p.#1.}
519 \advance\verso@mergestate 1
520 \ifnum\verso@mergestate=1
521 \immediate\write\@auxout{\string\verso@mergenote{\the\verso@currentnotenum}}
522 \fi
523 \nointerlineskip
524 \vbox to \verso@spacerskip{\vfil
525 \hbox to \hsize{\hfil\vrule height 0.4pt width 10em}
526 \vfil}
527 \advance\@tempdimb \verso@spacerskip
528 \@tempdima=0pt % ...so don't add any more skip
529 \fi
530 \advance\@tempdimb \ht0
531 \advance\@tempdimb \dp0
532 % \end{macrocode}
533 % Parameter |\@tempdimb| now holds the expected new value of
534 % |\verso@currentposition|. Check to see if this would be beyond the bottom
535 % of the page, and move the text upwards in that case.
536 % \begin{macrocode}
537 \ifdim\@tempdimb>\verso@pagebottom
538 \message{^^Jversonotes warning: versonote text on p.#1 hit bottom of page.}
539 \advance\@tempdima -\@tempdimb
540 \advance\@tempdima \verso@pagebottom
541 \@tempdimb=\verso@pagebottom
542 \fi
543 % \end{macrocode}
544 % Finally, do the skip and add the box.
545 % \begin{macrocode}
546 \vskip\@tempdima
547 \verso@currentposition=\@tempdimb
548 \nointerlineskip
549 \box0
550 \fi
551 }
552 % \end{macrocode}
553 %
554 % Log notes where a previous run has discovered they collide.
555 % \begin{macrocode}
556 \def\verso@mergenotelist{}
557 \def\verso@mergenote#1{\xdef\verso@mergenotelist{\verso@mergenotelist #1,}}
558 % \end{macrocode}
559 %
560 % \subsection{Overall processing logic, and shipout}
561 %
562 % We want to use the current shipout mechanism, but also to remain
563 % compatible with pre-2020 \LaTeX, so conditionalise appropriately.
564 % Note that we can't use the (apparently preferable)
565 % |\IfFormatAtLeastTF| command to do this test: we want to continue to
566 % work even when we're using a \LaTeX\ which is too old for this
567 % command to be defined.
568 % \begin{macrocode}
569 \newif\ifverso@Liii
570 \@ifl@t@r\fmtversion{2020/10/01}\verso@Liiitrue\verso@Liiifalse
571 \PackageInfo{versonotes}
572 {choosing support for \ifverso@Liii L3\else pre-L3\fi}
573 % \end{macrocode}
574 %
575 % For the L3 case, we will use the |shipout/before| hook, and use
576 % |\RawShipout| to output the separate versonotes pages.
577 % See the \texttt{ltshipout-doc} documentation for details.
578 % But in the pre-L3 case, save the original definition of |\shipout|
579 % (using the L3 |\RawShipout| name for clarity),
580 % prior to our redefining it below.
581 % We could do this perfectly well using the \Lpackage{everyshi} package,
582 % but we do it by hand in order to avoid the extra dependency.
583 % \begin{macrocode}
584 \ifverso@Liii\else
585 \let\RawShipout\shipout
586 \fi
587 % \end{macrocode}
588 %
589 % We process the versonotes a page at a time. We don't have to do
590 % anything clever, because the page that a versonote lands on is
591 % governed by the page that the |\versonote| call appears on. If we
592 % have a long versonote at the bottom of a page, then we don't try to
593 % spill over onto the next (that would presumably be possible, using
594 % the inserts mechanism, but would be a significant jump in
595 % complication). We regard this situation as one for the user to work
596 % out for themself.
597 %
598 % Macro |\verso@processonepage@| consumes the next group in the
599 % |\verso@pages| list.
600 %
601 % Macro |\verso@processonepage| is called just before each shipout of
602 % a `real' page, as the content of the \texttt{shipout/before} hook
603 % (or as part of the redefined |\shipout| in the pre-L3 case).
604 % If we are putting notes on verso pages
605 % (ie, the usual case, as opposed to recto notes),
606 % then \emph{before} we ship out page~2, we must construct and
607 % ship out the notes for page~2; we will have a set of notes for
608 % page~1 (which we expect will be empty), which we must discard; we
609 % achieve this by simply doing nothing if the current page is page~1.
610 % If, on the other hand, we are putting notes on recto pages, then we
611 % must instead ship out the notes for page~2 just before shipping out page~3, and
612 % must similarly do nothing on pages~1 and~2. This works because
613 % in the latter case we have initialised |\verso@pages| with an extra
614 % leading |{{}}|.
615 %
616 % We manage the page skipping by decrementing a `pages to skip'
617 % counter. The more obvious way of doing that it to test the value of
618 % |\@tempcnta|, which at this point holds the current page number, but
619 % this produces the wrong answer if the document starts at other than
620 % page~1 (perhaps because the document includes |\setcounter{page}{99}|).
621 % \begin{macrocode}
622 \newcount\verso@pagestoskip
623 \if@verso@notesonleft
624 \verso@pagestoskip=1
625 \else
626 \verso@pagestoskip=2
627 \fi
628 % \end{macrocode}
629 %
630 % Define |\verso@processonepage@|.
631 % \begin{macrocode}
632 \long\def\verso@processonepage@#1#2\@nil{
633 \def\@tempa{#1}
634 % \end{macrocode}
635 % Do nothing on page~1 (in the verso case), or pages~1 and~2 (in the
636 % recto case). Any notes which would appear in such a position are
637 % silently discarded.
638 % \begin{macrocode}
639 \ifnum\verso@pagestoskip=0
640 % \end{macrocode}
641 % If there are no verso-notes on this page, then ship out an empty box.
642 % \begin{macrocode}
643 \ifx\@tempa\@empty
644 \RawShipout\vbox{}
645 % \end{macrocode}
646 % This is the normal case:
647 % create a box containing the |\\{...}| contents of the
648 % current page's verso-notes
649 % \begin{macrocode}
650 \else
651 \begingroup
652 % \end{macrocode}
653 % Within the box we're about to create, we have to `un-protect' things.
654 % Robust commands (including for example |\emph| and other font-changing commands) are
655 % defined using |\protect|, which in the present context, inside
656 % |\@outputpage|, is |\let| equal to |\noexpand|.
657 % We must set this to be simply |\relax|,
658 % as it is in the normal run of text elsewhere
659 % (see \url{http://tex.stackexchange.com/questions/206673/}).
660 % \begin{macrocode}
661 \let\protect\relax
662 % \end{macrocode}
663 % Set everything up for setting the verso page.
664 % \begin{macrocode}
665 \hoffset=-1in \advance\hoffset \versoleftmargin
666 \voffset=-1in
667 \hsize=\versotextwidth
668 \topskip=0pt
669 \topmargin=0pt
670 \headheight=0pt
671 \headsep=0pt
672 \vsize=1000mm % larger than any actual note
673 \normalfont\normalsize
674 % \end{macrocode}
675 % Construct and ship out the page contents.
676 % \begin{macrocode}
677 \long\def\\##1{\verso@setnote ##1}
678 \RawShipout\vbox{
679 \verso@currentposition=0pt
680 #1}
681 \endgroup
682 \fi
683 % \end{macrocode}
684 % Otherwise, the |\verso@pagestoskip| counter is still positive,
685 % indicating that we are skipping pages.
686 % Decrement the counter and do nothing else.
687 % \begin{macrocode}
688 \else
689 \global\advance\verso@pagestoskip -1
690 \fi
691 % \end{macrocode}
692 % Finally, set |\verso@pages| to the tail of the list.
693 % \begin{macrocode}
694 \global\verso@pages={#2}}
695 % \end{macrocode}
696 %
697 % The command |\verso@processonepage| is invoked once on every |\shipout|.
698 % \begin{macrocode}
699 \def\verso@processonepage{
700 \if@verso@processversonotes
701 \expandafter\verso@processonepage@\the\verso@pages\@nil
702 % \end{macrocode}
703 % If this test is false, then we don't seem to have any versonotes in this file,
704 % so don't come here again.
705 % \begin{macrocode}
706 \else
707 \global\let\verso@processonepage\relax
708 \fi
709 }
710 % \end{macrocode}
711 %
712 % And finally, do the |\shipout| gymnastics.
713 % \begin{macrocode}
714 \ifverso@Liii
715 \AddToHook{shipout/before}{\verso@processonepage}
716 \else
717 \def\shipout{\verso@processonepage \RawShipout}
718 \fi
719 % \end{macrocode}
720 %
721 % All done!
722 % \begin{macrocode}
723 %</package>
724 % \end{macrocode}
725 % \Finale
726 %
727 \endinput