Make the Overleaf revision editable without losing the diff

CHANGELOG.md

@@ -8,6 +8,10 @@ All notable changes to this project are documented in this file. The format is b
 
 - A playground on the documentation site: edit Texchanges markup and watch the same source render as a review, as the final document, and as the original. The preview is drawn in JavaScript rather than by LaTeX, and an Open in Overleaf button sends the same source to a real compiler with the package travelling alongside it.
 
+### Changed
+
+- The Overleaf automatic-diff example splits the revised document into a wrapper and `texchanges-revised-body.tex`, which is the file to edit. Overleaf compiles whichever open file contains `\documentclass`, so editing the old single-file revision silently switched the compiled output away from the diff; the body file has no `\documentclass`, so it can stay open while every recompile still produces the comparison.
+
 ### Fixed
 
 - A change containing something LaTeX cannot carry there now stops with a message naming the construct and the way around it, instead of a cryptic error from TeX or xcolor that never mentioned this package. This covers `\verb`, verbatim-like environments, an alignment tab that would make a change span table cells, and a footnote inside a change. Citations, indexing, cross-references, and changes within a single table cell were checked and work as before.

Makefile

@@ -41,13 +41,15 @@ dist: clean
 	cp texchanges.sty examples/explicit-review/texchanges-explicit-review.tex \
 	  examples/automatic-diff/texchanges-original.tex \
 	  examples/automatic-diff/texchanges-revised.tex \
+	  examples/automatic-diff/texchanges-revised-body.tex \
 	  examples/automatic-diff/texchanges-review.tex \
 	  examples/automatic-diff/latexmkrc \
 	  $(BUILD_DIR)/overleaf-workflow/
 	cp examples/overleaf-workflow/README.md $(BUILD_DIR)/overleaf-workflow/README.md
 	(cd $(BUILD_DIR)/overleaf-workflow && zip -q ../../$(DIST_DIR)/$(PACKAGE)-overleaf.zip \
 	  texchanges.sty texchanges-explicit-review.tex texchanges-original.tex \
-	  texchanges-revised.tex texchanges-review.tex latexmkrc README.md)
+	  texchanges-revised.tex texchanges-revised-body.tex \
+	  texchanges-review.tex latexmkrc README.md)
 
 overleaf-check: dist
 	@task_tmp=$$(mktemp -d "$${TMPDIR:-/tmp}/texchanges-overleaf.XXXXXX"); \

docs/dev/manual-testing.md

@@ -8,7 +8,7 @@ Run this before tagging a release. The automated suite compares text extracted f
 make release-check
 ```
 
-Expect 22 green cases and `Texchanges release artifacts verified.` on the last line. This covers three engines, the `l3build` log comparison, version agreement across the five copies, the CLI, the automatic `latexdiff` path, and both archives.
+Expect 23 green cases and `Texchanges release artifacts verified.` on the last line. This covers three engines, the `l3build` log comparison, version agreement across the five copies, the CLI, the automatic `latexdiff` path, and both archives.
 
 To dig into one area:
 
@@ -47,6 +47,23 @@ Edit `\providecommand{\texchangesexamplemode}{...}` in `examples/explicit-review
 
 In `final`, the `.log` must carry `Pending changes were accepted`. Restore `review` afterwards.
 
