SyncTeX (Vorwärts-/Rückwärtssuche)

SyncTeX ist die Maschine, mit der Sie in beide Richtungen zwischen einer Stelle in Ihrer .tex-Quelle und der passenden Stelle in der fertigen PDF springen können. Setzen Sie den Cursor auf einen Absatz und der Betrachter scrollt dorthin. Klicken Sie auf ein Wort im PDF und der Editor springt zu dieser Quellzeile. Wenn Sie ein langes Dokument Korrektur lesen, ist es unverzichtbar. Auf dieser Seite wird erläutert, wie SyncTeX im Allgemeinen funktioniert. Die einzelnen Editor-Schritte werden auf der eigenen Seite jedes Editors angezeigt.

Was SyncTeX ist

Da TeX das gesamte Manuskript auf einmal verarbeitet, um ein PDF zu erstellen, geht normalerweise die Verbindung zwischen einer Ausgabezeile und der Stelle in der Quelle verloren, von der sie stammt. SyncTeX (Zxqph5xz synchronisieren) ist die Technik, die diese Korrespondenz beibehält. Es wurde von Jérôme Laurens entwickelt und ist jetzt in die wichtigsten Engines eingebaut, die mit TeX Live und MiKTeX ausgeliefert werden.

Es funktioniert in zwei Richtungen. Der Übergang von der Quelle zum PDF ist eine Vorwärtssuche (auch direkte Synchronisierung genannt); Von PDF zurück zur Quelle zu gehen ist inverse Suche (oder umgekehrte/rückwärts gerichtete Suche). Beides ist eine Zusammenarbeit zwischen Ihrem Editor und Ihrem PDF-Viewer: Der Editor fragt „Zeige mir die Ausgabe für diese Zeile und Spalte“ oder „Auf welche Quellposition wird diese PDF-Koordinatenkarte abgebildet“, und der Viewer oder ein Helfer antwortet.

Vorwärts- und Rückwärtssuche

Vorwärtssuche (Quelle → PDF) beantwortet die Frage, die Sie beim Schreiben stellen: „Wo wird die Stelle, die ich bearbeite, auf der Seite landen?“ Platzieren Sie den Cursor im Editor, drücken Sie die Vorwärtssuchtaste (oder einen Menüpunkt wie „Gehe zu PDF“), und der Betrachter scrollt zur rechten Seite und markiert kurz die passende Stelle.

Inverse Suche (PDF → Quelle) ist das Gegenteil und glänzt beim Korrekturlesen. Lesen Sie PDF und entdecken Sie etwas, das behoben werden muss? Klicken Sie auf diese Stelle (normalerweise mit einer Sondertaste) und Ihr Editor erscheint im Vordergrund, wobei sich der Cursor auf der entsprechenden Zeile befindet. Der Punkt ist, dass Sie nie eine lange Quelle durchsuchen müssen, um den Ort zum Bearbeiten zu finden.

Unter der Haube übernimmt das Befehlszeilentool synctex (im Lieferumfang von SyncTeX enthalten) die Vermittlung. Die Vorwärtssuche entspricht dem Unterbefehl synctex view, die Rückwärtssuche dem Unterbefehl synctex edit; Redakteure und Betrachter rufen diese entweder auf oder implementieren das Äquivalent selbst. Normalerweise sieht man sie nie, aber die manuelle Ausführung der beiden ist eine praktische Möglichkeit, ein Problem einzugrenzen.

Die .synctex.gz-Datei und deren Aktivierung

Diese Entsprechung wird in einer .synctex.gz-Datei aufgezeichnet, die die Engine zur Kompilierungszeit schreibt. Darin befindet sich eine Karte – zlib-komprimiert – die Quelldatei, Zeile und Spalte mit einer PDF-Seite und den Koordinaten eines Rechtecks ​​(einer Box) darauf paart. Es befindet sich neben PDF, mit demselben Basisnamen und im selben Ordner (main.tex → main.synctex.gz). Weder die Vorwärts- noch die Rückwärtssuche funktioniert, bis diese Datei vorhanden ist.

Um es zu generieren, übergeben Sie beim Kompilieren -synctex=1 (LuaTeX verwendet die Langform --synctex=1). Von Hand sieht es so aus. Sie benötigen es bei jedem Build, also lassen Sie es in der Praxis einmal in Ihrem Editor oder Build-Tool festgelegt.

pdflatex -synctex=1 main.tex
xelatex  -synctex=1 main.tex
lualatex --synctex=1 main.tex

Der Wert wird als Bits gelesen. 1 gibt das komprimierte .synctex.gz; -1 liefert ein einfaches, unkomprimiertes .synctex (praktisch, wenn Sie einen Blick hineinwerfen oder debuggen möchten). Anstelle der Befehlszeile können Sie es auch von oben in der Quelle mit dem TeX-Primitiv \synctex=1 einschalten.

