Collaboration, version control and tracked changes

Two co-authors who each change one sentence of the same paragraph should not have to merge their work by hand. In this lesson’s session they did have to, because the paragraph was a single line of the file; with one sentence per line, Git merged the same two edits by itself.

Below, two people write a short report together. You will lay its source out so that Git shows and merges sentences, keep the files that builds write out of the repository, give a supervisor a PDF with every change between two drafts marked, compare Typst drafts, bring a Word user’s tracked changes back into the source, and keep notes for co-authors out of the final PDF. Every session was recorded with Git 2.54, TeX Live 2026, Typst 0.15.1 and pandoc 3.12.

One sentence per line lets Git merge two people’s changes

Git compares files line by line. A diff lists the lines that changed, and a merge combines two branches’ changes as long as they touch different lines; when both change the same lines, the result is a merge conflictmerge conflict: What Git reports when two branches changed the same lines of a file, or lines next to each other: it stops and writes both versions between conflict markers for a person to resolve.. In this session two co-authors change one paragraph of three sentences: Ravi, on the branch ravi, the last sentence, and Meera, on main, the first. two_edits.sh makes both commits, and the merge is recorded three times, with the paragraph on one line, with one sentence per line, and with Ravi’s change moved to the second sentence, next to Meera’s:

# two_edits.sh FOLDER OLD1 NEW1 OLD2 NEW2
# In FOLDER, commit method.tex, then change it on two branches, as two co-authors would:
#   on the branch ravi, OLD1 becomes NEW1;
#   on main, OLD2 becomes NEW2.
# It stops on main, ready for git merge ravi, and stops at the first command that fails.
set -e
cd "$1"
git init -q -b main .
git add method.tex
git commit -q -m 'Method, first draft'
git switch -q -c ravi
python3 ../edit.py method.tex "$2" "$3"
git commit -q -am 'Mark missing readings'
git switch -q main
python3 ../edit.py method.tex "$4" "$5"
git commit -q -am 'Two weeks of data'

"""Replaces one piece of text in a file, the way a co-author changes one sentence in an editor.

    python3 edit.py FILE OLD NEW

The first OLD in FILE becomes NEW, and the file is saved. It stops with exit status 1, and changes nothing, when FILE
does not contain OLD, so a session never goes on as if an edit had been made.
"""

import sys
from pathlib import Path

path, old, new = Path(sys.argv[1]), sys.argv[2], sys.argv[3]
text = path.read_text(encoding="utf-8")
if old not in text:
    sys.exit(f"{path}: no {old!r} in the file")
path.write_text(text.replace(old, new, 1), encoding="utf-8")

from session import files, needs, run

# Two co-authors change one paragraph on two branches, and Git merges them: first with the paragraph on one line,
# then with one sentence per line, then with the two changes in neighbouring sentences.
needs("git", "python3")
files("edit.py", "merge/two_edits.sh", "merge/paragraph.tex=paragraph/method.tex",
      "merge/sentences.tex=sentences/method.tex", "merge/sentences.tex=neighbours/method.tex")
run("""
# 1. The whole paragraph on one line; Ravi changes the last sentence, Meera the first.
sh two_edits.sh paragraph 'left blank.' 'left blank and marked as missing.' 'for a week.' 'for two weeks.'
!cd paragraph && git merge ravi -m 'Merge ravi'
cat paragraph/method.tex
# 2. One sentence per line, the same two changes.
sh two_edits.sh sentences 'left blank.' 'left blank and marked as missing.' 'for a week.' 'for two weeks.'
cd sentences && git merge ravi -m 'Merge ravi'
cat sentences/method.tex
# 3. One sentence per line, but Ravi changes the second sentence, next to Meera's first.
sh two_edits.sh neighbours 'at 8 a.m.' 'at 8 a.m. and 6 p.m.' 'for a week.' 'for two weeks.'
!cd neighbours && git merge ravi -m 'Merge ravi'
cat neighbours/method.tex
""")

