Korrekturlesen (proofread)

Wer je eine Rückmeldung mit dem Verweis „Seite 12, dritter Absatz, vierte Zeile“ erhalten hat, weiß bereits, was das Korrekturlesen in LaTeX zuerst braucht: Zeilennummern aus dem Paket lineno. Viele Zeitschriften verlangen ein zeilennummeriertes Manuskript schon bei der Einreichung, und mit Nummern am Rand kostet ein Hinweis genau ein Wort – „L412“. Diese Seite geht einen vollständigen Korrekturdurchlauf durch: Zeilen nummerieren, Aufgaben an den Rand heften, die Eingriffe jedes Mitautors farblich zuordnen, mit latexdiff zeigen, was sich seit dem letzten Entwurf geändert hat, und drei Prüfprogramme – chktex, lacheck und nag – auf die Quelle loslassen. Jeder Schritt wird mit der Ausgabe eines echten Laufs belegt.

Zeilennummern für die Begutachtungsfassung: das Paket lineno

\usepackage{lineno} laden, \linenumbers schreiben – und ab dieser Stelle erhält jede Zeile Fließtext eine Nummer im linken Rand. Optionen ändern die Darstellung: modulo nummeriert nur jede fünfte Zeile und hält den Rand ruhig, pagewise beginnt die Zählung auf jeder Seite neu bei 1, switch setzt die Nummern im doppelseitigen Satz in den Außenrand. \nolinenumbers schaltet sie wieder ab, die Umgebung linenumbers nummeriert einen Bereich. Nur einen Teil eines Dokuments zu nummerieren – etwa den Haupttext, nicht aber den Anhang – ist eine alltägliche Anforderung.

\usepackage[modulo]{lineno}   % number every 5th line only
% \usepackage[pagewise]{lineno} % restart the count on each page
% \usepackage[switch]{lineno}   % outer margin, for twoside
\linenumbers
...
\nolinenumbers                % stop numbering (e.g. before the appendix)

Hier lauert die Falle, an der ein Begutachtungsgespräch scheitert. Standardmäßig werden abgesetzte Formeln nicht nummeriert. Gemessen an einem Dokument mit einer equation und einem align aus amsmath lief der Fließtext 1, 2, 3 – die Mathematik wurde schlicht übersprungen. Ergänzt man im selben Dokument \usepackage[mathlines]{lineno}, läuft die Zählung von 1 bis 6, und jede Zeile jeder abgesetzten Formel bekommt ebenfalls eine Nummer. Mit anderen Worten: Ob mathlines gesetzt ist, entscheidet darüber, worauf „L4“ zeigt. Sehen Gutachter und Autorin PDFs mit unterschiedlichen Einstellungen, reden sie aneinander vorbei. Bei formellastigen Manuskripten ist mathlines die sicherere Wahl.

lineno ist ein altes Werkzeug, es reicht bis 1995 zurück; in TeX Live 2024 steckt die v5.3 vom 20. Mai 2023. Im Copyright-Vermerk am Kopf des Pakets stehen drei Generationen von Betreuern: Stephan I. Böttcher für 1995–2003, Uwe Lück für die Reihe 4.x und Karl Wette, der die Reihe 5.x 2021 übernahm. Dreißig Jahre Kompatibilitätsarbeit hinterlassen Spuren, und das Paket verträgt sich nicht mit allem reibungslos. Die Ladereihenfolge kann eine Rolle spielen: Erscheinen die Nummern partout nicht, sollte man lineno zuletzt laden.

latexdiff benutzen: einem Mitautor zeigen, was sich geändert hat

latexdiff old.tex new.tex > diff.tex ausführen und die entstandene diff.tex wie gewohnt mit pdflatex übersetzen. Das ist das ganze Verfahren, und es liefert ein PDF, in dem ergänzter und gestrichener Wortlaut optisch unterscheidbar sind. In einem tatsächlichen Lauf fädelt latexdiff Marken – \DIFaddbegin, \DIFadd{...}, \DIFdelbegin, \DIFdel{...} – durch den Text und ergänzt die Präambel um \RequirePackage[normalem]{ulem} sowie Farbdefinitionen. Zum wertvollsten Werkzeug des ganzen Korrektursatzes wird es dadurch, dass es dem Gegenüber das Lesen von LaTeX erspart: Der Unterschied erscheint auf der gesetzten Seite, nicht in einem Git-Diff.

# the whole workflow
latexdiff old.tex new.tex > diff.tex
pdflatex diff.tex

# one file made of many \input files: flatten first
latexdiff --flatten old/main.tex new/main.tex > diff.tex

# diff straight against a git revision (produces main-diffHEAD~1.tex)
latexdiff-vc --git --flatten -r HEAD~1 main.tex

