Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %<*internal>
3 \iffalse
4 %</internal>
5 %<*dummy>
6 I'd like to keep this part here for later use.
7 %</dummy>
8 %<*internal>
9 \fi
10 \def\nameofplainTeX{plain}
11 \ifx\fmtname\nameofplainTeX\else
12 \expandafter\begingroup
13 \fi
14 %</internal>
15 %<*install>
16 \input l3docstrip.tex
17 \keepsilent
18 \askforoverwritefalse
19 \preamble
20 Copyright (C) 2016-2026, Ruini Xue <[email protected]>
21
22 It may be distributed and/or modified under the conditions of
23 the LaTeX Project Public License (LPPL), either version 1.3c of
24 this license or (at your option) any later version. The latest
25 version of this license is in the file:
26
27 http://www.latex-project.org/lppl.txt
28 \endpreamble
29 \postamble
30
31 This work is "maintained" (as per LPPL maintenance status) by
32 Ruini Xue.
33
34 This work consists of the file zebra.dtx
35 and the derived files zebra.ins,
36 zebra.pdf,
37 zebra.sty, and
38 zebra-goodies.sty.
39
40 \endpostamble
41 \usedir{tex/latex/zebra}
42 \generate{
43 \file{\jobname.sty}{\from{\jobname.dtx}{package}}
44 \file{\jobname-goodies.sty}{\from{\jobname.dtx}{compat}}
45 }
46 \nopreamble\nopostamble
47 \generate{
48 \file{\jobname-demo-twocol.tex}{\from{\jobname.dtx}{demo-twocol}}
49 }
50 %</install>
51 %<install>\endbatchfile
52 %<*internal>
53 \usedir{source/latex/zebra}
54 \generate{
55 \file{\jobname.ins}{\from{\jobname.dtx}{install}}
56 }
57 %\nopreamble\nopostamble
58 %\usedir{doc/latex/zebra}
59 %\generate{
60 % \file{README.md}{\from{\jobname.dtx}{dummy}}
61 %}
62 \ifx\fmtname\nameofplainTeX
63 \expandafter\endbatchfile
64 \else
65 \expandafter\endgroup
66 \fi
67 %</internal>
68 %<*driver|package>
69 %\RequirePackage{xparse}
70 %</driver|package>
71 %<*driver>
72 \documentclass[full]{l3doc}
73 \usepackage[scaled=0.93]{helvet}
74 \usepackage[final]{listings}
75 \usepackage{fontawesome}
76 \usepackage{graphicx}
77 \graphicspath{{./out/}}
78 \usepackage{zebra}
79 \zebrasetup{symbol/fixed=\manerrarrow}
80 \colorlet{mycyan}{cyan!80!black}
81 \EnableCrossrefs
82 \CodelineIndex
83 \RecordChanges
84 \begin{document}
85 \DocInput{\jobname.dtx}
86 \end{document}
87 %</driver>
88 % \fi
89 %
90 %\makeatletter
91 %
92 %^^A For creating examples with nice highlighting of code, and so
93 %^^A on; based on the system used in the listings source (lstsample).
94 %\lst@RequireAspects{writefile}
95 %\newsavebox{\LaTeXdemo@box}
96 %\lstnewenvironment{LaTeXdemo}[1][code and example]{^^A
97 % \global\let\lst@intname\@empty
98 % \expandafter\let\expandafter\LaTeXdemo@end
99 % \csname LaTeXdemo@#1@end\endcsname
100 % \@nameuse{LaTeXdemo@#1}^^A
101 %}{^^A
102 % \LaTeXdemo@end
103 %}
104 %\newcommand*\LaTeXdemo@new[3]{^^A
105 % \expandafter\newcommand\expandafter*\expandafter
106 % {\csname LaTeXdemo@#1\endcsname}{#2}^^A
107 % \expandafter\newcommand\expandafter*\expandafter
108 % {\csname LaTeXdemo@#1@end\endcsname}{#3}^^A
109 %}
110 %\newcommand*\LaTeXdemo@common{^^A
111 % \setkeys{lst}{
112 % basicstyle = \small\ttfamily,
113 % %basewidth = 0.51em,
114 % frame = l,
115 % backgroundcolor = \color{gray!5},
116 % gobble = 3,
117 % keywordstyle = \bfseries\color{blue},
118 % language = [LaTeX]{TeX},
119 % moretexcs = {
120 % todo ,
121 % note ,
122 % comment ,
123 % fixed ,
124 % placeholder ,
125 % question ,
126 % zebratodo ,
127 % zebranote ,
128 % zebracomment ,
129 % zebrafixed ,
130 % zebraplaceholder,
131 % zebranewnote ,
132 % zebraref ,
133 % zebrasetup ,
134 % colorlet
135 % }
136 % }^^A
137 %}
138 %\newcommand*\LaTeXdemo@input{^^A
139 % \MakePercentComment
140 % \small
141 % \begingroup
142 % \endlinechar=13\relax
143 % \catcode`\^^M=5\relax
144 % \input{\jobname.tmp}^^A
145 % \endgroup
146 % \MakePercentIgnore
147 %}
148 %\LaTeXdemo@new{code and example}{^^A
149 % \setbox\LaTeXdemo@box=\hbox\bgroup
150 % \lst@BeginAlsoWriteFile{\jobname.tmp}^^A
151 % \LaTeXdemo@common
152 %}{^^A
153 % \lst@EndWriteFile
154 % \egroup
155 % \begin{center}
156 % \ifdim\wd\LaTeXdemo@box>0.48\linewidth\relax
157 % \hbox to\linewidth{\box\LaTeXdemo@box\hss}^^A
158 % \begin{minipage}{\linewidth}
159 % \LaTeXdemo@input
160 % \end{minipage}
161 % \else
162 % \begin{minipage}{0.48\linewidth}
163 % \LaTeXdemo@input
164 % \end{minipage}
165 % \hfill
166 % \begin{minipage}{0.48\linewidth}
167 % \hbox to\linewidth{\box\LaTeXdemo@box\hss}^^A
168 % \end{minipage}
169 % \fi
170 % \end{center}
171 %}
172 %\LaTeXdemo@new{code only}{^^A
173 % \LaTeXdemo@common
174 %}{^^A
175 %}
176 %
177 %\providecommand*\opt[1]{\texttt{#1}}
178 %
179 %\makeatother
180 %
181 %\GetFileInfo{\jobname.sty}
182 %
183 %\changes{v0.1.0}{2017/07/05}{Initial public release}
184 %\changes{v0.2.0}{2017/11/26}{Fix \pkg{xcolor} conflict}
185 %\changes{v0.3.0}{2017/12/06}{Detect command conflicts}
186 %\changes{v0.4.0}{2019/06/29}{Show note number for easy reference}
187 %\changes{v0.5.0}{2019/06/29}{Use darker color for label}
188 %\changes{v0.6.0}{2019/06/30}{Use gray background for label}
189 %\changes{v0.9.0}{2026/02/25}{Fix legacy bugs and improve implementation}
190 %\changes{v0.9.1}{2026/02/27}{Beautify the numbers.}
191 %\changes{v0.9.2}{2026/03/03}{Faster.}
192 %\changes{v1.0.0}{2026/03/16}{\pkg{expl3}, list of notes and compatibility.}
193 %\changes{v1.1.0}{2026/03/21}{Customisable margin symbol, accurate page numbers, code cleanup.}
194 %\changes{v1.1.1}{2026/03/22}{Per-type \texttt{color}/\texttt{symbol} keys, \cs{zebrasetup}.}
195 %\changes{v1.2.0}{2026/03/23}{Simplify key architecture.}
196 %\changes{v1.3.0}{2026/03/25}{Rename package to \pkg{zebra}.}
197 %\changes{v1.3.0}{2026/03/25}{Rename the page-link option to \opt{pagelinks}/\opt{nopagelinks}.}
198 %\changes{v1.3.0}{2026/03/25}{Rename the microtype expansion option to \opt{font-expansion}.}
199 %\changes{v1.4.0}{2026/04/03}{Support note labels via \cs{label}, \cs{ref}, and \cs{zebraref}.}
200 %\changes{v1.5.0}{2026/04/14}{Fix notes numbering in moving arguments.}
201 %\changes{v1.6.0}{2026/04/16}{Numbering in moving arguments is hard.}
202 %\changes{v1.7.0}{2026/04/25}{Robust margin notes in twocolumn captions, titles and headings.}
203 %\changes{v1.8.0}{2026/04/25}{Fix margin symbol distance.}
204 %\changes{v1.8.0}{2026/04/26}{Add \opt{unnumbered} option for lightweight mode.}
205 %\changes{v1.8.0}{2026/04/26}{Stabilise labeled notes replayed through uppercased running heads.}
206 %\changes{v1.8.1}{2026/04/27}{Drop note bodies from PDF bookmarks.}
207 %\changes{v1.8.1}{2026/04/27}{Fix multiply-defined labels for repeated unlabeled notes.}
208 %\changes{v1.8.1}{2026/04/27}{Keep labeled notes with shared content distinct.}
209 %\changes{v1.8.1}{2026/04/29}{Silence pass-1 warning from \cs{zebraref}.}
210 %\changes{v1.9.0}{2026/05/01}{Document known limitations.}
211 %\changes{v2.0.0}{2026/05/20}{Stop loading \pkg{hyperref} and \pkg{microtype}.}
212 %
213 %\title{^^A
214 % \pkg{zebra} --- Writing Revision Toolkit^^A
215 % \thanks{^^A
216 % This package was previously distributed as \pkg{zebra-goodies}.
217 % The old name still works but will print a deprecation warning. Please
218 % update to \pkg{zebra}.^^A
219 % }^^A
220 %}
221 %\author{^^A
222 % Ruini Xue\thanks{Email: [email protected]}^^A
223 %}
224 %\date{\fileversion~(\filedate)}
225 %
226 %\maketitle
227 %
228 %\begin{abstract}
229 % The \pkg{zebra} package is a writing revision toolkit. The current release
230 % focuses on inline note-taking, with a lightweight set of macros designed to
231 % be simple and practical for both solo and collaborative workflows. Five
232 % built-in commands---\cs{todo}, \cs{note}, \cs{comment}, \cs{fixed}, and
233 % \cs{placeholder}---cover common use cases out of the box, and
234 % \cs{zebranewnote} lets you define additional note types as needed. Notes are
235 % automatically numbered per type, marked with a customisable
236 % symbol\marginnote{\textdbend} (default: \cs{textdbend}) in the nearest
237 % margin, and summarised with a summary table plus a detailed note list at the
238 % end of the document. If \pkg{hyperref} is loaded, the detailed list links
239 % back to the notes. Passing the \opt{final} option suppresses all notes for
240 % production output.
241 %\end{abstract}
242 %
243 %\tableofcontents
244 %
245 %\begin{documentation}
246 %
247 %\section{Introduction}
248 %
249 % \pkg{zebra} is a writing revision toolkit. The current release focuses on
250 % inline note-taking. Many note-taking and to-do packages exist for \LaTeX{},
251 % but most fall into one of two traps: they either offer an overwhelming
252 % feature set that tries to cover every conceivable use case, or they clutter
253 % the margins with oversized colourful boxes and arrows that make the document
254 % hard to read.
255 %
256 % \pkg{zebra} takes a different approach. It aims to be \emph{simple}
257 % ---intuitive commands with only the arguments you actually need---and
258 % \emph{good enough}---notes appear inline with a small visual cue in the
259 % margin, keeping the document readable while still making annotations easy to
260 % spot. Each note type is automatically numbered, and a summary table plus a
261 % detailed note list at the end of the document serve as a gentle reminder to
262 % address them before the final version.
263 %
264 %\section{Installation}
265 %
266 %\changes{v0.7.0}{2019/07/01}{Move to docstrip}
267 %
268 % \pkg{zebra} is available on CTAN; install it through your \LaTeX{}
269 % distribution's package manager. To build from source, run
270 % \texttt{latexmk \jobname.dtx} to extract the package and typeset the
271 % documentation in one step.
272 %
273 %\section{Using the package}
274 %
275 % Load the package in the preamble with any desired options.
276 %\begin{LaTeXdemo}[code only]
277 % \usepackage[<options>]{zebra} % was zebra-goodies
278 %\end{LaTeXdemo}
279 %
280 %\subsection{Package Options}
281 %\label{sec:options}
282 %
283 %\DescribeOption{draft}
284 %\DescribeOption{final}
285 % These two options are complementary. Default: \texttt{true} (draft mode). All
286 % notes are typeset inline and a summary table plus a detailed note list are
287 % appended at the end of the document. Setting \opt{final} (or |draft=false|)
288 % suppresses all notes and the generated lists, producing clean output ready for
289 % distribution.
290 %
291 %\DescribeOption{sort}
292 % Controls the order of the detailed note list printed at the end of the
293 % document. Default: \texttt{none} (document order).
294 % |sort=type| groups them by note type.
295 %
296 % If \pkg{hyperref} is loaded by the document, page numbers in the detailed
297 % note list link back to the corresponding notes. \pkg{zebra} does not load
298 % \pkg{hyperref} itself; load it explicitly if links are desired. Without
299 % \pkg{hyperref}, the list uses ordinary page references.
300 %
301 %\DescribeOption{unnumbered}
302 % Turns off note numbering. Inline markers become \texttt{[todo: \dots]}
303 % (no number), the margin symbol carries no number, the end-of-document
304 % detailed note list is omitted (the per-type summary table remains),
305 % and \cs{zebraref} falls back to \cs{ref}. Useful as a workaround if
306 % numbered notes interact badly with a particular class; the summary
307 % table count is then an upper-bound estimate. Default: \texttt{false}.
308 %
309 %\subsection{Notes Macros}
310 %
311 % All note commands share the syntax \cs{cmd}\oarg{name}\marg{text}. Each also
312 % has a prefixed alias (e.g.\ \cs{zebratodo}) that is always available,
313 % regardless of name conflicts. If a short name clashes with another loaded
314 % package, \pkg{zebra} will \emph{not} overwrite the existing
315 % definition; use the prefixed form instead.
316 %
317 %\begin{function}{\todo, \zebratodo}
318 % \begin{syntax}
319 % \cs{todo}\oarg{name}\marg{text}
320 % \cs{zebratodo}\oarg{name}\marg{text}
321 % \end{syntax}
322 %\end{function}
323 %
324 % The primary command provided by \pkg{zebra} is \cs{todo}. It inserts
325 % an inline note in the current paragraph, typeset in a predefined colour and
326 % marked with a symbol in the nearest margin. The mandatory \meta{text}
327 % describes the task; the optional \meta{name} specifies who is responsible for
328 % addressing it, which is particularly useful during collaborative writing.
329 %
330 % \begin{LaTeXdemo}
331 % The motivation section still feels too vague \todo{revise the introduction
332 % before submission} and could benefit from a concrete running example to
333 % guide the reader through the key ideas step by step.
334 % \end{LaTeXdemo}
335 %
336 % The optional argument assigns one or more people to the note. Assignees appear
337 % prefixed with \texttt{@}, and notes of the same type are numbered
338 % sequentially.
339 %
340 % \begin{LaTeXdemo}
341 % The related work section needs more references \todo[alice]{add two or
342 % three citations from the latest survey} to recent advances in the field. We
343 % should also double-check the experimental setup before the camera-ready
344 % deadline \todo[bob, carol]{verify the hyperparameter table against the
345 % source code and update any outdated entries and let's check afterwards}.
346 % \end{LaTeXdemo}
347
348 % Notes can appear inside moving arguments such as \cs{section} and
349 % \cs{caption}. To ensure stable numbering and cross-references, add a
350 % \cs{label} inside the note:
351 %
352 % \begin{LaTeXdemo}[code only]
353 % \section{Introduction\todo[jerry]{\label{zebra:heading}fix the name}}
354 % \begin{figure}
355 % \caption{Speed vs distance. \todo{need to insert the figure}}
356 % \end{figure}
357 % \end{LaTeXdemo}
358 %
359 % With a \cs{label}, the note is counted once regardless of how many
360 % times the heading appears (table of contents, running headers, etc.).
361 % Notes without a \cs{label} in moving arguments are still safe but may
362 % receive a separate number in each context.
363 %
364 %\begin{function}{\note, \zebranote}
365 % \begin{syntax}
366 % \cs{note}\oarg{name}\marg{text}
367 % \cs{zebranote}\oarg{name}\marg{text}
368 % \end{syntax}
369 %\end{function}
370 %\begin{function}{\comment, \zebracomment}
371 % \begin{syntax}
372 % \cs{comment}\oarg{name}\marg{text}
373 % \cs{zebracomment}\oarg{name}\marg{text}
374 % \end{syntax}
375 %\end{function}
376 %\begin{function}{\fixed, \zebrafixed}
377 % \begin{syntax}
378 % \cs{fixed}\oarg{name}\marg{text}
379 % \cs{zebrafixed}\oarg{name}\marg{text}
380 % \end{syntax}
381 %\end{function}
382 %\begin{function}{\placeholder, \zebraplaceholder}
383 % \begin{syntax}
384 % \cs{placeholder}\oarg{name}\marg{text}
385 % \cs{zebraplaceholder}\oarg{name}\marg{text}
386 % \end{syntax}
387 %\end{function}
388 % These commands share the same syntax and behaviour as \cs{todo}; they differ
389 % only in name and colour, providing semantic distinction for different
390 % annotation purposes. Note that \cs{zebracomment} is used in the example below
391 % because \cs{comment} is already defined by \pkg{l3doc}.
392 % \begin{LaTeXdemo}
393 % We may want to reorganise \note{how should we structure the intro?} this
394 % part before the final submission. The experimental setup in Section~2 has
395 % already been reviewed by a collaborator \zebracomment[tom]{the setup
396 % description looks clear now}. Results are presented in the following tables
397 % and figures, but some of them are still missing.
398 %
399 % The discussion has been revised \placeholder[lucy, tom]{good job!}
400 % and the related work comparison strengthened with two additional references.
401 % The list of references still needs a second pass \todo{check bibliography
402 % entries for formatting} before we can finalize the submission.
403 %
404 % With those items addressed, the conclusion has been rewritten so the
405 % argument flows more naturally from the results. \fixed[John]{updated the
406 % conclusion} The overall structure now matches the revised outline we agreed
407 % on last week. \note[who]{anything else?} If not, the draft should be fine.
408 % \end{LaTeXdemo}
409 %
410 %\begin{function}{\zebranewnote}
411 % \begin{syntax}
412 % \cs{zebranewnote}\marg{note name}\marg{xcolor name}\oarg{symbol}
413 % \end{syntax}
414 %\end{function}
415 % Creates a new note type. The \meta{note name} becomes the command name
416 % (e.g.\ passing |question| creates \cs{question} and \cs{zebraquestion}), and
417 % \meta{xcolor name} sets its colour. The colour must be a named colour already
418 % known to \pkg{xcolor}; define it with \cs{definecolor} or \cs{colorlet}
419 % beforehand if needed. The optional \meta{symbol} overrides the default margin
420 % symbol (\cs{textdbend}) for this note type only. Per-type symbols can also be
421 % changed after loading via
422 % |\zebrasetup{symbol/|\meta{type}|=|\meta{symbol}|}|.
423 % \changes{v0.8.0}{2019/07/04}{Fix new note demo}
424 % \changes{v0.8.1}{2019/07/04}{Fix doc}
425 % \begin{LaTeXdemo}
426 % \colorlet{mycyan}{cyan!80!black}
427 % \zebranewnote{question}{mycyan}[\faQuestionCircle] % \usepackage{fontawesome}
428 %
429 % When it moves to the next step, we should be fine.\question[who]{what's this?}
430 % \end{LaTeXdemo}
431 %
432 %\begin{function}{\zebraref}
433 % \begin{syntax}
434 % \cs{zebraref}\marg{label}
435 % \end{syntax}
436 %\end{function}
437 %
438 % Labels may be placed inside note bodies with the usual \cs{label} command.
439 % Standard \cs{ref} returns the note number, while \cs{zebraref} prints the
440 % note type together with the number.
441 % \begin{LaTeXdemo}
442 % The motivation section still feels too vague \todo{\label{zebra:intro}revise
443 % the introduction before submission}. The same issue appears again later
444 % \note{see Todo~\ref{zebra:intro} (that is, \zebraref{zebra:intro}) on
445 % p.~\pageref{zebra:intro}}.
446 % \end{LaTeXdemo}
447 %
448 % As in standard \LaTeX{}, labels inside notes are unavailable in
449 % \opt{final} mode because the notes themselves are suppressed.
450 %
451 %\begin{function}{\zebrasetup}
452 % \begin{syntax}
453 % \cs{zebrasetup}\marg{key\,=\,value list}
454 % \end{syntax}
455 %\end{function}
456 % Configures note appearance after loading. Accepted keys:
457 % \begin{itemize}
458 % \item |color/|\meta{type}|=|\meta{colour} --- override the
459 % colour of a note type.
460 % \item |symbol/|\meta{type}|=|\meta{symbol} --- override the
461 % margin symbol of a note type.
462 % \end{itemize}
463 % For example:
464 % \begin{LaTeXdemo}[code only]
465 % \zebrasetup{symbol/fixed=\manerrarrow} % like this doc
466 % \zebrasetup{color/todo=red}
467 % \end{LaTeXdemo}
468 %
469 %\subsection{Two-column Support}
470 %
471 % In \texttt{twocolumn} documents, the margin symbol is automatically placed on
472 % the nearest margin: left margin for the left column, right margin for the
473 % right column. No special configuration is needed. This also works correctly in
474 % combination with the \texttt{twoside} option.
475 % \lstinputlisting[
476 % basicstyle=\small\ttfamily,
477 % frame=l,
478 % backgroundcolor=\color{gray!5},
479 % firstline=3, ^^A docstrip adds 2 more lines
480 % keywordstyle=\bfseries\color{blue},
481 % language={[LaTeX]TeX},
482 % moretexcs={todo,note,comment,fixed,placeholder,zebrasetup},
483 % ]{\jobname-demo-twocol.tex}
484 %
485 % The code above produces the following output:
486 %
487 % \begin{center}
488 % \fbox{\includegraphics[width=\linewidth,page=1]{zebra-demo-twocol}}
489 % \end{center}
490 %
491 % \subsection{Limitations}
492 %
493 % \begin{itemize}
494 % \item Notes in moving arguments such as \cs{section} and \cs{caption}
495 % should use \cs{label} for stable numbering. Unlabelled notes there may
496 % be counted again when replayed in contents lists or running heads.
497 % \item A labelled note and an unlabelled note with the same type, author,
498 % and body may be treated as the same replay. Add a \cs{label}, vary the
499 % text, or avoid identical note bodies.
500 % \item Identical unlabelled notes on the same source line, such as
501 % |\todo{x}\todo{x}|, collapse to one note.
502 % \item In \opt{final} mode, labels inside notes are unavailable. In
503 % \opt{unnumbered} mode, the detailed list is omitted and summary counts
504 % are only an upper-bound estimate.
505 % \item \cs{zebranewnote} expects command-name-safe note names and colours
506 % already known to \pkg{xcolor}; invalid values are left to \TeX{} or
507 % \pkg{xcolor} errors.
508 % \end{itemize}
509 %
510 %
511 %
512 %\end{documentation}
513 %
514 %\begin{implementation}
515 %
516 %\section{Implementation}
517 %
518 % \begin{macrocode}
519 %<*package>
520 % \end{macrocode}
521 %
522 % \begin{macrocode}
523 %<@@=zebra>
524 % \end{macrocode}
525 %
526 % Version data to start with.
527 % \begin{macrocode}
528 \NeedsTeXFormat{LaTeX2e}[2022-06-01]
529 \ProvidesExplPackage{zebra}
530 {2026/05/20}
531 {2.0.0}
532 {Writing Revision Toolkit}
533 % \end{macrocode}
534 %
535 %\subsection{Package options}
536 %
537 % Package options \opt{draft}, \opt{sort}, and \opt{unnumbered} are created using
538 % the kernel key--value interface available since \LaTeX{} 2022-06-01.
539 % Post-load configuration (\cs{zebrasetup}) uses a separate
540 % \texttt{zebra-setup} key family with \texttt{color/\meta{type}} and
541 % \texttt{symbol/\meta{type}} sub-families.
542 % \begin{macrocode}
543 \bool_new:N \l@@_draft_bool
544 \bool_new:N \l@@_emit_label_bool
545 \bool_new:N \l@@_sort_none_bool
546 \bool_new:N \l@@_unnumbered_bool
547 \seq_new:N \g@@_note_types_seq
548 \prop_new:N \g@@_note_colors_prop
549 \prop_new:N \g@@_note_public_alias_prop
550 \int_new:N \g@@_note_id_int
551 \tl_new:N \l@@_note_target_tl
552 \tl_new:N \l@@_note_color_tl
553 \tl_new:N \l@@_note_ref_type_tl
554 \tl_new:N \l@@_summary_rows_tl
555 \int_new:N \l@@_total_notes_int
556 \prop_new:N \g@@_note_symbols_prop
557 \tl_new:N \l@@_symbol_tl
558 \tl_set:Nn \l@@_symbol_tl { \textdbend }
559
560 \msg_new:nnn { zebra } { command-taken }
561 {
562 The~command~'\iow_char:N\\#1'~is~already~defined.~
563 Use~'\iow_char:N\\zebra#1'~instead.
564 }
565 \msg_new:nnn { zebra } { duplicate-note-label }
566 { Note~label~'#1'~used~by~a~different~note;~second~note~gets~
567 its~own~identity. }
568
569 \prg_new_conditional:Npnn \@@_if_package_loaded:n #1 { T , F , TF }
570 {
571 \cs_if_exist:cTF { ver@#1.sty }
572 { \prg_return_true: }
573 { \prg_return_false: }
574 }
575
576 \keys_define:nn { zebra }
577 {
578 draft .bool_set:N = \l@@_draft_bool,
579 draft .initial:n = true,
580 final .meta:n = { draft = false },
581 sort .choice:,
582 sort / type .code:n = { \bool_set_false:N \l@@_sort_none_bool },
583 sort / none .code:n = { \bool_set_true:N \l@@_sort_none_bool },
584 sort .initial:n = none,
585 unnumbered .bool_set:N = \l@@_unnumbered_bool,
586 unnumbered .initial:n = false,
587 }
588 \ProcessKeyOptions [ zebra ]
589 \keys_define:nn { zebra-setup / color }
590 {
591 unknown .code:n =
592 { \prop_gput:NVn \g@@_note_colors_prop \l_keys_key_str {#1} }
593 }
594 \keys_define:nn { zebra-setup / symbol }
595 {
596 unknown .code:n =
597 { \prop_gput:NVn \g@@_note_symbols_prop \l_keys_key_str {#1} }
598 }
599 % \end{macrocode}
600 %
601 % \subsection{Moving-argument deduplication}
602 %
603 % Notes inside moving arguments (\cs{section}, \cs{caption}, etc.) may be
604 % processed more than once per compilation pass. Two separate problems
605 % are handled independently:
606 %
607 % \paragraph{Problem A --- \cs{sbox} re-measurement.}
608 % \cs{@makecaption} typesets the caption in an \cs{sbox} for width
609 % measurement, then typesets it again if it is long. Both executions
610 % share the same \cs{inputlineno}, so the \emph{instance key}
611 % (\meta{type}\verb"|"\meta{author}\verb"|"\meta{body}\verb"|"\cs{inputlineno})
612 % catches the replay for both labeled and unlabeled notes. The second
613 % execution reuses the first's allocation and re-renders, so writes
614 % that were lost inside the discarded \cs{sbox} are re-emitted by the
615 % actual typesetting pass.
616 %
617 % \paragraph{Problem B --- TOC/LOF/header replay.}
618 % The note token is written verbatim to \texttt{.toc}/\texttt{.lof}/marks
619 % and re-executed in a secondary context with a different
620 % \cs{inputlineno}. For \emph{labeled} notes the replay is caught by
621 % two mechanisms:
622 % \begin{enumerate}
623 % \item A \emph{stable key} (\meta{type}\verb"|"\meta{label name})
624 % stored alongside the allocation; a later encounter from
625 % marks/headers that still carries the \cs{label} finds this key
626 % and suppresses.
627 % \item A \emph{content signature}
628 % (\meta{type}\verb"|"\meta{author}\verb"|"\meta{sanitised body})
629 % written to the \texttt{.aux} file; on the next pass, TOC/LOF
630 % encounters whose \cs{label} was consumed by
631 % \cs{protected@write}'s \cs{edef} match the signature and
632 % suppress.
633 % \end{enumerate}
634 % Unlabeled notes in moving arguments receive independent allocations
635 % on each replay (cosmetic duplicate on TOC/LOF/marks); adding
636 % \cs{label} is the recommended fix when stable replay behaviour is
637 % required.
638 %
639 % \paragraph{Limitation --- same-line same-body unlabeled.}
640 % Two unlabeled notes with identical body on the same source line
641 % (e.g.\ \cs{todo}\verb"{x}"\cs{todo}\verb"{x}") share an instance key
642 % with a single \cs{sbox} replay of the same source location and are
643 % indistinguishable from it at the TeX level. Case~1 collapses the
644 % second occurrence into the first. Workarounds: split across lines,
645 % vary the body, or add \cs{label}. Notes inside \cs{fbox},
646 % \texttt{tabular} cells, \cs{parbox}, \texttt{minipage}, footnotes,
647 % and other inner-mode containers are unaffected --- a single source
648 % encounter records normally regardless of the surrounding mode.
649 %
650 % \begin{macrocode}
651 \RequirePackage{xcolor}
652 \RequirePackage{marginnote}
653 \cs_new_eq:NN \@@_kernel_label:n \label
654 %% -- dedup data structures --
655 %% Maps any key (instance, stable, or content-sig) to the allocation.
656 \prop_new:N \g@@_note_target_prop
657 \prop_new:N \g@@_note_display_prop
658 %% Content signatures of labeled notes from previous pass (.aux).
659 \prop_new:N \g@@_note_sig_known_prop
660 %% Content signatures written this pass (dedup aux writes).
661 \prop_new:N \g@@_note_sig_written_prop
662 %% Content signature stored per stable key (for label-conflict detection).
663 \prop_new:N \g@@_note_stable_sig_prop
664 %% Group-local set of targets whose \label has been emitted. Sbox
665 %% boundaries reset it (so caption replay re-emits after the sbox is
666 %% discarded), while a same-source-line repeat in body text sees the
667 %% prior emission and skips the redundant \label, avoiding
668 %% multiply-defined labels.
669 \prop_new:N \l@@_label_emitted_prop
670 \tl_new:N \l@@_note_display_tl
671 \tl_new:N \l@@_note_key_tl
672 %% Instance key: unique per source location.
673 \cs_new:Npn \@@_instance_key:nnn #1#2#3
674 {
675 \tl_to_str:n {#1}
676 | \tl_to_str:n {#2}
677 | \tl_to_str:n {#3}
678 | \int_eval:n { \tex_inputlineno:D }
679 }
680 %% Content signature: body stringified with ALL \label{...} stripped.
681 %% Matches across body (has labels), TOC (labels consumed by \edef),
682 %% and running heads (which may uppercase the author/body text).
683 %% The optional \protect prefix covers marks and \protected@write paths.
684 %% Uses replace_all so that multiple labels are all stripped.
685 \cs_new_protected:Npn \@@_content_sig:nnnN #1#2#3#4
686 {
687 \tl_set:Nx \l_tmpa_tl { \tl_to_str:n {#3} }
688 \regex_replace_all:nnN
689 { (?: \\protect \s* )? \\label \s* \{ [^{}]* \} } { } \l_tmpa_tl
690 \tl_set:Nx #4
691 {
692 \tl_to_str:n {#1}
693 | \str_lowercase:f { \tl_to_str:n {#2} }
694 | \str_lowercase:f { \l_tmpa_tl }
695 }
696 }
697 %% Extract the last \label name from the stringified body
698 %% (the greedy \A.* consumes up to the rightmost \label). Both the
699 %% original encounter and any replay run through this same regex,
700 %% so they agree on which label to use as the stable key.
701 %% Sets #2 to the label name, or clears it if none found.
702 %% The optional \protect prefix covers marks and \protected@write paths.
703 \cs_new_protected:Npn \@@_extract_label:nN #1#2
704 {
705 \tl_set:Nx \l_tmpb_tl { \tl_to_str:n {#1} }
706 \tl_set_eq:NN \l_tmpc_tl \l_tmpb_tl
707 \regex_replace_once:nnN
708 { \A .* (?: \\protect \s* )? \\label \s* \{ ([^{}]*) \} .* \Z }
709 { \1 } \l_tmpb_tl
710 \tl_if_eq:NNTF \l_tmpb_tl \l_tmpc_tl
711 { \tl_clear:N #2 }
712 { \tl_set_eq:NN #2 \l_tmpb_tl }
713 }
714 %% Stable key for labeled notes.
715 %% #2 is expected to be already stringified (from regex extraction),
716 %% so no \tl_to_str is applied — otherwise an unexpanded variable
717 %% token would be stringified instead of its value.
718 \cs_new:Npn \@@_stable_key:nn #1#2
719 { \tl_to_str:n {#1} | label | #2 }
720 %% Allocate a fresh note: increment the type counter, generate
721 %% a unique hypertarget name, and record the note in the list body.
722 \cs_new_protected:Npn \@@_allocate_note:nnn #1#2#3
723 {
724 \int_gincr:c { g@@_note_count_#1_int }
725 \tl_set:Nx \l@@_note_display_tl { \@@_note_count:n {#1} }
726 \int_gincr:N \g@@_note_id_int
727 \tl_set:Nx \l@@_note_target_tl
728 { zebranote.\int_use:N \g@@_note_id_int }
729 \@@_record_note:nnnnn
730 {#1}
731 { \l@@_note_display_tl }
732 {#2}
733 {#3}
734 { \l@@_note_target_tl }
735 }
736 %% Aux-file interface: record a content signature together with the
737 %% originating instance key. A later encounter whose instance key
738 %% differs from the stored one is a replay and is suppressed.
739 %% Re-stringify for catcode normalisation.
740 \cs_new_protected:Npn \zebra@sig #1#2
741 {
742 \tl_set:Nx \l_tmpa_tl { \tl_to_str:n {#1} }
743 \tl_set:Nx \l_tmpb_tl { \tl_to_str:n {#2} }
744 \prop_gput:NVV \g@@_note_sig_known_prop \l_tmpa_tl \l_tmpb_tl
745 }
746 \cs_new_protected:Npn \@@_write_sig:NN #1#2
747 {
748 \prop_if_in:NVF \g@@_note_sig_written_prop #1
749 {
750 \immediate\write \@auxout
751 { \string\zebra@sig { \tl_use:N #1 } { \tl_use:N #2 } }
752 \prop_gput:NVn \g@@_note_sig_written_prop #1 { 1 }
753 }
754 }
755 \cs_if_exist:NTF \dbend
756 {
757 \cs_set_eq:NN \@@_saved_dbend: \dbend
758 \cs_undefine:N \dbend
759 \RequirePackage{manfnt}
760 \cs_set_eq:NN \dbend \@@_saved_dbend:
761 }
762 { \RequirePackage{manfnt} }
763 \cs_new:Npn \@@_pdfstring_note:
764 #1
765 {
766 \str_if_eq:eeT { \tl_to_str:n {#1} } { [ }
767 { \@@_pdfstring_note_opt:w }
768 }
769 \cs_new:Npn \@@_pdfstring_note_opt:w #1 ] #2 { }
770 \cs_new:Npn \@@_target:nn #1#2 {#2}
771 \cs_new:Npn \@@_link:nn #1#2 {#2}
772 \cs_new:Npn \@@_pageref:n #1 { \pageref {#1} }
773 \cs_new:Npn \@@_zebra_label_name:n #1 { #1@zebra }
774 \cs_new:Npn \@@_zebra_label_type:n #1
775 {
776 \exp_after:wN \use_i:nn
777 \cs:w r@\@@_zebra_label_name:n {#1}\cs_end:
778 { }
779 }
780 \cs_new_protected:Npn \@@_write_zebra_label:n #1
781 {
782 \protected@write \@auxout { }
783 {
784 \string\newlabel{\@@_zebra_label_name:n {#1}}
785 {{\exp_not:V \l@@_note_ref_type_tl}{}}
786 }
787 }
788 \cs_new_protected:Npn \@@_note_label:n #1
789 {
790 \@@_kernel_label:n {#1}
791 \@@_write_zebra_label:n {#1}
792 }
793 \cs_new_protected:Npn \@@_zebra_ref:n #1
794 {
795 \cs_if_exist:cTF { r@\@@_zebra_label_name:n {#1} }
796 { \@@_zebra_label_type:n {#1}~\ref{#1} }
797 { \ref{#1} }
798 }
799 \NewDocumentCommand \zebraref { m }
800 {
801 \bool_if:NTF \l@@_unnumbered_bool
802 { \ref{#1} }
803 { \@@_zebra_ref:n {#1} }
804 }
805 \cs_new_protected:Npn \@@_apply_pdfstring_defs:
806 {
807 \pdfstringdefDisableCommands
808 {
809 \cs_set:Npn \zebraref ##1 { \ref{##1} }
810 \seq_map_inline:Nn \g@@_note_types_seq
811 {
812 \cs_set_eq:cN { zebra##1 } \@@_pdfstring_note:
813 \prop_if_in:NnT \g@@_note_public_alias_prop { ##1 }
814 { \cs_set_eq:cN { ##1 } \@@_pdfstring_note: }
815 }
816 }
817 }
818 \cs_new_protected:Npn \@@_setup_hyperref:
819 {
820 \cs_set:Npn \@@_target:nn ##1##2 {##2}
821 \cs_set:Npn \@@_link:nn ##1##2 {##2}
822 \cs_set:Npn \@@_pageref:n ##1 { \pageref {##1} }
823 \@@_if_package_loaded:nT { hyperref }
824 {
825 \cs_set:Npn \@@_pageref:n ##1 { \pageref* {##1} }
826 \cs_set:Npn \@@_target:nn ##1##2 { \hypertarget{##1}{##2} }
827 \cs_set:Npn \@@_link:nn ##1##2 { \hyperlink{##1}{##2} }
828 \@@_apply_pdfstring_defs:
829 }
830 }
831 \hook_gput_code:nnn { begindocument } { zebra }
832 { \@@_setup_hyperref: }
833 % \end{macrocode}
834 %
835 % \subsection{Main notes macros}
836 % Various helper macros are defined before reaching out to
837 % the \cs{todo} commands.
838 %
839 % Place the margin note on the nearest margin. Takes two arguments:
840 % |#1| for the left margin (number then symbol) and |#2| for the right
841 % margin (symbol then number), so the symbol always sits closest to the
842 % text column. In single-column mode \cs{marginnote} is used with the
843 % right-margin variant as default. In twocolumn mode \cs{marginpar}
844 % positions the symbol close to the text column reliably (it picks
845 % side from \cs{if@firstcolumn}, not from a \texttt{.aux} round trip),
846 % so we keep that path for the body. We must, however, route around
847 % the contexts where \cs{marginpar} would crash with ``Float(s)
848 % lost'': caption sboxes (inner mode), caption parboxes (signalled by
849 % \cs{@captype}), and the wide \cs{vbox} that \cs{@topnewpage} builds
850 % for \cs{title} (signalled by \cs{hsize}${}>{}$\cs{columnwidth}).
851 % Those contexts fall back to \cs{marginnote}, where we additionally
852 % replicate \cs{@marginparreset} (\cs{@parboxrestore} +
853 % \cs{normalfont}\cs{normalsize}) so the marker does not inherit a
854 % \cs{Huge} font from \cs{title}.
855 % \begin{macrocode}
856 \cs_new_protected:Npn \@@_margin_note:nn #1#2
857 {
858 \legacy_if:nTF { @twocolumn }
859 {
860 \bool_lazy_or:nnTF
861 { \mode_if_inner_p: }
862 {
863 \bool_lazy_or_p:nn
864 { \cs_if_exist_p:N \@captype }
865 { \dim_compare_p:nNn { \hsize } > { \columnwidth } }
866 }
867 {
868 \marginnote
869 [ { \@parboxrestore \normalfont \normalsize #1 } ]
870 { \@parboxrestore \normalfont \normalsize #2 }
871 }
872 {
873 \marginpar
874 [ { \makebox[\marginparwidth][r]{#1} } ]
875 { \makebox[\marginparwidth][l]{#2} }
876 }
877 }
878 { \marginnote[#1]{#2} }
879 }
880 \cs_new:Npn \@@_prepend:nn #1#2
881 { \tl_if_blank:nTF {#2} {} {#1#2} }
882 \cs_new:Npn \@@_capitalize_type:n #1
883 { \text_uppercase:n { \tl_head:n {#1} } \tl_tail:n {#1} }
884 \cs_new:Npn \@@_note_count:n #1
885 { \int_use:c { g@@_note_count_#1_int } }
886 \cs_new:Npn \@@_note_color:n #1
887 { \prop_item:Nn \g@@_note_colors_prop {#1} }
888 \cs_new:Npn \@@_note_symbol:n #1
889 {
890 \prop_if_in:NnTF \g@@_note_symbols_prop {#1}
891 { \prop_item:Nn \g@@_note_symbols_prop {#1} }
892 { \l@@_symbol_tl }
893 }
894 \cs_new_protected:Npn \@@_new_listbody:n #1
895 { \tl_new:c { g@@_listbody_#1_tl } }
896 \tl_new:N \g@@_listbody_all_tl
897 \cs_new:Npn \@@_use_listbody:n #1
898 { \tl_use:c { g@@_listbody_#1_tl } }
899 \cs_new_protected:Npn \@@_record_note:nnnnn #1#2#3#4#5
900 {
901 \tl_gput_right:cx
902 {
903 \bool_if:NTF \l@@_sort_none_bool
904 { g@@_listbody_all_tl }
905 { g@@_listbody_#1_tl }
906 }
907 {
908 \exp_not:N \@@_list_entry:nnnnn
909 { \exp_not:n {#1} }
910 {#2}
911 { \exp_not:n {#3} }
912 { \exp_not:n {#4} }
913 {#5}
914 }
915 }
916 %% \@@_note_unnumbered:nnn {type}{author}{body}
917 %% Fast path for the \opt{unnumbered} option: skip dedup, .aux
918 %% signatures and list registration entirely. The counter is still
919 %% bumped on every call (so the summary table reflects rough counts;
920 %% notes inside captions/TOC/marks may be over-counted, which is the
921 %% accepted trade-off for cutting out the fragile bookkeeping).
922 \cs_new_protected:Npn \@@_note_unnumbered:nnn #1#2#3
923 {
924 \bool_if:NT \l@@_draft_bool
925 {
926 \tl_set:Nx \l@@_note_color_tl { \@@_note_color:n {#1} }
927 \int_gincr:c { g@@_note_count_#1_int }
928 \@@_render_note:nnn {#1} {#2} {#3}
929 }
930 }
931 %% \@@_note:nnn {type}{author}{body}
932 %% Main entry point: dispatch to the lightweight unnumbered path or to
933 %% the numbered path with deduplication/bookkeeping.
934 \cs_new_protected:Npn \@@_note:nnn #1#2#3
935 {
936 \bool_if:NTF \l@@_unnumbered_bool
937 { \@@_note_unnumbered:nnn {#1} {#2} {#3} }
938 { \@@_note_numbered:nnn {#1} {#2} {#3} }
939 }
940 %% Numbered path. Four cases:
941 %% Case 1 — sbox reuse: instance_key found → reuse, render
942 %% Case 2 — stable key: label found, stable_key in prop → suppress
943 %% Case 3 — content sig: sig in .aux data → suppress
944 %% Case 4 — new note: allocate, render
945 %% Case 1 also catches an unlabeled same-source-line same-body pair
946 %% (\todo{x}\todo{x}); the second is collapsed. Two such notes are
947 %% indistinguishable at TeX level from a single note replayed by an
948 %% sbox/moving argument, so this collision is documented and resolved
949 %% by adding \label or splitting the line.
950 \cs_new_protected:Npn \@@_note_numbered:nnn #1#2#3
951 {
952 \bool_if:NT \l@@_draft_bool
953 {
954 \tl_set:Nx \l@@_note_color_tl { \@@_note_color:n {#1} }
955 %% Case 1: sbox reuse (same \inputlineno)
956 \tl_set:Nx \l@@_note_key_tl
957 { \@@_instance_key:nnn {#1} {#2} {#3} }
958 \prop_get:NVNTF \g@@_note_target_prop \l@@_note_key_tl
959 \l@@_note_target_tl
960 {
961 \prop_get:NVN \g@@_note_display_prop \l@@_note_key_tl
962 \l@@_note_display_tl
963 \@@_render_note:nnn {#1} {#2} {#3}
964 }
965 {
966 %% Extract label and compute content signature
967 \@@_extract_label:nN {#3} \l_tmpb_tl
968 \@@_content_sig:nnnN {#1} {#2} {#3} \l_tmpa_tl
969 %% Case 2: stable-key suppress (labeled, marks/headers).
970 %% If the stable key exists AND the content signature
971 %% matches, this encounter is a replay → suppress.
972 %% Different content signature = label reuse → warn and
973 %% let Case 4 allocate independently.
974 \bool_set_false:N \l_tmpa_bool
975 \tl_if_empty:NF \l_tmpb_tl
976 {
977 \tl_set:Nx \l@@_note_key_tl
978 { \@@_stable_key:nn {#1} { \l_tmpb_tl } }
979 \prop_get:NVNT \g@@_note_stable_sig_prop
980 \l@@_note_key_tl \l_tmpc_tl
981 {
982 \tl_if_eq:NNTF \l_tmpa_tl \l_tmpc_tl
983 { \bool_set_true:N \l_tmpa_bool }
984 {
985 \msg_warning:nnV { zebra }
986 { duplicate-note-label } \l_tmpb_tl
987 }
988 }
989 }
990 %% Case 3: content-sig suppress (TOC/LOF/marks replay).
991 %% Only unlabeled current encounters may be suppressed by
992 %% content signature; labeled encounters already have a
993 %% strong identity via the stable key. Suppress only if
994 %% the stored instance key differs from the current one —
995 %% same key means it is the original note, not a replay.
996 \bool_if:NF \l_tmpa_bool
997 {
998 \tl_if_empty:NT \l_tmpb_tl
999 {
1000 \prop_get:NVNT \g@@_note_sig_known_prop
1001 \l_tmpa_tl \l_tmpc_tl
1002 {
1003 \tl_set:Nx \l_tmpd_tl
1004 { \@@_instance_key:nnn {#1} {#2} {#3} }
1005 \tl_if_eq:NNF \l_tmpc_tl \l_tmpd_tl
1006 { \bool_set_true:N \l_tmpa_bool }
1007 }
1008 }
1009 }
1010 \bool_if:NF \l_tmpa_bool
1011 {
1012 %% Case 4: new note — allocate and render
1013 \tl_set:Nx \l@@_note_key_tl
1014 { \@@_instance_key:nnn {#1} {#2} {#3} }
1015 \@@_allocate_note:nnn {#1} {#2} {#3}
1016 \prop_gput:NVV \g@@_note_target_prop
1017 \l@@_note_key_tl \l@@_note_target_tl
1018 \prop_gput:NVV \g@@_note_display_prop
1019 \l@@_note_key_tl \l@@_note_display_tl
1020 %% For labeled notes: register stable key + write sig,
1021 %% but only if the stable key is not already claimed by
1022 %% an earlier note (label-conflict case).
1023 \tl_if_empty:NF \l_tmpb_tl
1024 {
1025 \tl_set:Nx \l@@_note_key_tl
1026 { \@@_stable_key:nn {#1} { \l_tmpb_tl } }
1027 \prop_if_in:NVF \g@@_note_stable_sig_prop
1028 \l@@_note_key_tl
1029 {
1030 \prop_gput:NVV \g@@_note_target_prop
1031 \l@@_note_key_tl \l@@_note_target_tl
1032 \prop_gput:NVV \g@@_note_display_prop
1033 \l@@_note_key_tl \l@@_note_display_tl
1034 \prop_gput:NVV \g@@_note_stable_sig_prop
1035 \l@@_note_key_tl \l_tmpa_tl
1036 \tl_set:Nx \l_tmpc_tl
1037 { \@@_instance_key:nnn {#1} {#2} {#3} }
1038 \@@_write_sig:NN \l_tmpa_tl \l_tmpc_tl
1039 }
1040 }
1041 \@@_render_note:nnn {#1} {#2} {#3}
1042 }
1043 %% Cases 2–3: suppress — no output
1044 }
1045 }
1046 }
1047 %% Full render: hypertarget, target label, margin note, inline text.
1048 %% In \opt{unnumbered} mode the label/hypertarget setup is skipped so a
1049 %% \cs{label} inside the note body falls through to the surrounding
1050 %% \cs{@currentlabel} (e.g.\ the section number), and \cs{zebraref}
1051 %% degrades cleanly to \cs{ref}.
1052 \cs_new_protected:Npn \@@_render_note:nnn #1#2#3
1053 {
1054 %% Decide outside render's group whether to emit the kernel label.
1055 %% The flag lives in the caller's group: sbox/parbox boundaries reset
1056 %% it (so caption replay re-emits), but a same-line repeat in body
1057 %% text sees the prior emission and skips the redundant \label.
1058 \bool_set_false:N \l@@_emit_label_bool
1059 \bool_if:NF \l@@_unnumbered_bool
1060 {
1061 \prop_if_in:NVF \l@@_label_emitted_prop \l@@_note_target_tl
1062 {
1063 \bool_set_true:N \l@@_emit_label_bool
1064 \prop_put:NVn \l@@_label_emitted_prop
1065 \l@@_note_target_tl { 1 }
1066 }
1067 }
1068 \group_begin:
1069 \bool_if:NF \l@@_unnumbered_bool
1070 {
1071 \protected@edef \@currentlabel { \l@@_note_display_tl }
1072 \@@_if_package_loaded:nT { hyperref }
1073 { \tl_set:Nx \@currentHref { \l@@_note_target_tl } }
1074 \tl_set:Nx \l@@_note_ref_type_tl
1075 { \@@_capitalize_type:n {#1} }
1076 \@@_target:nn { \l@@_note_target_tl } {}
1077 \bool_if:NT \l@@_emit_label_bool
1078 { \exp_args:NV \@@_kernel_label:n \l@@_note_target_tl }
1079 }
1080 \@@_margin_note:nn
1081 {\textcolor{\l@@_note_color_tl}{%
1082 \bool_if:NF \l@@_unnumbered_bool
1083 { {\bfseries\l@@_note_display_tl}\kern1pt }%
1084 \@@_note_symbol:n {#1}}}
1085 {\textcolor{\l@@_note_color_tl}{%
1086 \@@_note_symbol:n {#1}%
1087 \bool_if:NF \l@@_unnumbered_bool
1088 { \kern1pt {\bfseries\l@@_note_display_tl} }}}%
1089 \bool_if:NF \l@@_unnumbered_bool
1090 { \cs_set_eq:NN \label \@@_note_label:n }
1091 \textcolor{\l@@_note_color_tl}{[\colorbox[gray]{0.97}{%
1092 \textcolor{\l@@_note_color_tl !70!black}{%
1093 \textsc{\MakeLowercase{\MakeUppercase#1}}%
1094 \bool_if:NF \l@@_unnumbered_bool
1095 { ~\l@@_note_display_tl }%
1096 \texttt{\@@_prepend:nn {@}{#2}}:}} #3]}%
1097 \group_end:
1098 }
1099 \cs_new_protected:Npn \@@_new_note_type:nn #1#2
1100 { \@@_new_note_type:nnn {#1} {#2} {} }
1101 \cs_new_protected:Npn \@@_new_note_type:nnn #1#2#3
1102 {
1103 \seq_gput_right:Nn \g@@_note_types_seq {#1}
1104 \prop_if_in:NnF \g@@_note_colors_prop {#1}
1105 { \prop_gput:Nnn \g@@_note_colors_prop {#1} {#2} }
1106 \tl_if_blank:nF {#3}
1107 {
1108 \prop_if_in:NnF \g@@_note_symbols_prop {#1}
1109 { \prop_gput:Nnn \g@@_note_symbols_prop {#1} {#3} }
1110 }
1111 \int_new:c { g@@_note_count_#1_int }
1112 \@@_new_listbody:n {#1}
1113 \exp_args:Nc \NewDocumentCommand { zebra#1 } { O{} m }
1114 { \@@_note:nnn {#1}{##1}{##2} }
1115 \cs_if_exist:cTF {#1}
1116 { \msg_warning:nnn { zebra } { command-taken } {#1} }
1117 {
1118 \cs_set_eq:cc {#1} {zebra#1}
1119 \prop_gput:Nnn \g@@_note_public_alias_prop {#1} { true }
1120 }
1121 \@@_if_package_loaded:nT { hyperref }
1122 { \@@_apply_pdfstring_defs: }
1123 }
1124 \cs_new_protected:Npn \@@_list_entry:nnnnn #1#2#3#4#5
1125 {
1126 \par\noindent
1127 \textcolor{\@@_note_color:n {#1}}{%
1128 \textbf{\@@_capitalize_type:n {#1}~#2}%
1129 \tl_if_blank:nF {#3} { \enspace \texttt{\@@_prepend:nn {@}{#3}} }}%
1130 \nobreak\dotfill
1131 \@@_link:nn {#5} { \@@_pageref:n {#5} }%
1132 \par
1133 \begingroup
1134 \leftskip=2em
1135 \rightskip=2em
1136 \parindent=0pt
1137 \cs_set_eq:NN \label \use_none:n
1138 #4\par
1139 \endgroup
1140 }
1141 \cs_new_protected:Npn \@@_print_note_group:n #1
1142 {
1143 \int_compare:nNnT { \@@_note_count:n {#1} } > { 0 }
1144 {
1145 \par\medskip
1146 \@@_use_listbody:n {#1}
1147 }
1148 }
1149 \cs_new_protected:Npn \@@_print_notes_inorder:
1150 {
1151 \tl_if_empty:NF \g@@_listbody_all_tl
1152 { \par\medskip \tl_use:N \g@@_listbody_all_tl }
1153 }
1154 \cs_new_protected:Npn \@@_summary_row:n #1
1155 {
1156 \int_compare:nNnT { \@@_note_count:n {#1} } > { 0 }
1157 {
1158 \int_add:Nn \l@@_total_notes_int { \@@_note_count:n {#1} }
1159 \tl_put_right:Nx \l@@_summary_rows_tl
1160 {
1161 \exp_not:N \textcolor
1162 { \@@_note_color:n {#1} }
1163 {#1}
1164 \exp_not:N &
1165 \@@_note_count:n {#1}
1166 \exp_not:N \\
1167 }
1168 }
1169 }
1170 \cs_new_protected:Npn \@@_print_notes:
1171 {
1172 \tl_clear:N \l@@_summary_rows_tl
1173 \int_zero:N \l@@_total_notes_int
1174 \seq_map_inline:Nn \g@@_note_types_seq
1175 { \@@_summary_row:n {##1} }
1176 \tl_if_empty:NF \l@@_summary_rows_tl
1177 {
1178 \par\nobreak
1179 \noindent\dotfill\par\medskip
1180 \nobreak
1181 \noindent\textbf{\Large Zebra~Notes}
1182 \par \medskip
1183 \begin{center}
1184 \begin{tabular}{lr}
1185 \hline
1186 \textbf{Type} & \textbf{Count} \\\hline
1187 \tl_use:N \l@@_summary_rows_tl
1188 \hline
1189 \textbf{Total} & \textbf{\int_use:N \l@@_total_notes_int} \\
1190 \hline
1191 \end{tabular}
1192 \end{center}
1193 \bool_if:NF \l@@_unnumbered_bool
1194 {
1195 \par \medskip
1196 \begingroup
1197 \small
1198 \noindent{\bfseries List~of~notes}\par
1199 \nobreak
1200 \bool_if:NTF \l@@_sort_none_bool
1201 { \@@_print_notes_inorder: }
1202 {
1203 \seq_map_inline:Nn \g@@_note_types_seq
1204 { \@@_print_note_group:n {##1} }
1205 }
1206 \endgroup
1207 }
1208 }
1209 }
1210 % \end{macrocode}
1211 %
1212 % \begin{macro}{\zebranewnote}
1213 % All note types are created with \cs{zebranewnote}.
1214 % \changes{v0.8.0}{2019/07/04}{Fix on \cs{global} for examples}
1215 % \begin{macrocode}
1216 \NewDocumentCommand \zebranewnote { m m O{} }
1217 { \@@_new_note_type:nnn {#1} {#2} {#3} }
1218 % \end{macrocode}
1219 % \end{macro}
1220 %
1221 % \begin{macro}{\zebrasetup}
1222 % Applies configuration keys after loading using the
1223 % \texttt{zebra-setup} key family.
1224 % \begin{macrocode}
1225 \NewDocumentCommand \zebrasetup { m }
1226 { \keys_set:nn { zebra-setup } {#1} }
1227 % \end{macrocode}
1228 % \end{macro}
1229 %
1230 % \begin{macro}{\todo}
1231 % \begin{macro}{\note}
1232 % \begin{macro}{\fixed}
1233 % \begin{macro}{\comment}
1234 % \begin{macro}{\placeholder}
1235 % Built-in note types, defined with \cs{zebranewnote}.
1236 % \begin{macrocode}
1237 \zebranewnote{todo}{purple}
1238 \colorlet{zebra@fixed@color}{green!50!black}
1239 \zebranewnote{fixed}{zebra@fixed@color}
1240 \zebranewnote{comment}{blue}
1241 \zebranewnote{note}{violet}
1242 \zebranewnote{placeholder}{gray}
1243 % \end{macrocode}
1244 % \end{macro}
1245 % \end{macro}
1246 % \end{macro}
1247 % \end{macro}
1248 % \end{macro}
1249 %
1250 %\subsection{Print summary at end of the document}
1251 %
1252 % A summary table and a detailed note list are inserted automatically at the
1253 % end of the document. Each note type with at least one instance is listed with
1254 % its colour and count, followed by notes in document order or grouped by type.
1255 %
1256 % \begin{macrocode}
1257 %% At end of document: print the note summary and list.
1258 %% Content signatures are written to .aux inline (at allocation time),
1259 %% so no additional end-of-document aux writes are needed.
1260 \hook_gput_code:nnn { enddocument } { zebra }
1261 {
1262 \bool_if:NT \l@@_draft_bool
1263 { \@@_print_notes: }
1264 }
1265 \ExplSyntaxOff
1266 % \end{macrocode}
1267 % \begin{macrocode}
1268 %</package>
1269 % \end{macrocode}
1270 %
1271 %\subsection{Compatibility shim}
1272 %
1273 % The old package name \pkg{zebra-goodies} is supported via a thin
1274 % wrapper that loads \pkg{zebra} and prints a deprecation warning.
1275 % \begin{macrocode}
1276 %<*compat>
1277 \NeedsTeXFormat{LaTeX2e}
1278 \ProvidesPackage{zebra-goodies}
1279 [2026/05/20 v2.0.0 Deprecated: use zebra instead]
1280 \PackageWarningNoLine{zebra-goodies}
1281 {Package 'zebra-goodies' is deprecated.\MessageBreak
1282 Use \string\usepackage{zebra} instead}
1283 \RequirePackageWithOptions{zebra}
1284 %</compat>
1285 % \end{macrocode}
1286 %
1287 %\subsection{Two-column demo}
1288 %
1289 % A standalone two-column document used to generate the demo figure
1290 % included in the documentation. It is extracted automatically by
1291 % docstrip and compiled during the build.
1292 % \begin{macrocode}
1293 %<*demo-twocol>
1294 \documentclass[twocolumn]{article}
1295 \usepackage[paperwidth=21cm,paperheight=15cm,margin=1.1cm]{geometry}
1296 \usepackage{zebra}
1297 \zebrasetup{symbol/comment=$\clubsuit$}
1298 \pagestyle{empty}
1299 \begin{document}
1300 \section{Demo name\comment{revise the name}}
1301 This draft still needs work
1302 \todo[alice]{\label{zebra:intro}revise the introduction}. The
1303 opening paragraph should also explain the main goal more plainly.
1304 Add one more citation here \note[bob]{support this claim}. A
1305 brief roadmap sentence would also make the structure easier to
1306 scan.
1307
1308 The issue raised in Todo~\ref{zebra:intro} still applies in
1309 the conclusion. The table now looks fine
1310 \fixed[carol]{alignment corrected}, but one figure is still
1311 missing \placeholder[eve]{insert the overview figure}. A short
1312 transition would also help the flow. The middle section should
1313 probably end with a clearer summary sentence before the
1314 discussion begins. That summary can stay compact, but it should
1315 signal why the next section matters.
1316
1317 Please verify the totals \note[frank]{check the numbers} and
1318 confirm the wording in the last paragraph
1319 \comment[tom]{is this sentence too strong?}. A small typo has
1320 already been fixed \fixed[heidi]{typo corrected}. The ending
1321 should stay short. The final sentence should return to the main
1322 claim rather than repeat background material. You can place
1323 \todo[judy]{summarise the findings} anywhere once the narrative
1324 is stable.
1325
1326 One more short paragraph is enough to show how \placeholder{wow,
1327 so great!} the markers stay readable in a compact two-column layout.
1328 The example is intentionally small, but it should still look like
1329 a realistic revision pass.\comment{Bye}
1330 \end{document}
1331 %</demo-twocol>
1332 % \end{macrocode}
1333 %
1334 %\end{implementation}
1335 %
1336 %\PrintChanges
1337 %\PrintIndex