# 1. The whole paragraph on one line; Ravi changes the last sentence, Meera the first.
$ sh two_edits.sh paragraph 'left blank.' 'left blank and marked as missing.' 'for a week.' 'for two weeks.'
$ cd paragraph && git merge ravi -m 'Merge ravi'
Auto-merging method.tex
CONFLICT (content): Merge conflict in method.tex
Automatic merge failed; fix conflicts and then commit the result.
[exit status 1]
$ cat paragraph/method.tex
<<<<<<< HEAD
Two gauges logged the rain for two weeks. They were read at 8 a.m. every day. A reading that could not be taken was left blank.
=======
Two gauges logged the rain for a week. They were read at 8 a.m. every day. A reading that could not be taken was left blank and marked as missing.
>>>>>>> ravi
# 2. One sentence per line, the same two changes.
$ sh two_edits.sh sentences 'left blank.' 'left blank and marked as missing.' 'for a week.' 'for two weeks.'
$ cd sentences && git merge ravi -m 'Merge ravi'
Auto-merging method.tex
Merge made by the 'ort' strategy.
 method.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
$ cat sentences/method.tex
Two gauges logged the rain for two weeks.
They were read at 8 a.m. every day.
A reading that could not be taken was left blank and marked as missing.
# 3. One sentence per line, but Ravi changes the second sentence, next to Meera's first.
$ sh two_edits.sh neighbours 'at 8 a.m.' 'at 8 a.m. and 6 p.m.' 'for a week.' 'for two weeks.'
$ cd neighbours && git merge ravi -m 'Merge ravi'
Auto-merging method.tex
CONFLICT (content): Merge conflict in method.tex
Automatic merge failed; fix conflicts and then commit the result.
[exit status 1]
$ cat neighbours/method.tex
<<<<<<< HEAD
Two gauges logged the rain for two weeks.
They were read at 8 a.m. every day.
=======
Two gauges logged the rain for a week.
They were read at 8 a.m. and 6 p.m. every day.
>>>>>>> ravi
A reading that could not be taken was left blank.

With the paragraph on one line, both branches had changed line 1, so Git stopped with CONFLICT (content) and wrote the whole paragraph twice between conflict markers. With one sentence per line, the changes sat on lines 1 and 3, and Git answered Merge made by the 'ort' strategy with both sentences edited. Changes to neighbouring lines conflict too, as the third merge shows, but its markers held two sentences instead of a paragraph. Step through the merges:

The same layout makes diffs readable. This session commits two drafts of report.tex, each sentence on its own line, and asks Git what changed; then it builds the report and asks what Git sees in the folder:

\documentclass{article}
\begin{document}
\section{Method}
Two gauges logged the rain on the roofs of Block~A and Block~B for a week.
The gauges were read at 8 a.m. every day.
A reading that could not be taken was left blank.
\section{Result}
Block~A received 41.5\,mm and Block~B 38.0\,mm, a difference of 3.5\,mm.
\end{document}

\documentclass{article}
\begin{document}
\section{Method}
Two gauges logged the rain on the roofs of Block~A and Block~B for two weeks.
The gauges were read at 8 a.m. every day.
A reading that could not be taken was left blank and marked as missing.
\section{Result}
Block~A received 83.0\,mm and Block~B 76.5\,mm, a difference of 6.5\,mm.
The gauges agree to within their stated error.
\end{document}

from session import files, needs, run

# The two drafts of report.tex as two commits: what git diff shows, with and without the tex diff driver of
# .gitattributes and with --word-diff; then a build, and what git status says before and after a .gitignore.
needs("git", "pdflatex", "latexmk")
files("drafts/v1.tex=report.tex", "drafts/gitignore.txt")
run("""
git init -q -b main . && git add report.tex && git commit -q -m 'Draft 1'
""")
files("drafts/v2.tex=v2.tex")
run("""
mv v2.tex report.tex
git diff --stat
git diff -U0
echo '*.tex diff=tex' > .gitattributes
git diff -U0
git diff --word-diff -U0
git add .gitattributes report.tex && git commit -q -m 'Draft 2'
latexmk -pdf -silent report.tex > /dev/null 2>&1
git status --short
cp gitignore.txt .gitignore && rm gitignore.txt
git status --short
git check-ignore -v report.log report.pdf
""", env={"SOURCE_DATE_EPOCH": "1767225600"})