Build-Tools sind da nicht anders. Fügen Sie mit latexmk -synctex=1 in den Kompilierungsbefehl in Ihrem .latexmkrc ein. In Kombination mit der kontinuierlichen Vorschau (-pvc) löst jedes Speichern eine Neukompilierung und eine Aktualisierung der Vorschau aus, sodass Vorwärts- und Rückwärtssuche immer auf einem aktuellen .synctex.gz basieren.

$pdf_mode = 1;
$pdflatex = 'pdflatex -synctex=1 -interaction=nonstopmode %O %S';
# clean up the SyncTeX file too
@generated_exts = (@generated_exts, 'synctex.gz');

Motoren und die DVI-Route (pLaTeX / upLaTeX)

Die Engines, die PDF direkt ausgeben – pdfTeX, XeTeX und LuaTeX – verstehen alle -synctex und schreiben .synctex.gz selbst; Das Gleiche gilt für pdfLaTeX, XeLaTeX und LuaLaTeX. So weit, so einfach.

Die Hauptstütze für Japanisch, pLaTeX / upLaTeX, ist eine zweistufige Pipeline: Sie gibt zunächst eine DVI-Datei aus, die dvipdfmx dann in PDF umwandelt. Auch hier übergeben Sie -synctex=1 an die Engine (platex / uplatex). Die Engine schreibt zunächst .synctex.gz in DVI-Koordinaten. Die DVI-Koordinaten und die endgültigen PDF-Koordinaten unterscheiden sich jedoch durch die Offsets und die Vergrößerung dvipdfmx, so dass diese Lücke nach der Konvertierung ausgeglichen werden muss.

Der letzte Schliff ist der Unterbefehl synctex synctex update, dessen Aufgabe darin besteht, „die SyncTeX-Datei zu aktualisieren, sobald ein dvi/xdv → pdf-Filter angewendet wird“. dvipdfmx selbst hat keine -synctex-Option; Stattdessen übergeben Sie synctex update die Vergrößerung und die horizontalen/vertikalen Versätze, die für die Konvertierung verwendet wurden (-m / -x / -y, dieselben Werte, die an den Filter übergeben wurden), sodass die Koordinaten übereinstimmen. In der Praxis führt ein übergeordnetes Tool wie ptex2pdf oder latexmk diese gesamte Kette für Sie aus.

Wie jeder Editor es auslöst

SyncTeX selbst ist die gemeinsame Grundlage; Nur die Taste oder der Klick, der die Vorwärts- und Rückwärtssuche auslöst, unterscheidet sich zwischen Redakteuren und Betrachtern. Hier sind einige repräsentative Kombinationen (die vollständige Einrichtung finden Sie auf jeder Seite). Beachten Sie, dass Viewer ohne SyncTeX-Unterstützung, wie z. B. Adobe Acrobat/Reader, keine umgekehrte Suche durchführen können; Häufige Optionen, die dies tun, sind Skim (macOS), SumatraPDF (Windows) und Okular (Linux).

Ein letztes Wort zur Präzision. SyncTeX ordnet die Granularität von gesetzten „Kästchen“ zu, sodass der Sprung im normalen Textkörper genau genug ist – aber innerhalb von TikZ-Bildern, der Erweiterung komplizierter Makros oder den Innereien von Tabellen kann die Übereinstimmung auf ein nahegelegenes Kästchen gerundet werden und ein oder zwei Wörter neben Ihrem Ziel landen. Dies ist eine Einschränkung des Ansatzes und kein Fehler.

Eine Korrekturleseschleife mit SyncTeX

SyncTeX ist nicht nur eine Einstellung; Es ist eine Gewohnheit des Korrekturlesens. Klicken Sie im letzten Durchgang vor der Einreichung von PDF auf ein verdächtiges Wort im PDF, um zur Quelle zurückzukehren, bearbeiten Sie das Manuskript, speichern und erstellen Sie es neu und verwenden Sie dann die Vorwärtssuche, um zur korrigierten Stelle zurückzukehren. Wenn diese SyncTeX-Korrekturleseschleife fehlschlägt, prüfen Sie der Reihe nach: ob sich .synctex.gz neben PDF befindet, ob der Build -synctex=1 verwendet hat und ob der Viewer den Befehl ausführen kann, der den Editor aufruft.

Die .synctex.gz-Datei ist weder die Einreichung noch die Quelle der Aufzeichnung; Es handelt sich um eine regenerierbare Arbeitskarte. Ignorieren Sie es normalerweise in Git und vermuten Sie, dass es veraltet ist, wenn PDF oder der Quellpfad umbenannt wurde. Ein Ein-Wort-Offset kann eine Einschränkung der Box-Level-Zuordnung darstellen, aber ein Sprung zu einer völlig anderen Datei bedeutet normalerweise eine veraltete Ausgabe oder die falsche Masterdatei.