diff --git a/CHANGELOG.md b/CHANGELOG.md index 2af7e3a..b1948be 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/Makefile b/Makefile index a4c31e1..00dc1ba 100644 --- a/Makefile +++ b/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"); \ diff --git a/docs/dev/manual-testing.md b/docs/dev/manual-testing.md index 0b5cb77..8db3e95 100644 --- a/docs/dev/manual-testing.md +++ b/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 diff --git a/examples/automatic-diff/README.md b/examples/automatic-diff/README.md index 71ac304..fb4744e 100644 --- a/examples/automatic-diff/README.md +++ b/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. diff --git a/examples/automatic-diff/texchanges-revised-body.tex b/examples/automatic-diff/texchanges-revised-body.tex new file mode 100644 index 0000000..68321cd --- /dev/null +++ b/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} diff --git a/examples/automatic-diff/texchanges-revised.tex b/examples/automatic-diff/texchanges-revised.tex index ef6cbcb..1868497 100644 --- a/examples/automatic-diff/texchanges-revised.tex +++ b/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} diff --git a/examples/overleaf-workflow/README.md b/examples/overleaf-workflow/README.md index ca7b475..632edc6 100644 --- a/examples/overleaf-workflow/README.md +++ b/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. diff --git a/scripts/ctan-release.sh b/scripts/ctan-release.sh index 4d92c1e..76e175e 100755 --- a/scripts/ctan-release.sh +++ b/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/"