$ git init -q -b main . && git add report.tex && git commit -q -m 'Draft 1'
$ mv v2.tex report.tex
$ git diff --stat
 report.tex | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
$ git diff -U0
diff --git a/report.tex b/report.tex
index f1f6bfe..e334a5a 100644
--- a/report.tex
+++ b/report.tex
@@ -4 +4 @@
-Two gauges logged the rain on the roofs of Block~A and Block~B for a week.
+Two gauges logged the rain on the roofs of Block~A and Block~B for two weeks.
@@ -6 +6 @@ The gauges were read at 8 a.m. every day.
-A reading that could not be taken was left blank.
+A reading that could not be taken was left blank and marked as missing.
@@ -8 +8,2 @@ A reading that could not be taken was left blank.
-Block~A received 41.5\,mm and Block~B 38.0\,mm, a difference of 3.5\,mm.
+Block~A received 83.0\,mm and Block~B 76.5\,mm, a difference of 6.5\,mm.
+The gauges agree to within their stated error.
$ echo '*.tex diff=tex' > .gitattributes
$ git diff -U0
diff --git a/report.tex b/report.tex
index f1f6bfe..e334a5a 100644
--- a/report.tex
+++ b/report.tex
@@ -4 +4 @@ \section{Method}
-Two gauges logged the rain on the roofs of Block~A and Block~B for a week.
+Two gauges logged the rain on the roofs of Block~A and Block~B for two weeks.
@@ -6 +6 @@ \section{Method}
-A reading that could not be taken was left blank.
+A reading that could not be taken was left blank and marked as missing.
@@ -8 +8,2 @@ \section{Result}
-Block~A received 41.5\,mm and Block~B 38.0\,mm, a difference of 3.5\,mm.
+Block~A received 83.0\,mm and Block~B 76.5\,mm, a difference of 6.5\,mm.
+The gauges agree to within their stated error.
$ git diff --word-diff -U0
diff --git a/report.tex b/report.tex
index f1f6bfe..e334a5a 100644
--- a/report.tex
+++ b/report.tex
@@ -4 +4 @@ \section{Method}
Two gauges logged the rain on the roofs of Block~A and Block~B for [-a week-]{+two weeks+}.
@@ -6 +6 @@ \section{Method}
A reading that could not be taken was left blank {+and marked as missing+}.
@@ -8 +8,2 @@ \section{Result}
Block~A received [-41-]{+83+}.[-5-]{+0+}\,mm and Block~B [-38-]{+76+}.[-0-]{+5+}\,mm, a difference of [-3-]{+6+}.5\,mm.
{+The gauges agree to within their stated error.+}
$ git add .gitattributes report.tex && git commit -q -m 'Draft 2'
$ latexmk -pdf -silent report.tex > /dev/null 2>&1
$ git status --short
?? gitignore.txt
?? report.aux
?? report.fdb_latexmk
?? report.fls
?? report.log
?? report.pdf
$ cp gitignore.txt .gitignore && rm gitignore.txt
$ git status --short
?? .gitignore
$ git check-ignore -v report.log report.pdf
.gitignore:7:*.log	report.log
.gitignore:12:*.pdf	report.pdf

Each changed sentence showed as one changed line. The line after @@ is the header of a hunkhunk: One block of changed lines in a diff, introduced by a header line that starts with @@ and gives where the block starts in the old and in the new file.: by default Git took the nearest line that starts with a letter, a sentence that tells you nothing, but with *.tex diff=tex in .gitattributes, one of the built-in patterns the gitattributes manual lists, it named the section, \section{Method}. --word-diff showed the changed words inside each line, [-a week-]{+two weeks+}; with the tex pattern on, it split numbers at the full stop, so 41.5 became two changes.

Commit what you write, never what the build writes