+### Moving arguments and boxed contexts
+
+The suite asserts these on extracted text; the visual half needs an eye. Compile a scratch document with `\usepackage[review]{texchanges}` containing a `\section` whose title holds a `\txreplace[author=x, id=T1]{old}{new}`, a `\tableofcontents`, `\pagestyle{headings}`, and a figure with `commentmarkup=margin` and a `\txcomment` inside it. Two pdflatex passes.
+
+| Element | Expected |
+|---|---|
+| Second pass | Compiles. A duplicate-ID error here is the pre-0.4.0 bug returning |
+| Table of contents line | Resolved text only ("new"), no strikethrough, no author label |
+| Running header on page 2 | Same resolved text |
+| Heading in the body | Full markup: struck "old", underlined "new", author label |
+| The margin comment in the figure | Rendered inline in the comment colour, with one `Falling back to an inline comment` warning in the log |
+| `\txlistofchanges` | Each change counted exactly once, however many pages and contents lines echo it |
+
+### Context diagnostics
+
+Put `\verb|x|` inside a `\txadd` and compile. The error must name texchanges and the construct ("\verb cannot be used inside a change"), not `\XC@col@rlet` or another internal. Same check with an `&` inside a change in a tabular, and a `\footnote` inside a change.
+
 ## 3. The merge CLI
 
 ```bash
@@ -82,11 +99,12 @@ python3 scripts/texchanges-merge.py /tmp/legacy.tex --accept --dry-run
 
 ## 4. Overleaf
 
-This is where most users are, and nothing automated reaches it. Upload `dist/texchanges-overleaf.zip` as a new project; the bundle holds seven files.
+This is where most users are, and nothing automated reaches it. Upload `dist/texchanges-overleaf.zip` as a new project; the bundle holds eight files.
 
 1. Set `texchanges-explicit-review.tex` as the Main document and compile. The result matches section 2.
 2. Switch the Main document to `texchanges-review.tex` and compile. `latexmkrc` runs `latexdiff` at word level, so the output shows removed words struck through and added words underlined.
-3. Change the TeX Live year under **Menu, Settings** to the oldest supported release and compile again. Version-specific expl3 differences have broken the package here before.
+3. Open `texchanges-revised-body.tex`, change a word, and recompile **while that file is open**. The output must still be the diff, now showing your edit. If the output is the plain revised document instead, Overleaf compiled the open file, which is the failure the body split exists to prevent.
+4. Change the TeX Live year under **Menu, Settings** to the oldest supported release and compile again. Version-specific expl3 differences have broken the package here before.
 
 ## 5. Website
 

examples/automatic-diff/README.md

@@ -5,16 +5,19 @@ This example compares two complete LaTeX revisions and generates a visual PDF di
 ## Files
 
 - [`texchanges-original.tex`](texchanges-original.tex), the earlier revision.
-- [`texchanges-revised.tex`](texchanges-revised.tex), the later revision.
+- [`texchanges-revised.tex`](texchanges-revised.tex), a thin wrapper around the later revision. Leave it alone.
+- [`texchanges-revised-body.tex`](texchanges-revised-body.tex), the later revision's text. **This is the file to edit.**
 - [`texchanges-review.tex`](texchanges-review.tex), select this as the Overleaf Main document.
 - [`latexmkrc`](latexmkrc), runs `latexdiff` before pdfLaTeX compiles the generated review document.
 
+The revision is split in two because Overleaf compiles whichever open file contains `\documentclass`, ignoring the Main document setting. The body file has none, so you can keep it open, edit it, and every recompile still produces the diff. `latexdiff --flatten` expands the `\input` before comparing.
+
 ## Try it on Overleaf
 
-1. Upload all four files to a blank Overleaf project.
+1. Upload all five files to a blank Overleaf project.
 2. Select `texchanges-review.tex` as the Main document.
 3. Compile with pdfLaTeX.
-4. Recompile after changing either revision to generate a fresh visual diff.
+4. Open `texchanges-revised-body.tex`, edit it, and recompile for a fresh visual diff.
 
 Edit the two filenames in `latexmkrc` to match a real project. Keep filenames free of shell metacharacters because they are part of a compile command.
 

examples/automatic-diff/texchanges-revised-body.tex

@@ -0,0 +1,18 @@
+% The revised text. Edit this file: it has no \documentclass, so opening it
+% on Overleaf keeps texchanges-review.tex as the compiled document and every
+% recompile shows the diff against texchanges-original.tex.
+\section{Introduction}
+
+The system provides selected characteristics of indoor navigation under partial observability.
+
+The evaluation retains a concise summary for each route.
+
+The prototype reports its findings clearly, with confidence intervals.
+
+The model evaluates routes with \emph{adaptive} landmarks.
+
+\begin{itemize}
+  \item The interface announces the next turn.
+  \item The study records travel time.
+  \item The reviewer verifies route completion.
+\end{itemize}

examples/automatic-diff/texchanges-revised.tex

@@ -1,3 +1,8 @@
+% The wrapper exists so the revision can be edited on Overleaf. Overleaf
+% compiles whichever open file contains \documentclass, ignoring the Main
+% document setting, so keeping \documentclass out of the file a reviewer
+% actually edits is what keeps the diff as the compiled output. Edit
+% texchanges-revised-body.tex; this file stays as it is.
 \documentclass{article}
 
 \title{Texchanges Automatic Diff}
@@ -6,21 +11,5 @@
 
 \begin{document}
 \maketitle
-
-\section{Introduction}
-
-The system provides selected characteristics of indoor navigation under partial observability.
-
-The evaluation retains a concise summary for each route.
-
-The prototype reports its findings clearly, with confidence intervals.
-
-The model evaluates routes with \emph{adaptive} landmarks.
-
-\begin{itemize}
-  \item The interface announces the next turn.
-  \item The study records travel time.
-  \item The reviewer verifies route completion.
-\end{itemize}
-
+\input{texchanges-revised-body}
 \end{document}

examples/overleaf-workflow/README.md

@@ -12,7 +12,7 @@ This bundle supports explicit Texchanges review markup and automatic `latexdiff`
 
 1. Select `texchanges-review.tex` as the Overleaf Main document.
 2. Compile with pdfLaTeX.
-3. The top-level `latexmkrc` creates `review-generated.tex` from `texchanges-original.tex` and `texchanges-revised.tex`, then compiles the visual diff.
+3. The top-level `latexmkrc` creates `review-generated.tex` from `texchanges-original.tex` and `texchanges-revised.tex`, then compiles the visual diff. Edit `texchanges-revised-body.tex` for the revised text; it has no `\documentclass`, so keeping it open does not switch Overleaf away from compiling the diff.
 
 The automatic example uses word-level matching. Short shared phrases remain unchanged, while nearby additions and removals are marked separately.
 

scripts/ctan-release.sh

@@ -33,6 +33,7 @@ cp "$PROJECT_ROOT/examples/automatic-diff/README.md" \
   "$PROJECT_ROOT/examples/automatic-diff/texchanges-original.tex" \
   "$PROJECT_ROOT/examples/automatic-diff/texchanges-review.tex" \
   "$PROJECT_ROOT/examples/automatic-diff/texchanges-revised.tex" \
+  "$PROJECT_ROOT/examples/automatic-diff/texchanges-revised-body.tex" \
   "$PACKAGE_DIR/examples/automatic-diff/"
 cp "$PROJECT_ROOT/examples/overleaf-workflow/README.md" \
   "$PACKAGE_DIR/examples/overleaf-workflow/"