SyncTeX (recherche directe/inverse)

SyncTeX est la machine qui vous permet de sauter dans les deux sens entre un point de votre source .tex et le point correspondant dans le PDF fini. Placez votre curseur sur un paragraphe et le spectateur y fait défiler ; cliquez sur un mot dans le PDF et l'éditeur passe à cette ligne source. Lorsque vous relisez un long document, cela est indispensable. Cette page explique comment fonctionne SyncTeX en général ; les étapes par éditeur sont en direct sur la propre page de chaque éditeur.

Qu'est-ce que SyncTeX

Étant donné que TeX traite l'intégralité du manuscrit en une seule fois pour créer un PDF, le lien entre une ligne de sortie et l'endroit dans la source d'où elle provient est normalement perdu. SyncTeX (Synchronize TeXnology) est la technique qui préserve cette correspondance. Il a été créé par Jérôme Laurens et est désormais intégré aux principaux moteurs livrés avec TeX Live et MiKTeX.

Cela fonctionne dans deux directions. Passer de la source au PDF est une recherche avant (également appelée synchronisation directe) ; aller du PDF à la source est une recherche inverse (ou recherche inversée/vers l'arrière). Les deux sont une coopération entre votre éditeur et votre visualiseur PDF : l'éditeur demande « montre-moi la sortie de cette ligne et de cette colonne » ou « à quelle position source cette coordonnée PDF est-elle mappée » et le visualiseur ou un assistant répond.

Recherche avant et arrière

La recherche avant (source → PDF) répond à la question que vous posez en écrivant : "où finira l'endroit que je modifie sur la page ?" Placez le curseur dans l'éditeur, appuyez sur la touche de recherche avant (ou sur un élément de menu tel que « Aller à PDF »), et le spectateur fait défiler vers la page de droite et met brièvement en évidence l'endroit correspondant.

La recherche inverse (PDF → source) est l'inverse, et elle brille lors de la relecture. Vous lisez le PDF et vous repérez quelque chose à corriger ? Cliquez à cet endroit (généralement avec une touche de modification) et votre éditeur apparaîtra au premier plan avec le curseur sur la ligne correspondante. Le fait est que vous n’avez jamais besoin de parcourir une longue source pour trouver l’endroit à modifier.

Sous le capot, l'outil de ligne de commande synctex (livré avec SyncTeX) effectue le courtage. La recherche avant correspond à la sous-commande synctex view, la recherche inverse à synctex edit ; les éditeurs et les téléspectateurs les appellent ou implémentent eux-mêmes l'équivalent. Normalement, vous ne les voyez jamais, mais les exécuter manuellement est un moyen pratique d’isoler un problème.

Le fichier .synctex.gz et son activation

Cette correspondance est enregistrée dans un fichier .synctex.gz que le moteur écrit au moment de la compilation. À l'intérieur se trouve une carte — compressée par zlib — qui associe un fichier source, une ligne et une colonne avec une page PDF et les coordonnées d'un rectangle (une boîte) dessus. Il se trouve à côté du PDF, avec le même nom de base et dans le même dossier (main.tex → main.synctex.gz). Ni la recherche avant ni la recherche inverse ne fonctionnent tant que ce fichier n'existe pas.

Pour le générer, transmettez -synctex=1 lors de la compilation (LuaTeX utilise la forme longue --synctex=1). A la main, cela ressemble à ceci. Vous en avez besoin à chaque build, donc en pratique vous le laissez défini une fois dans votre éditeur ou outil de build.

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

La valeur est lue sous forme de bits. 1 donne le .synctex.gz compressé ; -1 donne un .synctex simple et non compressé (pratique lorsque vous souhaitez jeter un coup d'œil à l'intérieur ou déboguer). Au lieu de la ligne de commande, vous pouvez également l'activer depuis le haut de la source avec la primitive TeX \synctex=1.

Les outils de construction ne sont pas différents. Avec latexmk, placez -synctex=1 dans la commande de compilation de votre .latexmkrc. Combiné avec un aperçu continu (-pvc), chaque sauvegarde déclenche une recompilation et une actualisation de l'aperçu, de sorte que la recherche avant et inverse agit toujours sur un .synctex.gz à jour.

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

Moteurs et itinéraire DVI (pLaTeX / upLaTeX)

Les moteurs qui émettent directement PDF — pdfTeX, XeTeX et LuaTeX — comprennent tous -synctex et écrivent eux-mêmes le .synctex.gz ; il en va de même pour pdfLaTeX, XeLaTeX et LuaLaTeX. Jusqu’ici, c’est si simple.

Le pilier du japonais, pLaTeX / upLaTeX, est un pipeline en deux étapes : il émet d'abord un fichier DVI, que dvipdfmx transforme ensuite en PDF. Ici aussi, vous transmettez -synctex=1 au moteur (platex / uplatex). Le moteur écrit d'abord le .synctex.gz en coordonnées DVI. Mais les coordonnées DVI et les coordonnées finales-PDF diffèrent par les décalages et le grossissement dvipdfmx appliqué, de sorte que l'écart doit être comblé après la conversion.

Cette touche finale est la sous-commande synctex synctex update, dont le travail consiste à « mettre à jour le fichier SyncTeX une fois qu'un filtre dvi/xdv → pdf est appliqué ». dvipdfmx lui-même n'a pas d'option -synctex ; à la place, vous donnez à synctex update le grossissement et les décalages horizontaux/verticaux utilisés pour la conversion (-m / -x / -y, les mêmes valeurs transmises au filtre) afin que les coordonnées s'alignent. En pratique, un outil de niveau supérieur tel que ptex2pdf ou latexmk gère toute cette chaîne pour vous.

Comment chaque éditeur le déclenche

SyncTeX lui-même est le fondement commun ; seule la touche ou le clic qui déclenche la recherche avant et arrière diffère entre les éditeurs et les téléspectateurs. Voici quelques combinaisons représentatives (voir chaque page pour la configuration complète). Notez que les visionneuses sans prise en charge de SyncTeX, telles qu'Adobe Acrobat/Reader, ne peuvent pas effectuer de recherche inverse ; les choix courants qui le font sont Skim (macOS), SumatraPDF (Windows) et Okular (Linux).

Un dernier mot sur la précision. SyncTeX correspond à la granularité des « boîtes » composées, donc dans le corps du texte ordinaire, le saut est suffisamment précis - mais à l'intérieur des images TikZ, de l'expansion de macros complexes ou des entrailles des tableaux, la correspondance peut arrondir vers une boîte proche et faire tomber un mot ou deux de votre cible. Il s'agit d'une limitation de l'approche, pas d'un bug.

Une boucle de relecture avec SyncTeX

SyncTeX n'est pas seulement un paramètre ; c'est une habitude de relecture. Lors de la dernière passe avant la soumission de PDF, cliquez sur un mot suspect dans PDF pour revenir à la source, modifiez le manuscrit, enregistrez et reconstruisez, puis utilisez la recherche avant pour revenir à l'endroit corrigé. Si cette boucle de relecture de SyncTeX échoue, vérifiez dans l'ordre : si .synctex.gz se trouve à côté de PDF, si la version a utilisé -synctex=1 et si le spectateur peut exécuter la commande qui appelle l'éditeur.

Le fichier .synctex.gz n'est ni la soumission ni la source du dossier ; c'est une carte de travail régénérable. Normalement, ignorez-le dans Git et soupçonnez-en un obsolète chaque fois que le PDF ou le chemin source a été renommé. Un décalage d'un mot peut constituer une limitation du mappage au niveau de la boîte, mais un saut vers un fichier entièrement différent signifie généralement une sortie obsolète ou un mauvais fichier maître.