After the build, git status --short listed five files that nobody wrote: report.aux, report.fdb_latexmk, report.fls, report.log and the PDF, besides the gitignore.txt the session had copied in. Committed, they would change on every build and conflict on every merge. With a .gitignore that lists them, only the .gitignore itself was left to add, and git check-ignore -v named the line that matched each file:

# Save as .gitignore: files that LaTeX, BibTeX, latexmk and the editors write, never the sources.
*.aux
*.bbl
*.blg
*.fdb_latexmk
*.fls
*.log
*.out
*.synctex.gz
*.toc
# The PDFs are built from the sources; CI keeps them as artifacts.
*.pdf

latexdiff marks every change between two drafts

A supervisor who reads PDFs does not want a diff of markup. latexdiff, whose CTAN entry calls it a Perl script for visual mark up and revision of significant differences between two LaTeX files, writes a third .tex file in which every deletion and addition is marked; pdflatex then builds it like any other file. This session takes the last commit but one from Git, compares it with the current file, builds the result and checks the PDF:

from session import files, needs, run

# Draft 1 and draft 2 of report.tex as two commits; latexdiff marks what changed between the last commit but one and
# the file as it is now, pdflatex builds the marked file, and changes.py lists the coloured text of its PDF.
# latexdiff-vc, which comes with latexdiff, does the same from the commit's name; its temporary file is named after
# the process, which the page shows as [process id].
needs("git", "pdflatex", "latexdiff", "mutool")
files("drafts/v1.tex=report.tex", "changes.py")
run("""
git init -q -b main . && git add report.tex && git commit -q -m 'Draft 1'
""")
files("drafts/v2.tex=v2.tex")
run("""
mv v2.tex report.tex && git commit -q -am 'Draft 2'
git show HEAD~1:report.tex > old.tex
latexdiff old.tex report.tex > diff.tex
sed -n '/^.begin{document}/,$p' diff.tex
pdflatex -interaction=nonstopmode -halt-on-error diff.tex > /dev/null
python3 changes.py diff.pdf
latexdiff-vc --git -r HEAD~1 report.tex
""", mask=[(r"oldtmp-\d+", "oldtmp-[process id]")], env={"SOURCE_DATE_EPOCH": "1767225600"})

$ git init -q -b main . && git add report.tex && git commit -q -m 'Draft 1'
$ mv v2.tex report.tex && git commit -q -am 'Draft 2'
$ git show HEAD~1:report.tex > old.tex
$ latexdiff old.tex report.tex > diff.tex
$ sed -n '/^.begin{document}/,$p' diff.tex
\begin{document}
\section{Method}
Two gauges logged the rain on the roofs of Block~A and Block~B for \DIFdelbegin \DIFdel{a week}\DIFdelend \DIFaddbegin \DIFadd{two weeks}\DIFaddend .
The gauges were read at 8 a.m. every day.
A reading that could not be taken was left blank \DIFaddbegin \DIFadd{and marked as missing}\DIFaddend .
\section{Result}
Block~A received \DIFdelbegin \DIFdel{41.5}\DIFdelend \DIFaddbegin \DIFadd{83.0}\DIFaddend \,mm and Block~B \DIFdelbegin \DIFdel{38.0}\DIFdelend \DIFaddbegin \DIFadd{76.5}\DIFaddend \,mm, a difference of \DIFdelbegin \DIFdel{3.5}\DIFdelend \DIFaddbegin \DIFadd{6.5}\DIFaddend \,mm\DIFaddbegin \DIFadd{.
The gauges agree to within their stated error}\DIFaddend .
\end{document}
$ pdflatex -interaction=nonstopmode -halt-on-error diff.tex > /dev/null
$ python3 changes.py diff.pdf
deleted  a week
added    two weeks
added    and marked as missing
deleted  41.5
added    83.0
deleted  38.0
added    76.5
deleted  3.5
added    6.5
added    . The gauges agree to within their stated error
$ latexdiff-vc --git -r HEAD~1 report.tex
Working on  report.tex 
patching file report.tex
Running: latexdiff   "report-oldtmp-[process id].tex" "report.tex" > "report-diffHEAD~1.tex"
Generated difference file report-diffHEAD~1.tex