# a different visual style, e.g. bold instead of underline
latexdiff --type=CFONT old.tex new.tex > diff.tex

Das voreingestellte Aussehen ist etwas genauer, als die übliche Beschreibung „Ergänzungen unterstrichen, Streichungen durchgestrichen“ vermuten lässt. In TeX Live 2024 steckt v1.3.3 – latexdiff --version meldet sich mit „(c) 2004-2022 F J Tilmann“ –, und die eingefügte Präambel definiert \DIFadd als {\protect\color{blue}\uwave{#1}} und \DIFdel als {\protect\color{red}\sout{#1}}. Also: Ergänzungen sind eine blaue Wellenlinie, Streichungen ein roter Durchstrich. Diese Vorgabe heißt --type=UNDERLINE; als Alternativen stehen CTRADITIONAL, TRADITIONAL, CFONT, FONTSTRIKE, INVISIBLE, CHANGEBAR, CCHANGEBAR, CULINECHBAR, CFONTCHBAR, BOLD und PDFCOMMENT bereit. Wer an Gutachter schickt, die schwarzweiß ausdrucken, fährt mit FONTSTRIKE oder BOLD deutlich besser.

% What latexdiff actually writes into diff.tex (excerpt of a real run):
\RequirePackage[normalem]{ulem}
\providecommand{\DIFadd}[1]{{\protect\color{blue}\uwave{#1}}}
\providecommand{\DIFdel}[1]{{\protect\color{red}\sout{#1}}}
...
The measured value was \DIFdelbegin \DIFdel{3.2}\DIFdelend
  \DIFaddbegin \DIFadd{3.4}\DIFaddend \,mm.

Zwei Gelegenheiten machen den Aufwand bezahlt. Die eine ist die überarbeitete Einreichung: Viele Zeitschriften verlangen neben der sauberen Fassung eine markierte, und die Ausgabe von latexdiff ist genau dieses Dokument. Die andere ist der Versand an Mitautoren. Bei einem auf mehrere Dateien verteilten Text expandiert --flatten die \inputs vor dem Vergleich, und latexdiff-vc --git --flatten -r HEAD~1 main.tex vergleicht den Arbeitsbaum direkt mit einem früheren Commit und schreibt main-diffHEAD~1.tex. Ein Vorbehalt: latexdiff behandelt LaTeX als Text, nicht als Syntax, weshalb Änderungen innerhalb von Tabellen und Abbildungen die Auszeichnung zerreißen können. Dann hilft es, den betreffenden Befehl mit --append-safecmd auf die sichere Liste zu setzen oder die Umgebung mit --exclude-textcmd auszunehmen.

Jedem Mitautor eine Farbe: das Paket changes

Während latexdiff zwei Fassungen von außen vergleicht, hält changes die Eingriffe in der Quelle selbst fest. Man meldet die Autoren an – \definechangesauthor[name={Ada Lovelace}, color=blue]{AL} – und zeichnet dann mit \added[id=AL]{...}, \deleted[id=AL]{...}, \replaced[id=AT]{neu}{alt} und \comment[id=AT]{...} aus. Mit \listofchanges entsteht eine „List of changes“; im tatsächlichen Lauf standen dort Added (AL): ..., Replaced (AT): ..., Deleted (AL): ... und Commented (AT): ..., jeweils mit Urheber. In TeX Live 2024 steckt v4.2.1 (2021/07/15).

\usepackage[markup=underlined]{changes}   % draft look; the default
\definechangesauthor[name={Ada Lovelace}, color=blue]{AL}
\definechangesauthor[name={Alan Turing},  color=orange]{AT}
\begin{document}
\listofchanges
The engine \added[id=AL]{weaves algebraical patterns} and
\replaced[id=AT]{computes}{calculates} the numbers.
\deleted[id=AL]{This sentence is redundant.}
\comment[id=AT]{Check the citation here.}

Der letzte Handgriff ist entscheidend. Nach dem Wechsel zu \usepackage[final]{changes} versteckt das Paket die Auszeichnung nicht bloß – es wendet die Änderungen an. Im tatsächlichen Lauf blieb der Wortlaut von \added stehen, \replaced behielt nur den neuen Text, und sowohl der \deleted-Satz als auch der \comment verschwanden; übrig blieb der saubere Satz „The engine weaves algebraical patterns and computes the numbers. Ordinary text.“ Man muss die Befehle also nie von Hand entfernen, um eine Endfassung zu erzeugen. Umgekehrt heißt das: Das PDF vor und nach dem Umschalten sagt Verschiedenes. Vor der Einreichung also immer im final-Modus neu übersetzen und nochmals lesen.

Aufgaben an den Rand heften: todonotes und \todo

Ein mit % geschriebener Kommentar verschwindet beim Übersetzen – die Mitautorin bekommt ihn also nie zu Gesicht. todonotes sorgt dafür, dass Aufgaben in der Ausgabe bleiben. \todo{check this number} zeichnet einen Klebezettel an den Rand, \todo[inline]{...} setzt ein Band mitten in den Textfluss, und \missingfigure{plot of the residuals} zeichnet einen Platzhalterkasten für eine noch fehlende Abbildung. \listoftodos erzeugt vorn eine „Todo list“; im tatsächlichen Lauf stand dort jeder Punkt mit Seitenzahl – auf einen Blick sieht man, was noch offen ist.

\usepackage[textwidth=3cm]{todonotes}
% \usepackage[disable]{todonotes}   % final version: hides notes AND the list
\begin{document}
\listoftodos
Some text.\todo{check this number}
More text.\todo[inline,color=green!30]{rewrite this paragraph}
\missingfigure{plot of the residuals}

Für die Endfassung tauscht man auf \usepackage[disable]{todonotes} um. Gemessen verschwinden damit die Randzettel, die \missingfigure-Kästen und auch die „Todo list“ am Anfang – während die Befehle in der Quelle bleiben, sodass ein entferntes disable bei der nächsten Überarbeitung sämtliche Aufgaben zurückholt. Das ist der entscheidende Unterschied zum %-Kommentar: Die Notiz wird versteckt, nicht vernichtet. Die Gefahr besteht darin, mit gesetztem disable einzureichen und niemand bemerkt die offenen Punkte. Machen Sie „disable einmal abschalten und \listoftodos lesen“ zum festen Schritt unmittelbar vor der Abgabe.

chktex und lacheck: aufspüren, was pdflatex nie erwähnt

Diese beiden fangen Fehler ab, die typografisch falsch, aber makellos kompilierbar sind – denn pdflatex interessiert nur, ob der Lauf gelingt. Ein konkreter Fall: Schickt man die Zeile As shown in Fig. 1 and in Table \ref{tab:one}, see also \cite{knuth1984}. durch pdflatex, kommt allein LaTeX Warning: Reference 'tab:one' on page 1 undefined zurück, eine Bemerkung zu Querverweisen. Dieselbe Zeile durch chktex geschickt, löst diese Warnung zweimal aus:

$ chktex -q ref.tex
Warning 2 in ref.tex line 3: Non-breaking space (`~') should have been used.
As shown in Fig. 1 and in Table \ref{tab:one}, see also \cite{knuth1984}.
                               ^
Warning 2 in ref.tex line 3: Non-breaking space (`~') should have been used.
As shown in Fig. 1 and in Table \ref{tab:one}, see also \cite{knuth1984}.
                                                       ^

Hier ist eine Richtigstellung fällig. Oft heißt es, chktex rüge das fehlende ~ in Fig. 1. Mit der Standardkonfiguration tut es das nicht. Die ~-Prüfung – Warnung 2 – überwacht allein das, was in chktexrc unter Linker steht: \ref, \vref, \pageref, \eqref und \cite. Eine nackte Zeichenkette wie Fig. 1 fällt nicht darunter. Damit Fig. erfasst wird, muss man es selbst in die Abbrev-Liste eintragen. Tut man das und prüft dieselbe Datei erneut, zeigt nun Warning 12 in ref.tex line 3: Interword spacing should perhaps be used. auf Fig. – gemeint ist, dass der Punkt sonst den breiteren Satzende-Abstand bekommt.

# The messages exactly as chktex prints them (one run, one bad file):
Warning 18 in bad.tex line 4: Use either `` or '' as an alternative to `"'.
Warning 11 in bad.tex line 4: You should use \ldots to achieve an ellipsis.
Warning 26 in bad.tex line 4: You ought to remove spaces in front of punctuation.
Warning 29 in bad.tex line 5: $\times$ may look prettier here.
Warning  8 in bad.tex line 7: Wrong length of dash may have been used.
Warning  9 in mm.tex  line 5: `itemize' expected, found `enumerate'.

lacheck ist weit wortkarger, und seine Rolle ist entsprechend klar. Wo chktex mit regulären Ausdrücken Schreibgewohnheiten überwacht, prüft lacheck die strukturelle Stimmigkeit des Dokuments. Übergibt man ihm eine Datei, die \begin{itemize} mit \end{enumerate} schließt, meldet es beide Enden als Paar: "mm.tex", line 5: <- unmatched "\end{enumerate}" und "mm.tex", line 3: -> unmatched "\begin{itemize}". chktex erfasst denselben Fehler als Warning 9, zeigt aber nur auf das schließende Ende. In einem langen Dokument, wenn die Frage lautet, wo die Verschachtelung zuerst kippte, führt lacheck schneller ans Ziel. Richtig ist, beide laufen zu lassen.

$ lacheck mm.tex
"mm.tex", line 5: <- unmatched "\end{enumerate}"
"mm.tex", line 3: -> unmatched "\begin{itemize}"

# chktex exits with the number of warnings, so CI can gate on it
$ chktex -q ref.tex >/dev/null; echo $?
2
# mute one check by number and it passes
$ chktex -q -n2 ref.tex >/dev/null; echo $?
0
# teach it your abbreviations via a local rc file
$ printf 'Abbrev { Fig. Eq. Sec. }\n' > my.chktexrc
$ chktex -q -l my.chktexrc ref.tex

Dass chktex mit der Zahl der Warnungen selbst endet, macht es für CI brauchbar. Im obigen Lauf beendete sich chktex -q ref.tex mit 2 – zwei Warnungen –, und das Stummschalten von Prüfung 2 mit -n2 brachte den Wert auf 0. Eine Linie wie „genau diese Prüfung dulden wir“ lässt sich damit als Repository-Konfiguration festschreiben. Projektbezogene Einstellungen kommen in eine Datei, die mit -l my.chktexrc geladen wird; lokal unterdrücken lässt sich mit Anweisungen im Quelltext wie % chktex-file 26.

Veraltete Befehle und ungenutzte Marken rügen: nag und refcheck

nag weist auf Konstruktionen hin, die noch funktionieren, aber längst überholt sind – und zwar zur Übersetzungszeit. Setzt man \RequirePackage[l2tabu,orthodox]{nag} vor \documentclass und übersetzt, füllt sich das Protokoll mit Beschwerden: Package nag Warning: Command \bf is an old LaTeX 2.09 command. gefolgt von Use \bfseries or \textbf instead on input line 5., dann $$...$$ is obsolete. Use \[...\] et al. instead, Command \centerline is TeX. Use \centering or center environment instead, Package epsf is obsolete. Use the graphicx package instead. und zum Schluss Package nag Warning: 5 complaints in total. Spätestens beim ersten geerbten Manuskript auf jahrzehntealter Vorlage zahlt sich das aus.

Ebenfalls einen Lauf vor der Einreichung wert ist refcheck (in TeX Live 2024 die v1.9.1). \usepackage{refcheck} ergänzen, zweimal übersetzen – und es listet die Marken auf, auf die niemand verweist: Im tatsächlichen Lauf erschienen Package refcheck Warning: Unused label 'sec:unused' on input line 5. und Package refcheck Warning: Unused label 'eq:never' on input line 7. Eine Formel, die eine Nummer trägt, aber nie zitiert wird, ist meist eine Formel, die keine Nummer haben sollte – und das Erste, was sich streichen lässt, wenn eine Kürzung verlangt wird.

\RequirePackage[l2tabu,orthodox]{nag}   % MUST come before \documentclass
\documentclass{article}
\usepackage{refcheck}                   % lists labels nobody refers to
% Then: pdflatex paper.tex && grep -E "nag Warning|refcheck Warning" paper.log

Den Korrekturzyklus vollständig durchlaufen

Welches Werkzeug zu wählen ist, entscheidet sich daran, wer was zu sehen bekommt. Aufgaben, die nur Sie und die Mitautoren angehen: todonotes. Eingriffe, die einen Namen tragen müssen: changes. Einem Gutachter zeigen, was sich seit der Vorfassung bewegt hat: latexdiff. Und die Fehlersuche, die eine Maschine erledigen kann: chktex, lacheck und nag. Die vier stehen einander nicht im Weg. In dieser Reihenfolge durchlaufen, muss dasselbe Manuskript nicht zweimal angefasst werden.

• Beim Schreiben Aufgaben mit todonotes hinterlassen – \todo{...}, \missingfigure{...} – und mit \listoftodos zählen, was offen ist.
• Vor dem Weitergeben chktex, lacheck und nag laufen lassen, damit maschinell auffindbare Mängel weg sind. Dafür keine menschliche Aufmerksamkeit verbrauchen.
• Für den Versand eine Fassung mit lineno und aktivem \linenumbers bauen. Bei formellastigen Arbeiten zusätzlich mathlines.
• Die Rückmeldungen über changes einarbeiten – \added, \replaced, \deleted – und mit \listofchanges sicherstellen, dass nichts liegen bleibt.
• Zu jeder übergebenen Fassung eine mit latexdiff --flatten old.tex new.tex > diff.tex erzeugte Datei mitliefern. Der Gegenüber muss nur das Diff öffnen.
• Kurz vor der Abgabe ungenutzte Marken mit refcheck beseitigen und dann mit todonotes auf disable und changes auf final neu übersetzen.