Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % sidenotes.dtx
4 %
5 % Copyright (C) 2011-2024 by Andy Thomas <andythomas(at)web.de>
6 %
7 % This work may be distributed and/or modified under the
8 % conditions of the LaTeX Project Public License, either version 1.3
9 % of this license or (at your option) any later version.
10 % The latest version of this license is in
11 % http://www.latex-project.org/lppl.txt
12 % and version 1.3 or later is part of all distributions of LaTeX
13 % version 2003/12/01 or later.
14 %
15 % The author of this work is Andy Thomas
16 %
17 %<*driver>
18 \ProvidesFile{sidenotes.dtx}[2024/09/12 v1.20 Rich text in the margin for LaTeX]%
19 %</driver>
20 %<package>\RequirePackage{l3keys2e}%
21 %<package>\ProvidesExplPackage{sidenotes}{2024/09/12}{1.20}{Rich text in the margin for LaTeX}
22 %<package>\RequirePackage{marginnote} % Provides an offset option for the marginals instead of a float
23 %<package>\RequirePackage{caption} % Handles the captions (in the margin)
24 %<package>\RequirePackage{xparse} % New LaTeX3 syntax to define macros and environments
25 %<package>\RequirePackage[strict]{changepage} % Changepage package for symmetric twoside handling
26 %<*driver>
27 \documentclass{ltxdoc}
28 \CodelineIndex
29 \RecordChanges
30 \begin{document}
31 \DocInput{sidenotes.dtx}
32 \PrintIndex
33 \PrintChanges
34 \end{document}
35 %</driver>
36 % \fi
37 %
38 % \CharacterTable
39 % {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
40 % 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
41 % Digits \0\1\2\3\4\5\6\7\8\9
42 % Exclamation \! Double quote \" Hash (number) \#
43 % Dollar \$ Percent \% Ampersand \&
44 % Acute accent \' Left paren \( Right paren \)
45 % Asterisk \* Plus \+ Comma \,
46 % Minus \- Point \. Solidus \/
47 % Colon \: Semicolon \; Less than \<
48 % Equals \= Greater than \> Question mark \?
49 % Commercial at \@ Left bracket \[ Backslash \\
50 % Right bracket \] Circumflex \^ Underscore \_
51 % Grave accent \` Left brace \{ Vertical bar \|
52 % Right brace \} Tilde \~}
53 %
54 %
55 %
56 % \GetFileInfo{sidenotes.dtx}
57 %
58 %
59 % \title{The \textsf{sidenotes} package\thanks{This document
60 % corresponds to \textsf{sidenotes}~\fileversion, dated \filedate.
61 % Earlier versions by Oliver Schebaum.}}
62 % \author{Andy Thomas\\ \texttt{andythomas(at)web.de}}
63 %
64 % \maketitle
65 %
66 % \changes{v0.51}{2011/10/05}{Extent the documentation of the macros.}
67 % \changes{v0.90}{2012/06/02}{two opt package is required, the definitions are too confusing otherwise}
68 % \changes{v0.92}{2012/11/09}{corrected typo in email address}
69 % \changes{v0.95}{2014/01/23}{cleaned up the documentation.}
70 % \changes{v0.97}{2014/06/05}{make it a expl package}
71 % \changes{v0.97}{2014/06/05}{introduce package option oneside }
72 % \changes{v0.98}{2015/03/04}{compatible with new mhchem version}
73 % \changes{v0.99}{2015/08/10}{no changes (only in caesar-book.cls)}
74 % \changes{v1.00}{2016/04/21}{no changes, tag v1.0}
75 %
76 % \begin{abstract}
77 % \noindent This package allows the typesetting of rich content in the margin.
78 % It includes text, but also figures, captions, tables and citations,
79 % which is common in science textbooks such as Feynman's
80 % \textit{Lectures on Physics}.
81 % \end{abstract}
82 %
83 % \tableofcontents
84 %
85 % \changes{v0.2}{2011/08/21}{Initial version}
86 % \changes{v0.7}{2011/11/09}{rewrite without optional offsets}
87 % \changes{v0.91}{2012/06/03}{deleted marginfullcite}
88 %
89 % \section{Usage}
90 %
91 % \DescribeMacro{\sidenote}
92 % The macro is very similar to the footnote macro and tries to emulate
93 % its behavior. It just puts the notes in the margin instead of the bottom
94 % of the page, therefore the name \emph{sidenote}. It has the same parameters
95 % as footnote as well as an additional offset:
96 % \verb+\sidenote[number][offset]{text}+. All the sidenotes are subsequently
97 % numbered and float in the margin to avoid overlap.
98 % The first, optional parameter will manually change the numbering to the given
99 % value. The second offset parameter will fix the text at a certain position
100 % in the margin. In particular, there is a difference between not providing an
101 % offset (floating text) and an offset of 0 (fix text at actual position).
102 %
103 % \DescribeMacro{\sidenotemark}
104 % Sidenote tries to mimic the footnote behavior and, consequently, provides the
105 % same solutions. Sometimes, it is not possible to directly call a sidenote
106 % macro, e.g.\ inside of a figure caption. Then, you can use
107 % \verb+\sidenotemark[number]+ and \verb+\sidenotetext[number][offset]{text}+
108 % macros. \verb+\sidenotemark+ puts a mark at the current position. Afterwards,
109 % outside of the environment that causes the trouble,
110 % \DescribeMacro{\sidenotetext}
111 % it is possible the call \verb+\sidenotetext[number][offset]{text}+ to provide
112 % the text and typeset the sidenote. The optional parameters are similar to the
113 % sidenote macro. The first, optional parameter will change the numbering and
114 % the offset will change the position.
115 %
116 % \changes{v0.61}{2011/10/17}{documentation of sidetext}
117 %
118 %\DescribeMacro{\sidecaption}
119 % The \verb+\sidecaption[entry][offset]{text}+ macro can be used if the caption
120 % of a figure or table should be in the margin. The caption has to be adjacent
121 % to the figure, so a float is not an option here. Therefore, the caption might
122 % overlap with other marginals. Then, these marginals have to be adjusted with
123 % offset parameters. The formatting of the caption is done by the \emph{caption}
124 % package by defining a \emph{sidecaption} style. Please refer to the
125 % documentation of the caption package for information on styles. The macro can
126 % be starred, which is analog to the regular starred caption (no numbering, no
127 % tof entry): \verb+\sidecaption*[offset]{text}+.
128 %
129 % \DescribeEnv{marginfigure}
130 % The marginfigure environment puts a figure and its caption in the margin.
131 % Instead of \verb+\begin{figure}[htbp]+ use \verb+\begin{marginfigure}[offset]+.
132 % Again, using an offset value switches the behavior from float to fixed
133 % position. The marginfigure has its own caption style named \emph{marginfigure}.
134 %
135 % \DescribeEnv{margintable}
136 % The margintable environment works similar to marginfigure, but with table
137 % environments. Use \verb+\begin{margintable}[offset]+ instead of
138 % \verb+\begin{table}[htbp]+, its caption style is named \emph{margintable}.
139 %
140 % \DescribeEnv{figure*}
141 % The \verb+figure*+ environment is used to position figures across the full
142 % page, i.e. the text width plus the margin. The algorithm has to distinguish
143 % between recto and verso (left and right) pages and might need up to three
144 % \LaTeX{} runs to provide the desired result. The corresponding caption style
145 % is called \emph{widefigure}.
146 % \DescribeEnv{table*}
147 % The sister environment for tables is \verb+table*+. Use \emph{widetable} to
148 % change its caption style.
149 %
150 % \section{Technical note}
151 %
152 % When writing the package, we tried to provide a \emph{minimum} extension to
153 % standard \LaTeX{} for typesetting rich content in the margin. This means,
154 % that there are no sensible default values for most things such as page
155 % geometry, fonts and font sizes. However, the \emph{caesar\textunderscore
156 % book}-class accompanies this package as an example implementation as well
157 % as a template we use for our theses.
158 %
159 % In addition, we tried to keep compatibility with
160 % packages the user might want to use later. However, the following packages
161 % are needed by \emph{sidenotes} and might introduce side effects with other
162 % packages.
163 %
164 % \section{Required packages}
165 %
166 % \changes{v0.52}{2011/10/06}{added a section that the package needs marginnote, caption and xifthen.}
167 % \changes{v0.90}{2012/06/02}{added a section that the package needs twoopt and changepage.}
168 % \changes{v0.94}{2014/01/22}{start using xparse}
169 % \changes{v0.97}{2014/06/05}{start using l3keys2e}
170 %
171 % \begin{description}
172 % \item[marginnote]
173 % supports an alternative to \verb+\marginpar+ and creates notes in the
174 % margin. The notes are not floats and can be shifted up or down.
175 % Technically, every time an offset is provided the package uses
176 % \verb+\marginnote+ and \verb+\marginpar+ otherwise.
177 % \item[caption]
178 % allows to set figure and table captions in the margin and allows
179 % easier formatting of these captions. Please refer to the
180 % \emph{caption} manual for details on styles.
181 % \item[xparse] is used to take advantage of the improved \LaTeX3 syntax.
182 % All macros and environments are defined using this package.
183 % \item[l3keys2e] provides a key/value mechanism
184 % \item[changepage] is used to correctly shift figure* and table*. It has
185 % to use the option [strict] to work properly. This might lead to an
186 % option clash, if the same package is loaded without this option.
187 % \end{description}%
188 %
189 % \section{Implementation}
190 %
191 % \iffalse
192 %<*package>
193 % \fi
194 %
195 % Process the package options: onside
196 %
197 % \begin{macrocode}
198 \ExplSyntaxOn
199 %
200 \keys_define:nn { sidenotes }
201 {
202 oneside .bool_set:N = \sidenotes_oneside
203 }
204 \ProcessKeysOptions { sidenotes }
205 % \end{macrocode}
206 %
207 % \changes{v0.91}{2012/06/03}{sidenotetextstyle is not needed any more}
208 % \changes{v0.94}{2014/01/22}{change sidenote counter behavior}
209 %
210 % We need a counter similar to the footnote counter.
211 %
212 % \begin{macrocode}
213 \newcounter{sidenote} % make a counter
214 \setcounter{sidenote}{1} % init the counter
215 % \end{macrocode}
216 %
217 % \noindent The \LaTeX3 parts concerning the optional arguments should not
218 % distinguish between an empty bracket pair and no optional
219 % argument. This is required to keep macros with two leading
220 % optional arguments.
221 %
222 % \changes{v1.20}{2024/09/12}{Allow long arguments.}
223 %
224 % \begin{macrocode}
225 \DeclareExpandableDocumentCommand{\IfNoValueOrEmptyTF}{ m +m +m }
226 {
227 \IfNoValueTF{#1}
228 {#2}
229 {\tl_if_empty:nTF {#1} {#2} {#3}}
230 }
231 % \end{macrocode}
232 %
233 % \changes{v0.93}{2012/04/17}{regular ifnextchar gobbles trailing whitespaces, introduce a new one that does not.}
234 % \changes{v0.97}{2014/05/29}{New mechanism to detect subsequent sidenotemarks}
235 % \changes{v0.97}{2014/06/05}{New macro to place the superscript mark}
236 %
237 % \noindent Put a marker in the horizontal list to detect subsequent sidenotemarks.
238 %
239 % \begin{macrocode}
240 \NewDocumentCommand \@sidenotes@thesidenotemark { m }
241 {
242 \leavevmode
243 \ifhmode
244 \edef \@x@sf {\the \spacefactor }
245 \nobreak
246 \fi
247 \hbox {\@textsuperscript {\normalfont #1 }}
248 \ifhmode
249 \spacefactor \@x@sf
250 \fi
251 \relax
252 }
253 %
254 \NewDocumentCommand \@sidenotes@multisign { } {3sp}
255 %
256 \NewDocumentCommand \@sidenotes@multimarker { }
257 {
258 \kern-\@sidenotes@multisign
259 \kern\@sidenotes@multisign\relax
260 }
261 %
262 \NewDocumentCommand \@sidenotes@multichecker { }
263 {
264 \dim_compare:nNnTF \lastkern = \@sidenotes@multisign
265 {\@sidenotes@thesidenotemark{,}}
266 {}
267 }
268 %
269 % \end{macrocode}
270 %
271 % \changes{v0.97}{2014/05/27}{introduce an internal macro to place the marginal text}
272 %
273 % \noindent Introduce an internal macro to place the marginal text. Use
274 % margin note in case an offset is given and marginpar otherwise.
275 %
276 % \changes{v1.20}{2024/09/12}{Allow long arguments.}
277 %
278 % \begin{macrocode}
279 \NewDocumentCommand \@sidenotes@placemarginal { +m +m }
280 {
281 \IfNoValueOrEmptyTF{#1}
282 {\marginpar{#2}}
283 {\marginnote{#2}[#1]}
284 }
285 %
286 % \end{macrocode}
287 %
288 % \begin{macro}{\sidenote}
289 %
290 % Introduce the \verb+\sidenote+ macro with two optional
291 % arguments to set the number and the offset.
292 %
293 % \changes{v0.53}{2011/10/07}{bugfix, now optional number and offset possible}
294 % \changes{v0.80}{2011/11/10}{unstar the newcommand.}
295 % \changes{v0.81}{2011/11/29}{added a comma between subsequent sidenotes}
296 % \changes{v0.90}{2012/06/02}{add optional offset for sidenote}
297 % \changes{v0.93}{2012/04/17}{removed mandatory whitespace, new ifnextchar takes care of that}
298 % \changes{v0.94}{2014/01/11}{use xparse syntax}
299 %
300 % \begin{macrocode}
301 \NewDocumentCommand \sidenote { o o +m }
302 {
303 \sidenotemark[#1]
304 \sidenotetext[#1][#2]{#3}
305 \@sidenotes@multimarker
306 }
307 % \end{macrocode}
308 % \end{macro}
309 %
310 % \begin{macro}{\sidenotemark}
311 %
312 % Sidenotemark is supposed to work similarly to footnotemark.
313 %
314 % \changes{v0.94}{2014/01/11}{use xparse syntax, change counter behavior}
315 % \changes{v0.96}{2014/02/14}{increase the sidenote counter in sidenotetext now}
316 %
317 % \begin{macrocode}
318 \NewDocumentCommand \sidenotemark { o }
319 {
320 \@sidenotes@multichecker
321 \IfNoValueOrEmptyTF{#1}
322 {\@sidenotes@thesidenotemark{\thesidenote}}
323 {\@sidenotes@thesidenotemark{#1}}
324 \@sidenotes@multimarker
325 }
326 % \end{macrocode}
327 % \end{macro}
328 %
329 % \begin{macro}{\sidenotetext}
330 %
331 % Sidenotetext is supposed to work similarly to footnotetext. The additional,
332 % optional argument sets the offset.
333 %
334 % \changes{v0.80}{2011/11/10}{unstar the newcommand.}
335 % \changes{v0.90}{2012/06/02}{add optional offset for sidenotetext}
336 % \changes{v0.93}{2012/04/17}{add missing comment marks}
337 % \changes{v0.94}{2014/01/11}{use xparse syntax, change counter behavior}
338 %
339 % \begin{macrocode}
340 \NewDocumentCommand \sidenotetext { o o +m }
341 {
342 \IfNoValueOrEmptyTF{#1}
343 {
344 \@sidenotes@placemarginal{#2}{\textsuperscript{\thesidenote}{}~#3}
345 \refstepcounter{sidenote}
346 }
347 {\@sidenotes@placemarginal{#2}{\textsuperscript{#1}~#3}}
348 }
349 % \end{macrocode}
350 % \end{macro}
351 %
352 % \begin{macro}{\sidecaption}
353 %
354 % \changes{v0.91}{2012/06/03}{sidecaption* accompanies sidecaption}
355 % \changes{v0.94}{2014/01/22}{use xparse syntax}
356 %
357 % Sidecaption puts the caption in the margin. It never floats with the other
358 % text in the margin, since it has to be next to the figure.
359 % Sidecaption* works similarly to sidecaption, but without an entry.
360 %
361 % \begin{macrocode}
362 \DeclareCaptionStyle{sidecaption}{font=footnotesize}
363 \NewDocumentCommand \sidecaption {s o o m}
364 {
365 \captionsetup{style=sidecaption}
366 \IfBooleanTF{#1}
367 { % starred
368 \IfNoValueOrEmptyTF{#2}
369 {\marginnote{\caption*{#4}}}
370 {\marginnote{\caption*{#4}}[#2]}
371 }
372 { % unstarred
373 \IfNoValueOrEmptyTF{#2}
374 {\def\@sidenotes@sidecaption@tof{#4}}
375 {\def\@sidenotes@sidecaption@tof{#2}}
376 \IfNoValueOrEmptyTF{#3}
377 {\marginnote{\caption[\@sidenotes@sidecaption@tof]{#4}}}
378 {\marginnote{\caption[\@sidenotes@sidecaption@tof]{#4}}[#3]}
379 }
380 }
381 % \end{macrocode}
382 % \end{macro}
383 %
384 % \begin{environment}{marginfigure}
385 %
386 % \changes{v0.3}{2011/09/29}{define the sidefigure enviroment without the environ package}
387 % \changes{v0.90}{2012/06/02}{the optional offset parameter is back, renamed environment from sidefigure to marginfigure}
388 % \changes{v0.94}{2014/01/22}{use xparse syntax}
389 %
390 % The marginfigure environment is similar to the figure environment. But the
391 % figure is put in the margin.
392 %
393 % \begin{macrocode}
394 \newsavebox{\@sidenotes@marginfigurebox}
395 \DeclareCaptionStyle{marginfigure}{font=footnotesize}
396 \NewDocumentEnvironment{marginfigure} { o }
397 {
398 \begin{lrbox}{\@sidenotes@marginfigurebox}
399 \begin{minipage}{\marginparwidth}
400 \captionsetup{type=figure,style=marginfigure}
401 }
402 {
403 \end{minipage}%
404 \end{lrbox}%
405 \@sidenotes@placemarginal{#1}{\usebox{\@sidenotes@marginfigurebox}}
406 }
407 % \end{macrocode}
408 % \end{environment}
409 %
410 % \begin{environment}{margintable}
411 %
412 % \changes{v0.4}{2011/09/30}{define the sidetable enviroment without the environ package}
413 % \changes{v0.90}{2012/06/02}{the optional offset parameter is back, renamed environment from sidetable to margintable}
414 % \changes{v0.94}{2014/01/22}{use xparse syntax}
415 %
416 % The margintable is similar to the table environment. But the table
417 % is put in the margin.
418 %
419 % \begin{macrocode}
420 \newsavebox{\@sidenotes@margintablebox}
421 \DeclareCaptionStyle{margintable}{font=footnotesize}
422 \NewDocumentEnvironment{margintable} { o }
423 {
424 \begin{lrbox}{\@sidenotes@margintablebox}
425 \begin{minipage}{\marginparwidth}
426 \captionsetup{type=table,style=margintable}
427 }
428 {
429 \end{minipage}
430 \end{lrbox}
431 \@sidenotes@placemarginal{#1}{\usebox{\@sidenotes@margintablebox}}
432 }
433 % \end{macrocode}
434 % \end{environment}
435 %
436 % \begin{environment}{figure*}
437 %
438 % \changes{v0.85}{2011/06/01}{added the figure* environment}
439 % \changes{v0.97}{2014/05/27}{use adjustwidth in figure* environment}
440 % \changes{v1.10}{2020/04/05}{address issue with figures across the full width}
441 %
442 % The figure* environment provides a figure environment for figures that
443 % span across the full page (text plus margin width).
444 %
445 % \begin{macrocode}
446 \AtBeginDocument{%
447 \newlength{\@sidenotes@extrawidth}
448 \setlength{\@sidenotes@extrawidth}{\marginparwidth}
449 \addtolength{\@sidenotes@extrawidth}{\marginparsep}}
450 %
451 \NewDocumentEnvironment{autoadjustwidth}{ m m }%
452 {
453 \bool_if:NTF \sidenotes_oneside
454 {
455 \begin{adjustwidth}{#1}{#2}
456 }
457 {
458 \begin{adjustwidth*}{#1}{#2}
459 }
460 }
461 {
462 \bool_if:NTF \sidenotes_oneside
463 {
464 \end{adjustwidth}
465 }
466 {
467 \end{adjustwidth*}
468 }
469 }
470 %
471 \DeclareCaptionStyle{widefigure}{font=footnotesize}
472 \RenewDocumentEnvironment{figure*}{ O{htbp} }
473 {
474 \begin{figure}[#1]
475 \begin{autoadjustwidth}{}{-\@sidenotes@extrawidth}
476 \begin{minipage}{\linewidth}
477 \captionsetup{style=widefigure}
478 }
479 {
480 \end{minipage}
481 \end{autoadjustwidth}
482 \end{figure}
483 }
484 % \end{macrocode}
485 % \end{environment}
486 %
487 % \begin{environment}{table*}
488 %
489 % \changes{v0.85}{2011/06/01}{added the table* environment}
490 % \changes{v0.97}{2014/05/27}{use adjustwidth in table* environment}
491 % \changes{v1.10}{2020/04/05}{address issue with tables across the full width}
492 %
493 % The table* environment provides a table environment for figures across
494 % text and margin width.
495 %
496 % \begin{macrocode}
497 \DeclareCaptionStyle{widetable}{font=footnotesize}
498 \RenewDocumentEnvironment{table*}{ O{htbp} }
499 {
500 \begin{table}[#1]
501 \begin{autoadjustwidth}{}{-\@sidenotes@extrawidth}
502 \begin{minipage}{\linewidth}
503 \captionsetup{style=widetable}
504 }
505 {
506 \end{minipage}
507 \end{autoadjustwidth}
508 \end{table}
509 }
510 \ExplSyntaxOff
511 % \end{macrocode}
512 % \end{environment}
513 % \Finale
514 \endinput