In diff.tex, a week became \DIFdelbegin \DIFdel{a week}\DIFdelend and two weeks the matching \DIFadd. latexdiff compares words, not lines, so each changed number was marked alone, and the full stop of the old last sentence moved into the added text. Follow the session’s steps:

A PDF with marks should be checked like any other output. changes.py reads every character’s colour with MuPDF, and listed four deleted runs and six added ones, a week deleted and two weeks added first. latexdiff-vc, installed with latexdiff, does the Git step itself: latexdiff-vc --git -r HEAD~1 report.tex wrote report-diffHEAD~1.tex. For a project of several files, --flatten reads \input and \include files into the comparison.

"""Lists the marked text of a latexdiff PDF: blue text is what was added, red text what was deleted.

    python3 changes.py diff.pdf

MuPDF's structured text (mutool draw -F stext) gives every character of the PDF with its colour. Neighbouring
characters of the same colour become one run, and a black character ends a run. latexdiff's default style draws the
wavy line under an addition with characters too (each one a ":" in blue), so those are skipped.
"""

import subprocess
import sys
import xml.etree.ElementTree as ET

KINDS = {"#0000ff": "added", "#ff0000": "deleted"}

stext = subprocess.run(["mutool", "draw", "-q", "-F", "stext", "-o", "-", sys.argv[1]], capture_output=True,
                       check=True).stdout
runs = []
for line in ET.fromstring(stext).iter("line"):
    for char in line.iter("char"):
        kind, text = KINDS.get(char.get("color")), char.get("c")
        if kind == "added" and text == ":":
            continue
        if kind is None:
            if runs and runs[-1][0] is not None:
                runs.append((None, ""))
        elif runs and runs[-1][0] == kind:
            runs[-1] = (kind, runs[-1][1] + text)
        else:
            runs.append((kind, text))
    if runs and runs[-1][0] is not None:
        runs[-1] = (runs[-1][0], runs[-1][1] + " ")
for kind, text in runs:
    if kind and text.strip():
        print(f"{kind:8} {' '.join(text.split())}")

A Typst draft is compared through the text a reader sees

Typst has no latexdiff. Its source is plain text, so the Git diffs above work the same way, but a co-author who reads PDFs needs the change in the words of the page. This session builds the two drafts of the report in Typst, extracts their text with pdftotext and compares the two texts word by word with git diff --no-index, which compares two files outside any repository:

#set heading(numbering: "1")
= Method
Two gauges logged the rain on the roofs of Block A and Block B for a week.
The gauges were read at 8 a.m. every day.
A reading that could not be taken was left blank.

= Result
Block A received 41.5 mm and Block B 38.0 mm, a difference of 3.5 mm.

#set heading(numbering: "1")
= Method
Two gauges logged the rain on the roofs of Block A and Block B for two weeks.
The gauges were read at 8 a.m. every day.
A reading that could not be taken was left blank and marked as missing.

= Result
Block A received 83.0 mm and Block B 76.5 mm, a difference of 6.5 mm.
The gauges agree to within their stated error.

from session import files, needs, run

# Typst has no latexdiff. The two drafts are compiled, pdftotext extracts what a reader sees, and git diff compares
# the two texts word by word (--no-index: two files, no repository).
needs("typst", "pdftotext", "git")
files("drafts/v1.typ", "drafts/v2.typ")
run("""
typst compile v1.typ && typst compile v2.typ
pdftotext v1.pdf v1.txt && pdftotext v2.pdf v2.txt
!git diff --no-index --word-diff -U0 v1.txt v2.txt
""", env={"SOURCE_DATE_EPOCH": "1767225600"})

