Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 %<*preamble>
4 % mnotes.dtx
5 %
6 % Copyright (C) 2013 by S Luz <[email protected]>
7 %
8 % This work may be distributed and/or modified under the conditions of
9 % the LaTeX Project Public License, either version 1.3 of this license
10 % or (at your option) any later version. The latest version of this
11 % license is in
12 %
13 % http://www.latex-project.org/lppl.txt
14 %
15 % and version 1.3 or later is part of all distributions of LaTeX
16 % version 2003/12/01 or later.
17 %
18 % INSTALLATION:
19 %
20 % on Unix, run "make" to get the style file and the documentation;
21 % Alternatively, to generate the driver mnotes.ins run
22 %
23 % $ pdflatex mnotes.dtx
24 %
25 % To generate the style file run
26 %
27 % $ tex mnotes.ins
28 %
29 %% @LaTeX-package-file{
30 %% author = "Saturnino Luz",
31 %% version = "0.9",
32 %% date = "25 May 2022",
33 %% filename = "mnotes.dtx",
34 %% address = "S Luz
35 %% Dublin, Ireland",
36 %% URL = "https://gitlab.com/e1700/mnotes/",
37 %% email = "[email protected]",
38 %% codetable = "ISO/ASCII",
39 %% keywords = "margin, notes, comments",
40 %% supported = "yes",
41 %% docstring = "This document describes the mnotes package.
42 %% }
43 %%
44 %
45 %</preamble>
46 %
47 %<*batchfile>
48 \begin{filecontents}{mnotes.ins}
49 \def\batchfile{mnotes.ins}
50 \input docstrip.tex
51 \askforoverwritefalse
52 \keepsilent
53 \preamble
54
55 This is a generated file.
56
57 Copyright (C) 2013-2021 by S Luz <[email protected]>
58
59 This work may be distributed and/or modified under the conditions of
60 the LaTeX Project Public License, either version 1.3 of this license
61 or (at your option) any later version. The latest version of this
62 license is in
63
64 http://www.latex-project.org/lppl.txt
65
66 and version 1.3 or later is part of all distributions of LaTeX version
67 2003/12/01 or later.
68
69 \endpreamble
70 \generate{\file{mnotes.sty}{\from{mnotes.dtx}{package}}}
71
72 \obeyspaces
73 \Msg{*************************************************************}
74 \Msg{* *}
75 \Msg{* To finish the installation you have to move the following *}
76 \Msg{* file into a directory searched by TeX: *}
77 \Msg{* *}
78 \Msg{* mnotes.sty *}
79 \Msg{* *}
80 \Msg{* To produce the documentation run the file mnotes.dtx *}
81 \Msg{* through LaTeX. *}
82 \Msg{* *}
83 \Msg{* Happy TeXing! *}
84 \Msg{* *}
85 \Msg{*************************************************************}
86 \endbatchfile
87 \end{filecontents}
88 %</batchfile>
89 %
90 %<*driver>
91 \ProvidesFile{mnotes.dtx}[%
92 %</driver>
93 %<package>\ProvidesPackage{mnotes}[%
94 %<*driver|package>
95 2022/25/05 v0.9 margin notes for collaborative document editing]
96 %</driver|package>
97 %<*driver>
98 \documentclass{ltxdoc}
99 %%\usepackage{mnotes}
100 \EnableCrossrefs
101 \CodelineIndex
102 \RecordChanges
103 \begin{document}
104 \DocInput{mnotes.dtx}
105 \PrintIndex
106 \PrintChanges
107 \end{document}
108 %</driver>
109 % \fi
110 %
111 % \CharacterTable
112 % {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
113 % 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
114 % Digits \0\1\2\3\4\5\6\7\8\9
115 % Exclamation \! Double quote \" Hash (number) \#
116 % Dollar \$ Percent \% Ampersand \&
117 % Acute accent \' Left paren \( Right paren \)
118 % Asterisk \* Plus \+ Comma \,
119 % Minus \- Point \. Solidus \/
120 % Colon \: Semicolon \; Less than \<
121 % Equals \= Greater than \> Question mark \?
122 % Commercial at \@ Left bracket \[ Backslash \\
123 % Right bracket \] Circumflex \^ Underscore \_
124 % Grave accent \` Left brace \{ Vertical bar \|
125 % Right brace \} Tilde \~}
126 %
127 % \changes{v0.4}{2013/04/18}{Clean-up}
128 % \changes{v0.5}{2013/04/20}{First release}
129 %
130 % \GetFileInfo{mnotes.dtx}
131 %
132 %
133 % \title{\texttt{mnotes} --- annotate documents with margin comments\thanks{This document
134 % corresponds to \textsf{mnotes}~\fileversion, dated \filedate.}}
135 % \author{S Luz\\ \texttt{luzs<at>acm.org} }
136 %
137 % \maketitle
138 %
139 % \begin{abstract}
140 % This is a simple package to allow you to add comments to the margins
141 % of your documents. It is primarily designed to support collaborative
142 % document writing. The comments can be added to the text similarly
143 % to \verb+\footnote+ and will be displayed on the margins in
144 % text boxes connected by a thin line to the part of the text they refer
145 % to. Thanks to the use of \texttt{sidenotes}, comments can float on
146 % the margins to avoid overlaps. The text can optionally be scaled
147 % down to allow comments to fit in otherwise narrow notes without
148 % altering the document's template.
149 % \end{abstract}
150 %
151 % \tableofcontents
152 %
153 % \section{Package options}
154 %
155 % The basic usage is to include a \verb+\usepackage{mnotes}+ to the
156 % preamble of your \LaTeX\ document.
157 %
158 % The \textsf{mnotes} package also provides some basic
159 % customisation of the way comments are displayed. The interface to the
160 % package's options is, as usual, accessed through the \verb+\usepackage+
161 % command.
162 %
163 % The package options are:
164 % \begin{itemize}
165 % \item[\texttt{scale}] This enlarges the physical page of the
166 % document to allow comments to fit in the margin area. The default
167 % \verb+\usepackage[scale]{mnotes}+ is to make the physical page 5\%
168 % larger than the original paper size. You can pass a value to this
169 % option to control the the amount of space allocated to the
170 % margins. For instance \verb+\usepackage[scale=1.2]{mnotes}+ makes
171 % the physical page 20\% larger. \textbf{Important:} when printing
172 % your draft, make
173 % sure that the printer is set to shrink the page to printable area.\\
174 % Default: \texttt{scale=1.05}.
175 % \item[\texttt{mnwidth}] Sets the default width for the comment
176 % boxes. \\ Default: \texttt{mnwidth=2.2cm}.
177 % \item[\texttt{boxcolour}] the colour of the box that encloses the
178 % comments (and of the lines that connect comments to the
179 % text). \\Default: \texttt{boxcolour=red}.
180 % \item[\texttt{hide}] Hides all notes. Useful for generating a final
181 % (camera-ready) version without comments, without actually removing
182 % the comments from the \LaTeX\ code.
183 %
184 % \changes{v0.6}{2013/04/22}{Added nosidenotes option}
185 % \changes{v0.8}{2014/11/05}{By default don't use sidenotes. Specify
186 % sidenotes option to use it. marginnote allows placement of MNOTEs on
187 % floats; sidenote doesn't seem to.}
188 %
189 % \item[\texttt{sidenotes}] use sidenote package instead of plain marginnote.
190 % \item[\texttt{basic}] This causes the note setting to fallback to
191 % \LaTeX{} kernel's \verb+\marginpar+, in case \texttt{sidenotes} or
192 % \texttt{tikz} isn't available.
193 %
194 % \changes{v0.6}{2013/04/22}{Added reverseconnect option}
195 %
196 % \item[\texttt{reverseconnect}] Some classes seem to call the right
197 % column 'first column' (i.e. they set \verb+\if@firstcolumn+ to
198 % \texttt{true} on the first column). This option tries to fix this,
199 % so the lines link to the notes on the right side of the boxes
200 % (west for right columns and east for left columns). The direction
201 % of connection can also be reversed in the document through the
202 % \verb+\ReverseMNConnect+ command.
203 % \end{itemize}
204 %
205 % \section{Usage}
206 %
207 % \DescribeMacro{\MNOTE} The \verb+\MNOTE[colour]{comments}+ places
208 % \texttt{comments} on the right margin of the document. Comments can
209 % contain any valid \LaTeX\ code, including text, pictures, tables
210 % etc. Comments are enclosed in boxes and linked to specific places in
211 % the text by lines, except when the option \texttt{basic} is passed to
212 % \verb+\usepackage+. If you are generating a \texttt{pdf} file with
213 % \texttt{pdflatex} (or \texttt{pdftex}) you might have to run it
214 % at least twice in order to get \texttt{tikz} to find the correct
215 % coordinates for lines and boxes.
216 %
217 % The aim was to keep the interface as simple as
218 % possible, so that the
219 % usage can be quickly explained to your collaborators, even if they
220 % are not regular \LaTeX\ users. The following example shows the basic
221 % usage:
222 % \begin{verbatim}
223 % The aim was to keep the interface as simple as
224 % possible\MNOTE{Revise this text}, so that the
225 % usage can be quickly explained to your collaborators, even if they
226 % are not regular \LaTeX\ users.
227 % \end{verbatim}
228 %
229 % \DescribeMacro{\Mnewauthor} Define author-specific margin notes for
230 % comments. \\The
231 % \verb+\Mnewauthor[<initials>]{<name>}{<todonote specs>}+ macro
232 % defines a command for personalised comments by author \verb+name+ by
233 % setting up the command \verb+\mn<initials>[highlight]{comment}+
234 % which can then be used in the text. Usage:
235 % \begin{verbatim}
236 % \newauthor[BD]{Bob}{yellow}
237 % \end{verbatim}
238 % This defines \verb+\mnBD+, which can be used to comment and highlight
239 % as follows:
240 % \begin{verbatim}
241 % \mnBD[this is highlighted]{this is a margin note.} or,
242 % alternatively, without highlighting
243 % \mnBDhis is a margin note with no highlights.}
244 % \end{verbatim}
245 %
246 % \DescribeMacro{\HideMNOTES} Comments can be ``switched off'' at any
247 % point in the text by adding a \verb+\HideMNOTES{}+ command anywhere
248 % in the text.
249 % \DescribeMacro{\ShowMNOTES}
250 % They can be switched back on again through the
251 % \verb+\ShowMNOTES{}+
252 %
253 % \DescribeMacro{\ReverseMNConnect}
254 % Toggle the side to which the comment boxes are connected to the
255 % text, to be used in case \LaTeX\ looses track of it. Package option
256 % \verb+reverseconnect+ reverses these connections globally.
257 %
258 % \section{Required packages}
259 %
260 % \begin{description}
261 % \item[kvoptions] for option processing
262 % \item[sidenotes] for note placement, including floats. N.B.:
263 % \texttt{sidenotes} is not required if \texttt{basic} or \texttt{nosidenotes}
264 % is passed
265 % as an option. In this case, note placement reverts to \LaTeX{}'s
266 % kernel's \verb+\marginpar+ macro.
267 % \item[soul] for highlighting.
268 % \item[tikz] for graphics (boxes and connectors). N.B.:
269 % \texttt{tikz} is note required if \texttt{basic} is passed as an
270 % option.
271 % \end{description}%
272 %
273 % \section{Bugs}
274 %
275 % The connectors sometimes go off the page when option
276 % \verb+nosidenotes+ is set (i.e. notes are set through \LaTeX\ kernnel's
277 % \verb+\marginpar+ macro).
278 %
279 % \section{Implementation}
280 %
281 % \iffalse
282 %<*package>
283 % \fi
284 % Define some defaults: width of comment bcx, colour, font and paperwidth.
285 % \begin{macrocode}
286 \expandafter\ifx\csname mnotespaperwidth\endcsname\relax
287 \newdimen\mnotespaperwidth
288 \mnotespaperwidth1.05\paperwidth
289 \fi
290 \newlength{\MNOTEWIDTH}
291 \setlength{\MNOTEWIDTH}{2.2cm}
292 \newcommand{\MNCOLOUR}{red}
293 \newcommand{\MNFONT}{\tiny}
294 \newif\if@mnotes@hide
295 \@mnotes@hidefalse
296 \newif\if@mnotes@basic
297 \@mnotes@basicfalse
298 \newif\if@mnotes@sidenotes
299 \@mnotes@sidenotesfalse
300 \newif\if@mnotes@scale
301 \@mnotes@scalefalse
302 \newif\if@mnotes@reverseconnect
303 \@mnotes@reverseconnectfalse
304 % \end{macrocode}
305 % Get package options
306 % \begin{macrocode}
307 \RequirePackage{kvoptions}
308 \RequirePackage{soul}
309 \DeclareVoidOption{basic}{\@mnotes@basictrue}
310 \DeclareVoidOption{sidenotes}{\@mnotes@sidenotestrue}
311 \DeclareVoidOption{hide}{\@mnotes@hidetrue \AtEndOfPackage{\HideMNOTES{}}}
312 \DeclareVoidOption{reverseconnect}{\@mnotes@reverseconnecttrue}
313 \SetupKeyvalOptions{family=mnotes, prefix=mnotes@}
314 \DeclareStringOption{scale}[1.05]
315 \define@key{mnotes}{scale}{\if@mnotes@hide\else%
316 \setlength{\paperwidth}{#1\paperwidth}\@mnotes@scaletrue\fi}
317 \DeclareVoidOption{centre}{\if@mnotes@scale\hoffset\paperwidth
318 \advance\hoffset-\paperwidth
319 \hoffset.5\hoffset\fi}
320 \DeclareStringOption{mnwidth}[\MNOTEWIDTH]
321 \define@key{mnotes}{mnwidth}{\setlength{\MNOTEWIDTH}{#1}}
322 \DeclareStringOption{boxcolour}
323 \define@key{mnotes}{boxcolour}{\renewcommand{\MNCOLOUR}{#1}}
324 \DeclareStringOption{fontsize}[6]
325 \define@key{mnotes}{fontsize}{%
326 \count1=#1 \multiply \count1 by 116 \divide \count1 by 100%
327 \def\MNFONT{\fontsize{#1}{\count1}\selectfont}}
328 %% try to keep notes on the same margin
329 % \makeatletter \@mparswitchfalse \makeatother
330 %\ExecuteOptions{}
331 \ProcessKeyvalOptions{mnotes}
332 %\ProcessOptions
333 % \end{macrocode}
334 % \changes{v0.7}{2013/04/24}{made basic option independent of
335 % ifoddpage package}
336 % \begin{macrocode}
337 \if@twocolumn\if@mnotes@scale\hoffset\pdfpagewidth
338 \advance\hoffset-\paperwidth
339 \hoffset.5\hoffset\fi\fi
340 \if@mnotes@basic
341 \RequirePackage{color}
342 \newif\ifoddpage %% define \ifoddpage even though it's not used to
343 \else %% avoid extra bracket error
344 \if@mnotes@sidenotes
345 \RequirePackage{sidenotes}
346 \else
347 \RequirePackage{marginnote}
348 \renewcommand\marginpar\marginnote
349 \fi
350 \RequirePackage{tikz}
351 \RequirePackage{ifoddpage}
352 \fi
353 % \end{macrocode}
354 % \begin{macro}{\MNOTEon}
355 % This is the core of the notes macro.
356 % \changes{v0.6}{2013/04/22}{Fixed problems with margins for
357 % twocolumn and twoside documents, so that connectors connect to the
358 % right side of the notes box. For some strange reason, article.cls
359 % seems to call the right column 'first column' (i.e. \texttt{if@firstcolumn}
360 % true). Created an option reverseconnect to fix that, so the lines
361 % link to the notes on the right side of the boxes (west for right
362 % columns and east for left columns). }
363 % \changes{v0.6}{2013/04/22}{Use reverseconnect to set the left and
364 % right margins correctly in some classes.}
365 % \changes{v0.8}{2013/04/24}{replaced marginpar by marginnote on the
366 % nosidenote option to allow MNOTES in floats.}
367 % \begin{macrocode}
368 \if@mnotes@basic
369 \setlength{\marginparsep}{6pt}\setlength{\marginparwidth}{\MNOTEWIDTH}
370 \newcommand{\MNOTEon}[2][\MNCOLOUR]{%
371 \marginpar%
372 [{\MNFONT\raggedleft\color{#1}\em #2}]%
373 {\MNFONT\raggedright\color{#1}\em #2}}%
374 \else% not basic
375 \newcommand{\MNOTEon}[2][\MNCOLOUR]{%
376 \setlength{\marginparsep}{6pt}\setlength{\marginparwidth}{\MNOTEWIDTH}%
377 \begin{tikzpicture}[remember picture, baseline=-0.75ex]%
378 \node [coordinate] (textPOS) {};%
379 \end{tikzpicture}%
380 \if@mnotes@sidenotes
381 \sidenotetext[\tiny.]%
382 {\MNFONT\raggedright\em%
383 \begin{tikzpicture}[remember picture]%
384 \draw node [draw=#1,text width=\MNOTEWIDTH-1pt] (notePOS) {#2};%
385 \end{tikzpicture}%
386 }%
387 \else
388 \marginpar%
389 [{\MNFONT\raggedleft\em\begin{tikzpicture}[remember picture]%
390 \draw node [draw=#1,text width=\MNOTEWIDTH-1pt] (notePOS) {#2};%
391 \end{tikzpicture}}]%
392 {{\MNFONT\raggedright\em%
393 \begin{tikzpicture}[remember picture]%
394 \draw node [draw=#1,text width=\MNOTEWIDTH-1pt] (notePOS) {#2};%
395 \end{tikzpicture}%
396 }}%
397 \fi%
398 \if@twocolumn%
399 \if@firstcolumn%
400 \if@mnotes@reverseconnect%
401 \mnoteswestlink{#1}%
402 \else%
403 \mnoteseastlink{#1}%
404 \fi%
405 \else%
406 \if@mnotes@reverseconnect%
407 \mnoteseastlink{#1}%
408 \else%
409 \mnoteswestlink{#1}%
410 \fi%
411 \fi%
412 \else%
413 \if@twoside%
414 \checkoddpage%
415 \ifoddpage%\ifodd\value{mn@abspage}%
416 \mnoteswestlink{#1}%
417 \else%
418 \mnoteseastlink{#1}%
419 \fi%
420 \else%
421 \mnoteswestlink{#1}%
422 \fi%
423 \fi%
424 }%
425 \newcommand{\mnoteseastlink}[1]{%
426 \begin{tikzpicture}[remember picture, overlay]%
427 \draw[#1,-]%
428 ([yshift=-0.2cm] textPOS)%
429 -|([xshift=-0.1pt] notePOS.east);%
430 \end{tikzpicture}%
431 }
432 \newcommand{\mnoteswestlink}[1]{%
433 \begin{tikzpicture}[remember picture, overlay]%
434 \draw[#1,-]%
435 ([yshift=-0.2cm] textPOS)%
436 -|([xshift=-0.1pt] notePOS.west);%
437 \end{tikzpicture}%
438 }
439 \fi
440 % \end{macrocode}
441 % \end{macro}
442 %\begin{macro}
443 % Define author-specific margin notes for comments.
444 % Syntax: \verb'\Mnewauthor[<initials>]{<name>}{color}'
445 % Example:
446 % \verb'\Mnewauthor[SL]{Nino}{yellow}'
447 % Sets up the command \verb'\mn<initials>{}' which can then be used in the
448 % text.
449 % E.g.:
450 % \verb'\mnSL[this is highlighted]{this is a margin note.}'
451 % \verb'\mnSL{this is a margin note with no highlights.}'
452 % \begin{macrocode}
453 \newcommand{\Mnewauthor}[3][]{%
454 % If #1 is not given, use #2 by default as the cmd name
455 \def\@tempa{#1}%
456 \ifx\@tempa\@empty%
457 \def\@authid{#2}%
458 \else%
459 \def\@authid{#1}%
460 \fi%
461 % Define the \mnX command with the colour and so on
462 \expandafter\newcommand\csname mn\@authid\endcsname[2][]{%
463 \if@mnotes@hide ##1\else\sethlcolor{#3}\hl{##1}\MNOTE[#3]{#2: ##2}{}\fi}%
464 }
465 % \end{macrocode}
466 % \end{macro}
467 % \begin{macro}{\MNOTE}
468 % User interface to \verb+\MNOTEon+
469 % \begin{macrocode}
470 \newcommand{\MNOTE}{\MNOTEon}
471 % \end{macrocode}
472 % \end{macro}
473 % \begin{macro}{\HideMNOTES}
474 % Hide notes from this point on.
475 % \begin{macrocode}
476 \newcommand{\HideMNOTES}{\renewcommand{\MNOTE}[2][red]{}}
477 % \end{macrocode}
478 % \end{macro}
479 % \begin{macro}{\ShowMNOTES}
480 % Show notes from this point on.
481 % \begin{macrocode}
482 \newcommand{\ShowMNOTES}{\renewcommand{\MNOTE}{\MNOTEon}}
483 % \end{macrocode}
484 % \end{macro}
485 % \begin{macro}{\ReverseMNConnect}
486 % Reverse the side of from which the lines connect to the MNOTE box.
487 % \begin{macrocode}
488 \newcommand{\ReverseMNConnect}{%
489 \if@mnotes@reverseconnect\@mnotes@reverseconnectfalse
490 \else\@mnotes@reverseconnecttrue\fi}
491 % \end{macrocode}
492 % \end{macro}
493 % \Finale
494 \endinput