texchanges-doc.tex

\documentclass[11pt]{article}

\usepackage[a4paper,margin=25mm]{geometry}
\usepackage[T1]{fontenc}
\usepackage{booktabs}
\usepackage{xcolor}
\usepackage{hyperref}
\usepackage{listings}

\definecolor{txblue}{HTML}{0057B8}
\definecolor{txred}{HTML}{C62828}
\definecolor{txpaper}{HTML}{F7F3EA}
\hypersetup{
  colorlinks=true,
  linkcolor=txblue,
  urlcolor=txblue,
  pdftitle={Texchanges 0.3.0 Manual},
  pdfauthor={Phuc Nguyen}
}
\setlength{\emergencystretch}{2em}
\Urlmuskip=0mu plus 2mu\relax
\lstdefinelanguage{Texchanges}{
  language=[LaTeX]TeX,
  moretexcs={txadd,txremove,txreplace,txhighlight,txcomment,txdefineauthor,txlistofchanges}
}
\lstset{
  language=Texchanges,
  basicstyle=\ttfamily\small,
  backgroundcolor=\color{txpaper},
  frame=single,
  rulecolor=\color{black!20},
  columns=fullflexible,
  keepspaces=true,
  breaklines=true
}

\title{\textsf{texchanges}\\\large LaTeX-native track changes}
\author{Phuc Nguyen}
\date{Version 0.3.0, 18 August 2026}

\begin{document}
\maketitle

\begin{abstract}
Texchanges records additions, removals, replacements, highlights, and comments
directly in LaTeX source. The same document can show review markup, proposed
final text, or the original text. Registered authors, stable change IDs, and
decision statuses support human review and automated editing workflows.
\end{abstract}

\tableofcontents

\section{Installation}

Texchanges is distributed through TeX Live. Install it with the normal package
manager when needed and load it with:

\begin{lstlisting}
\usepackage[review]{texchanges}
\end{lstlisting}

For Overleaf projects whose TeX Live version does not contain Texchanges,
upload \path{texchanges.sty} beside the main document. The unified
\path{texchanges-overleaf.zip} bundle includes the package, the explicit
review document, the two automatic comparison revisions, and a top-level
\path{latexmkrc}. Select \path{texchanges-explicit-review.tex} as Main for
explicit review, or \path{texchanges-review.tex} as Main for automatic diff.

\section{Automatic \texttt{latexdiff}}

The automatic example uses word-level matching. A removed word such as
``new'' is marked separately while a short shared phrase such as ``system
provides'' remains unchanged. The example also demonstrates phrase
replacement, a sentence-end insertion, a change inside \verb|\emph{}|, and a
revised \texttt{itemize} list. The conditional \path{latexmkrc} runs
\texttt{latexdiff} only when \path{texchanges-review.tex} is selected as the
Main document.

Use explicit Texchanges markup or manual review for changed display math,
complex floats, and custom verbatim-like environments.

\section{Core commands}

The native API uses the source order ``old, new'' for replacements.

\begin{lstlisting}
\txadd{new text}
\txremove{old text}
\txreplace{old text}{new text}
\txhighlight{important text}
\txcomment{Check this claim.}
\end{lstlisting}

The short aliases \verb|\add|, \verb|\remove|, and \verb|\replace| are
installed only when another package has not defined them.

\section{Authors, IDs, and decisions}

\begin{lstlisting}
\txdefineauthor[name={Phuc Nguyen},color=orange]{phuc}

\txreplace[
  author=phuc,
  id=R12,
  comment={Clarify this claim.},
  status=pending
]{old text}{new text}
\end{lstlisting}

The optional keys are \texttt{author}, \texttt{id}, \texttt{comment}, and
\texttt{status}. Status accepts \texttt{pending}, \texttt{accepted}, or
\texttt{rejected}. Non-empty change IDs must be unique. A legacy optional
label such as \path|\txadd[Reviewer]{text}| remains available for visual
labels without structured author metadata.

\section{Document modes}

\begin{center}
\begin{tabular}{llll}
\toprule
Mode & Pending & Accepted & Rejected \\
\midrule
\texttt{review} & marked change & proposed text & original text \\
\texttt{final} & proposed text & proposed text & original text \\
\texttt{original} & original text & original text & original text \\
\bottomrule
\end{tabular}
\end{center}

Final mode warns when pending changes remain. Change lists and summaries are
review artifacts, so \verb|\txlistofchanges| produces no output in final or
original mode.

\section{Reports}

Detailed reports include excerpts, IDs, page numbers, and links when
\texttt{hyperref} is loaded. Summary reports group counts by author, type, and
status. Run LaTeX twice after changes to refresh report data.

\begin{lstlisting}
\txlistofchanges
\txlistofchanges[style=summary]
\txlistofchanges[
  title={Pending reviewer changes},
  show={added,replaced,commented},
  status={pending},
  author={phuc}
]
\end{lstlisting}

\section{Presentation and localization}

Presets are \texttt{texchanges}, \texttt{default}, \texttt{underlined},
\texttt{bfit}, and \texttt{nocolor}. Individual added, deleted, highlighted,
comment, and author renderers can be selected through package options or
replaced at runtime. English, British English, German, French, Italian, and
Vietnamese report labels follow Babel or Polyglossia when their caption hooks
are available.

\section{Compatibility with \texttt{changes}}

Compatibility is opt in because the replacement argument order differs.

\begin{lstlisting}
\usepackage[review,compat=changes]{texchanges}
\definechangesauthor[name={Phuc Nguyen},color=orange]{phuc}
\replaced[id=phuc,changeid=R12]{new text}{old text}
\end{lstlisting}

The compatibility option provides documented \texttt{changes} commands and
setter aliases. Its \texttt{id} key identifies an author, while
\texttt{changeid} stores the Texchanges change ID. The
\texttt{commandname\allowbreak prefix} option accepts \texttt{none}, \texttt{ifneeded},
or \texttt{always}.

\section{Resolving source markup}

The supplemental \texttt{texchanges-merge} tool can update decisions or remove
resolved markup permanently from any working directory after TeX Live installs
the executable.

\begin{lstlisting}[language=bash]
texchanges-merge paper.tex reviewed.tex --accept
texchanges-merge paper.tex final.tex --accept --merge
texchanges-merge paper.tex --reject --id R12 --in-place
\end{lstlisting}

From a source checkout, run the script directly:

\begin{lstlisting}[language=bash]
python3 scripts/texchanges-merge.py --version
\end{lstlisting}

The tool requires Python 3.10 or later and uses only the standard library.

In-place edits create a backup. The parser handles nested groups and skips
comments and common verbatim-like environments. Malformed input fails before
the destination is written.

\section{Resources and license}

Project documentation, examples, releases, and issue reporting are available
at \url{https://texchanges.dev/} and
\url{https://github.com/phucnht/texchanges}.

Texchanges is maintained by Phuc Nguyen. It may be distributed
and modified under the LaTeX Project Public License, version 1.3c or later.

\end{document}