$ typst compile v1.typ && typst compile v2.typ
$ pdftotext v1.pdf v1.txt && pdftotext v2.pdf v2.txt
$ git diff --no-index --word-diff -U0 v1.txt v2.txt
diff --git a/v1.txt b/v2.txt
index aab0e2e..9a22d1b 100644
--- a/v1.txt
+++ b/v2.txt
@@ -2,2 +2,2 @@
Two gauges logged the rain on the roofs of Block A and Block B for [-a week.-]{+two weeks.+} The gauges were
read at 8 a.m. every day. A reading that could not be taken was left [-blank.-]{+blank and marked as missing.+}
@@ -6 +6,2 @@ Two gauges logged the rain on the roofs of Block A and Block B for a week. The g
Block A received [-41.5-]{+83.0+} mm and Block B [-38.0-]{+76.5+} mm, a difference of [-3.5-]{+6.5+} mm. {+The gauges agree to within+}
{+their stated error.+}
[exit status 1]

The comparison found the same six changes as latexdiff, [-a week.-]{+two weeks.+} first, and ended with exit status 1, which git diff --no-index uses when the files differ. The extracted text follows the PDF’s line breaks, not the source’s, so one changed sentence can show as two lines, as the last addition did. MySmartCoPilot’s Text Diff shows the same comparison side by side, and its PDF Compare tool also marks the areas of each page that look different:

A co-author’s tracked changes come back through pandoc

Some co-authors work only in a word processor, with tracked changestracked change: An insertion or a deletion that a word processor records with its author instead of making it silently, so that others can see it and accept or reject it.. A .docx file is a ZIP package of XML parts, so Git can store it but not show what changed. ECMA-376, the Office Open XML standard, stores each tracked change in the document’s XML: inserted text in a w:ins element, deleted text in a w:del element, each with its author. This session writes the report as a Word file, lets coauthor_edits.py make three tracked changes as an invented co-author would, and reads the file back with pandoc:

from session import files, needs, run

# report.tex goes to a co-author as a Word file. coauthor_edits.py plays the co-author, who makes three tracked
# changes; pandoc then reads them back, first with every change shown, then with the changes accepted (its default).
needs("pandoc", "python3")
files("drafts/v2.tex=report.tex", "coauthor_edits.py")
run("""
pandoc report.tex -o report.docx
python3 coauthor_edits.py report.docx report-ravi.docx
pandoc report-ravi.docx --track-changes=all -t markdown --wrap=none
pandoc report-ravi.docx -t markdown --wrap=none
""", env={"SOURCE_DATE_EPOCH": "1767225600"})

$ pandoc report.tex -o report.docx
$ python3 coauthor_edits.py report.docx report-ravi.docx
report-ravi.docx: 3 tracked changes by Ravi Kumar
$ pandoc report-ravi.docx --track-changes=all -t markdown --wrap=none
# Method

Two gauges logged the rain on the roofs of Block A and Block B for [two weeks]{.deletion author="Ravi Kumar"}[14 days]{.insertion author="Ravi Kumar"}. The gauges were read at 8 a.m. every day. A reading that could not be taken was left blank and marked as missing. [Missing readings were not estimated.]{.insertion author="Ravi Kumar"}

# Result

Block A received 83.0 mm and Block B 76.5 mm, a difference of 6.5 mm. [The gauges agree to within their stated error.]{.deletion author="Ravi Kumar"}
$ pandoc report-ravi.docx -t markdown --wrap=none
# Method

Two gauges logged the rain on the roofs of Block A and Block B for 14 days. The gauges were read at 8 a.m. every day. A reading that could not be taken was left blank and marked as missing. Missing readings were not estimated.

# Result

Block A received 83.0 mm and Block B 76.5 mm, a difference of 6.5 mm.

Pandoc’s manual describes --track-changes with three values. all kept every change as a span with its kind and author, [two weeks]{.deletion author="Ravi Kumar"}[14 days]{.insertion author="Ravi Kumar"}, a list to work through; the default, accept, printed the text with the three changes made; reject gives the text without them. Step through the round trip:

The .tex file stays the primary copyprimary copy: The one set of source files that every other format of a document is made from and that every edit goes into. Copies in other formats are outputs: they are rebuilt from it and never edited by hand.: you make the changes you agree with in report.tex and commit them, so the LaTeX markup that never went through Word, such as \,mm and the labels, is never lost.

Notes for co-authors stay in the source, out of the final PDF

