# zebra

A writing revision toolkit for LaTeX. The current release focuses on inline
note-taking, providing macros (`\todo`, `\comment`, `\fixed`, `\note`,
`\placeholder`) for collaborative writing. Notes are colour-coded, numbered,
and marked in the margin. A summary table and note list are appended at the
end of the document. If `hyperref` is loaded, note-list page references link
back to the notes. The `final` option suppresses all notes for clean output.

> **Migration:** This package was previously distributed as `zebra-goodies`.
> The old name still works but prints a deprecation warning.

## Options

- `draft` / `final`: show or suppress notes. Default: `draft`.
    ```latex
    \usepackage[final]{zebra}
    ```
- `sort`: order of the detailed note list. `none` (default, document order) or `type` (grouped by note type).
    ```latex
    \usepackage[sort=type]{zebra}
    ```
- `unnumbered`: turns off note numbering. Inline markers become `[todo: ...]` (no number), the margin symbol carries no number, the end-of-document detailed note list is omitted (the summary table remains), and `\zebraref` falls back to `\ref`. Useful as a workaround if numbered notes interact badly with a particular class; the summary table count is then an upper-bound estimate. Default: disabled.
    ```latex
    \usepackage[unnumbered]{zebra}
    ```

Load `hyperref` explicitly if you want clickable note-list page references:

```latex
\usepackage{zebra}
\usepackage{hyperref}
```

## Take Notes

```latex
\todo[<who>]{bla bla}
\fixed[<who>]{bla bla}
\comment[<who>]{bla bla}
\note[<who>]{bla bla}
\placeholder[<who>]{bla bla}
```

If a short name clashes with another package, use the prefixed form:

```latex
\zebratodo[<who>]{bla bla}
\zebrafixed[<who>]{bla bla}
\zebracomment[<who>]{bla bla}
\zebranote[<who>]{bla bla}
\zebraplaceholder[<who>]{bla bla}
```

## Refer to Notes

Labels may be placed inside note bodies with the usual `\label` command.
Standard `\ref` returns the note number, while `\zebraref` prints the note
type together with the number.

```latex
\todo{\label{zebra:intro}revise the introduction}

See Todo~\ref{zebra:intro} on p.~\pageref{zebra:intro}.
See \zebraref{zebra:intro} for the full reference.
```

Labels inside notes are unavailable in `final` mode because the notes
themselves are suppressed.

Notes can appear inside moving arguments such as `\section` and `\caption`.
To ensure stable numbering, add a `\label` inside the note — the note is
then counted once regardless of how many times the heading appears (TOC,
running headers, etc.). Notes without a `\label` in moving arguments are
still safe but may receive a separate number in each context.

## Define New Notes

```latex
\colorlet{mycyan}{cyan}
\zebranewnote{question}{mycyan}              % uses default symbol
\zebranewnote{question}{mycyan}[$\diamond$]  % custom symbol for this type

\question[who]{what's this?}
```

## Customise Existing Types

Use `\zebrasetup` to change the colour or symbol of any note type after loading. Accepted keys:

- `color/<type>=<colour>` — override the colour of a note type.
- `symbol/<type>=<symbol>` — override the margin symbol of a note type.

```latex
\zebrasetup{color/todo=red}                 % red todos
\zebrasetup{symbol/fixed=$\surd$}           % tick mark for fixed notes
\zebrasetup{color/todo=red, symbol/fixed=$\surd$}  % combine several keys
```

## Limitations

- Use `\label` for notes in `\section`, `\caption`, and similar moving arguments; unlabelled notes there may be counted again in contents lists or running heads.
- A labelled note and an unlabelled note with the same type, author, and body may be treated as the same replay. Add a label, vary the text, or avoid identical note bodies.
- Identical unlabelled notes on the same source line, such as `\todo{x}\todo{x}`, collapse to one note.
- In `final` mode, labels inside notes are unavailable. In `unnumbered` mode, the detailed list is omitted and summary counts are only an upper-bound estimate.
- `\zebranewnote` expects command-name-safe note names and colours already known to `xcolor`; invalid values are left to TeX or `xcolor` errors.

## Author

Ruini Xue <xueruini@gmail.com>

## License

Copyright (C) 2016-2026, Ruini Xue

This work may be distributed and/or modified under the conditions of
the LaTeX Project Public License (LPPL), version 1.3c. The latest
version of this license is at:

http://www.latex-project.org/lppl.txt

This work is "maintained" (as per LPPL maintenance status) by Ruini Xue.