A question for a co-author is easiest to answer where it belongs, in the text. todonotes, which its CTAN entry says lets you mark things to do later, draws a note in the margin or, with inline, in the text. In Typst a short function does the same, and sys.inputs, which reads values given with --input on the command line, turns the notes off for the final build:

% notes.tex: notes for co-authors with todonotes. A build that passes the option disable to todonotes leaves them out.
\documentclass{article}
\usepackage{todonotes}
\begin{document}
\section{Method}
Two gauges logged the rain for two weeks.\todo{Ravi: add the gauge model.}
They were read at 8 a.m. every day.
\todo[inline]{Meera: say who read them on Sundays.}
\end{document}

// notes.typ: notes for co-authors. typst compile notes.typ shows them;
// typst compile --input final=yes notes.typ leaves them out.
#let final = sys.inputs.at("final", default: "no") == "yes"
#let note(who, body) = if not final {
  box(fill: yellow.lighten(60%), inset: 2pt)[*#who:* #body]
}

#set heading(numbering: "1")
= Method
Two gauges logged the rain for two weeks. #note("Ravi")[Add the gauge model.]
They were read at 8 a.m. every day.
#note("Meera")[Say who read them on Sundays.]

from session import files, needs, run

# The same notes in both systems: a working build that shows them, and a final build that leaves them out, checked
# by counting the co-authors' names in the text pdftotext extracts.
needs("pdflatex", "typst", "pdftotext")
files("notes/notes.tex", "notes/notes.typ")
run(r"""
pdflatex -interaction=nonstopmode -halt-on-error notes.tex > /dev/null
pdftotext notes.pdf - | grep -c -E 'Ravi|Meera'
pdflatex -interaction=nonstopmode -halt-on-error -jobname=notes-final '\PassOptionsToPackage{disable}{todonotes}\input{notes}' > /dev/null
!pdftotext notes-final.pdf - | grep -c -E 'Ravi|Meera'
typst compile notes.typ
pdftotext notes.pdf - | grep -c -E 'Ravi|Meera'
typst compile --input final=yes notes.typ notes-final.pdf
!pdftotext notes-final.pdf - | grep -c -E 'Ravi|Meera'
""", env={"SOURCE_DATE_EPOCH": "1767225600"})

$ pdflatex -interaction=nonstopmode -halt-on-error notes.tex > /dev/null
$ pdftotext notes.pdf - | grep -c -E 'Ravi|Meera'
2
$ pdflatex -interaction=nonstopmode -halt-on-error -jobname=notes-final '\PassOptionsToPackage{disable}{todonotes}\input{notes}' > /dev/null
$ pdftotext notes-final.pdf - | grep -c -E 'Ravi|Meera'
0
[exit status 1]
$ typst compile notes.typ
$ pdftotext notes.pdf - | grep -c -E 'Ravi|Meera'
2
$ typst compile --input final=yes notes.typ notes-final.pdf
$ pdftotext notes-final.pdf - | grep -c -E 'Ravi|Meera'
0
[exit status 1]

grep -c counted the co-authors’ names in the extracted text. The working builds held 2; the final builds, pdflatex with \PassOptionsToPackage{disable}{todonotes} given before the file and Typst with --input final=yes, held 0, and grep ended with exit status 1 because it found nothing. Neither final build needed a change to the source, so a note that nobody remembered to delete still stays out of the final PDF, and the same grep can fail a CI job when it finds one.

The online editor’s plan decides history, tracked changes and Git

Some groups write in the browser. Overleaf edits LaTeX and the Typst web app edits Typst, and what each offers depends on the plan. Overleaf’s plans page lists these differences:

The Typst web app’s plans page lists these:

So without a subscription, an Overleaf project has one collaborator and a day of history, and no tracked changes; the Typst app lets a group edit together but lists comments and Git sync only with its subscription.

A Git repository with the latexdiff and pdftotext comparisons of this lesson keeps full history and gives marked PDFs whatever editor each co-author uses, so the plans decide only what the browser itself can do.

Practise: one sentence per line

Breaking a paragraph into sentences is the one step of this lesson that you would otherwise do by hand. Write it once, against sample tests made from this lesson’s report; the first hint is open:

def one_per_line(paragraph):
    """Return the paragraph with each sentence on a line of its own."""
    # Replace this line: find each sentence end and put a line break in place of the space after it.
    return paragraph.strip()

from sentences import one_per_line


def test_three_sentences():
    """breaks a paragraph of three sentences into three lines"""
    text = "Two gauges logged the rain for a week. They were read at 8 a.m. every day. A reading that could not be taken was left blank."
    assert one_per_line(text) == (
        "Two gauges logged the rain for a week.\n"
        "They were read at 8 a.m. every day.\n"
        "A reading that could not be taken was left blank."
    )


def test_abbreviations():
    """keeps e.g. and Fig. inside their sentences"""
    text = "Two gauges, e.g. the ones on Block A, logged the rain. Fig. 2 shows them."
    assert one_per_line(text) == "Two gauges, e.g. the ones on Block A, logged the rain.\nFig. 2 shows them."


def test_initials_and_et_al():
    """keeps initials and et al. inside their sentences"""
    text = "The method of A. Rao and D. Kulkarni was used. Rao et al. tested it on 12 roofs. It worked."
    assert one_per_line(text) == (
        "The method of A. Rao and D. Kulkarni was used.\n"
        "Rao et al. tested it on 12 roofs.\n"
        "It worked."
    )


def test_questions_numbers_and_commands():
    """ends sentences at ? and !, before a digit or a command, and never inside a number"""
    text = "Block A received 41.5 mm. Why less in Block B? 38.0 mm is low! \\textbf{Block B} was shaded."
    assert one_per_line(text) == (
        "Block A received 41.5 mm.\n"
        "Why less in Block B?\n"
        "38.0 mm is low!\n"
        "\\textbf{Block B} was shaded."
    )


def test_lower_case_after_full_stop():
    """does not break before a word in lower case"""
    assert one_per_line("They were read at 8 a.m. every day.") == "They were read at 8 a.m. every day."


def test_one_sentence_and_spaces():
    """returns a single sentence unchanged, without its outer spaces"""
    assert one_per_line("  The totals are in Table~\\ref{tab:totals}.  ") == "The totals are in Table~\\ref{tab:totals}."

Last, a short self-check on the six ideas of the lesson. Questions on what you know least come first, and every choice you pick is explained on the spot:

Interview questions

Warm-up (fresher to 2–5 years): Why keep one sentence per line in a LaTeX or Typst file that lives in Git?

Because Git diffs and merges by lines. With one sentence per line, a diff shows which sentences changed, and two co-authors who change different sentences of a paragraph get a clean merge. With a whole paragraph on one line, any change marks the paragraph as changed, and two changes anywhere in it conflict. In this lesson’s session, the same two edits to the first and last sentence of a paragraph conflicted when the paragraph was one line and merged by themselves with one sentence per line; edits to neighbouring sentences still conflicted, but only over those two lines. Neither LaTeX nor Typst cares where a line ends inside a paragraph, so the PDF stays the same, and the editor can still wrap long lines on screen.

Two harder questions come from this lesson: a thesis committee that wants the changes between two versions, and a group whose members write in three different tools. Plan your opening move for each before you read its first step:

Key takeaways

• Git diffs and merges by lines, so one sentence per line turned a paragraph-wide conflict into a clean merge, and *.tex diff=tex made each hunk name its section.
• Commit the sources and a .gitignore, never the .aux, .log, .bbl or PDF files that every build writes again.
• latexdiff writes a .tex file with every change marked, which pdflatex builds into a PDF a co-author can read; check the PDF’s marks, as changes.py did by colour.
• Typst drafts are compared through their extracted text, word by word, with git diff --no-index --word-diff.
• pandoc’s --track-changes=all lists a Word co-author’s changes with their authors, and the .tex file stays the primary copy in which you apply them.
• Notes for co-authors stay out of the final PDF when the final build turns them off, todonotes with disable and Typst through sys.inputs, and the plans pages say which online editor gives history, tracked changes and Git.