Sublime Text (LaTeXTools)

Pour écrire LaTeX dans Sublime Text, le choix standard est le package LaTeXTools. Installez-le à partir de Package Control et vous obtenez un système de construction, la complétion de \ref/\cite, la complétion de commandes, la complétion de nom de fichier et des sauts bidirectionnels avec votre visionneuse PDF, le tout sans quitter l'éditeur. Cette page explique l'installation et la configuration de LaTeXTools, le fonctionnement de la version, sa configuration pour le japonais, la complétion et la recherche avant/inverse via SyncTeX.

Qu'est-ce que LaTeXTools

Sublime Text ne compose pas lui-même TeX ; la compilation proprement dite est effectuée par une installation de TeX sur votre machine — TeX Live, MacTeX ou MiKTeX. LaTeXTools est le package qui relie les deux. Pendant que vous modifiez un fichier .tex, il active automatiquement les commandes de construction, l'analyse du journal avec les erreurs apparues, l'achèvement contextuel, le passage à la définition des \labels et des clés de citation, et le lancement/synchronisation de votre visionneuse PDF. En soi, LaTeXTools ne produit rien : il suppose une distribution TeX locale et un visualiseur PDF.

Deux pièces externes sont nécessaires. Tout d'abord, une distribution TeX : MacTeX sur macOS (le plus léger BasicTeX fonctionne aussi, mais vous devez ajouter latexmk séparément — voir ci-dessous) ; MiKTeX ou TeX Live sur Windows ; TeX Live de TUG sur Linux. Deuxièmement, un visualiseur PDF : pour activer la recherche directe et inverse, LaTeXTools suppose un visualiseur par défaut par plate-forme.

L'installation passe par Package Control (la méthode recommandée). Si vous n'avez pas encore Package Control, installez-le d'abord ; puis ouvrez la palette de commandes (Ctrl+Shift+P sur Windows/Linux, Cmd+Shift+P sur macOS), choisissez Package Control : Install Package et choisissez LaTeXTools dans la liste. Aucun redémarrage n'est nécessaire : ouvrez un fichier .tex, la syntaxe passe à LaTeX et les fonctionnalités prennent vie.

Deux choses à faire ensuite. Tout d'abord, préparez un fichier de paramètres : à partir de la palette de commandes, exécutez LaTeXTools : Réinitialiser les paramètres utilisateur par défaut, ou utilisez Préférences | Forfait Settings | LaTeXTools | Settings – Utilisateur, pour créer un LaTeXTools.sublime-settings modifiable dans votre répertoire User (ne modifiez jamais le fichier par défaut dans le dossier du plugin — il est écrasé lors de la mise à niveau). Deuxièmement, vérifiez la configuration : LaTeXTools : Check System vérifie si les commandes TeX et votre visionneuse sont accessibles depuis LaTeXTools. Lorsque quelque chose ne fonctionne pas, c'est la première commande à exécuter.

Bâtiment

Les builds s'exécutent sur la clé standard de Sublime Text, Ctrl+B (Cmd+B sur macOS). Avec une seule build, le constructeur par défaut (traditional) effectue toutes les opérations suivantes : il enregistre le fichier actuel, appelle la commande de build TeX, analyse le journal et répertorie les erreurs, les avertissements et (si activé) les mauvaises boîtes dans un panneau en bas, puis ouvre la visionneuse PDF et effectue une recherche avant sur votre curseur. Cliquez sur une erreur dans le panneau pour accéder à la ligne correspondante.

Le fait clé est que le générateur traditional exécute latexmk sous le capot. Précisément : il invoque latexmk sur TeX Live et MacTeX, et texify sur MiKTeX. latexmk détermine ce qui a changé et réexécute la chaîne d'outils autant de fois que nécessaire, en gérant les répétitions jusqu'à ce que les références croisées et la table des matières soient réglées. Sa ligne de commande par défaut est grossièrement :

latexmk -cd -f -%E -interaction=nonstopmode -synctex=1

Lecture : -cd se déplace dans le répertoire de la source avant le traitement ; -f continue aussi loin que possible même après une erreur ; -interaction=nonstopmode évite les arrêts interactifs ; et -synctex=1 émet les données de synchronisation dont la recherche avant/inverse ci-dessous a besoin. %E est un espace réservé que LaTeXTools remplace par -pdf (pdfLaTeX), -lualatex, -xelatex, etc. en fonction du moteur choisi — la sélection du moteur revient donc à échanger ce vers quoi %E se développe.

Le moyen le plus simple de choisir un moteur est d'insérer un commentaire magique en haut du fichier. Mettez ceci sur la première ligne de votre .tex et le moteur correspondant est utilisé (sans lui, pdfLaTeX). Dans un projet multi-fichiers, cette ligne va dans le fichier racine (maître). Pour la compatibilité TeXShop, TS-program fonctionne à la place de program :

%!TEX program = lualatex

Seules trois valeurs sont acceptées : pdflatex, lualatex et xelatex. De même, %!TEX options = ... transmet les options au moteur (par exemple --shell-escape) et %!TEX root = <master> nomme le fichier racine. Au lieu de commentaires magiques, vous pouvez également les configurer dans votre fichier de paramètres ou votre projet Sublime. Dans le bloc builder_settings de LaTeXTools.sublime-settings, vous pouvez ajuster program (le moteur), options, command et env (les variables d'environnement) :

{
  "builder_settings": {
    "program": "lualatex",
    "options": ["--shell-escape"]
  }
}

Un autre élément essentiel est le paramètre texpath — le PATH utilisé pour trouver les commandes LaTeX lors de l'appel de latexmk et de ses amis. Sur macOS en particulier, un Sublime Text lancé à partir du GUI a un PATH différent de votre shell, donc une valeur incorrecte échoue avec « commande introuvable ». La règle : texpath doit inclure $PATH (vos propres chemins d'abord, puis $PATH). Une valeur macOS typique est "/Library/TeX/texbin:$PATH" ; sur Windows, quelque chose comme "C:\\texlive\\2026\\bin\\windows;$PATH", adapté à votre installation. Sur Windows, définissez également distro sur "texlive" ou "miktex" pour correspondre à votre distribution.

Si traditional ne suffit pas, le paramètre builder vous permet de passer à basic (un constructeur minimal exécutant le moteur plus bibtex/biber) ou script (un constructeur avancé dans lequel vous écrivez votre propre séquence de commandes dans script_commands). Notez que --output-directory, --aux-directory et --jobname fonctionnent uniquement avec latexmk (le générateur traditional sur OS X/Linux), basic ou script — ils sont ignorés par MiKTeX. texify.

Configuration pour le japonais

C’est ici que les utilisateurs japonais trébuchent souvent. %!TEX program n'accepte que pdflatex, lualatex et xelatex — vous ne pouvez pas nommer uplatex ou platex directement. Si vous tapez du japonais avec LuaLaTeX, c'est simple : écrivez %!TEX program = lualatex et utilisez une classe luatexja/ltjsclasses-family.

D'un autre côté, pour utiliser upLaTeX + dvipdfmx — la combinaison classique de papier japonais dans les sciences, qui construit un DVI puis le convertit en PDF — l'approche la plus propre consiste à laisser .latexmkrc choisir le moteur. Puisque le constructeur traditional appelle latexmk sous le capot, en plaçant un .latexmkrc dans le répertoire du projet (ou votre répertoire personnel) fait passer la chaîne d'outils au traitement japonais sans presque aucune modification des propres paramètres de LaTeXTools. Voici un exemple upLaTeX + dvipdfmx :

$latex = 'uplatex -synctex=1 -interaction=nonstopmode -file-line-error %O %S';
$bibtex = 'upbibtex %O %B';
$biber = 'biber --bblencoding=utf8 -u -U --output_safechars %O %S';
$makeindex = 'upmendex %O -o %D %S';
$dvipdf = 'dvipdfmx %O -o %D %S';
$pdf_mode = 3;
$max_repeat = 5;

Les points clés : attribuez uplatex à $latex et dvipdfmx à $dvipdf, puis configurez $pdf_mode = 3 pour choisir le chemin « construire un DVI, puis le convertir en PDF avec dvipdfmx ». Passer -synctex=1 à $latex transporte également les données SyncTeX jusqu'au PDF même via DVI, donc la recherche ci-dessous fonctionne. Du côté de LaTeXTools, il est plus sûr de ne pas écrire une ligne %!TEX program (cela sélectionnerait le pdfLaTeX %E).

Pour être plus explicite, vous pouvez nommer latexmk directement via la clé command dans builder_settings. L'écriture de "command": "latexmk" (en conservant des options telles que -pdfdvi dans .latexmkrc) garantit l'exécution de latexmk configuré en japonais. La personnalisation de command désactive la sélection automatique du moteur via %!TEX program, mais dans une configuration qui corrige la chaîne d'outils dans .latexmkrc – comme le font les flux de travail japonais – ce n'est pas une perte.

Achèvement

La complétion de LaTeXTools se répartit en trois familles : complétion de commandes, complétion de \ref/\cite et complétion de nom de fichier/package (l'assistant de remplissage). Tout d’abord, l’achèvement de la commande. LaTeXTools fournit les listes de mots de complétion TeXStudio-derived (CWL) et affiche une fenêtre contextuelle de candidats dès que vous démarrez une commande avec \. Tapez \te, par exemple, et \textit et autres apparaissent. Le comportement est contrôlé par le paramètre command_completion : prefixed (par défaut ; uniquement lorsque le mot commence par \), always ou never. Les candidats aux packages chargés dans votre document sont ajoutés automatiquement via cwl_autoload (activé par défaut). Activez env_auto_trigger et les noms d'environnement sont également renseignés lorsque vous tapez \begin{/\end{.

Ensuite, la complétion des références et citations – l'un des points forts de LaTeXTools. Par défaut, dès que vous tapez \ref{ ou \cite{, un panneau rapide (une liste de candidats) apparaît en haut de l'écran : pour \ref{, tous les \label du document ; pour \cite{, toutes les entrées dans les bibliographies que vous référencez via \bibliography{} ou \addbibresource{} de biblatex. Tapez quelques caractères à filtrer, sélectionnez et appuyez sur Entrée, et la commande entière est insérée, par ex. \ref{my-label}. Tapez une virgule juste avant l'accolade fermante, comme dans \cite{paper1,, et vous choisissez la deuxième clé et les suivantes d'une citation multiple de la même manière.

Deux mises en garde. Tout d'abord, LaTeXTools collecte les candidats à partir du fichier enregistré ; si une étiquette ou une clé que vous venez d'ajouter ne s'affiche pas, enregistrez-la d'abord. Deuxièmement, seuls les fichiers .bib externes sont pris en charge – les \bibitem écrits en ligne ne le sont pas. Si ce déclencheur automatique semble intrusif, une bascule ou un paramètre le désactive. Pour l'invoquer manuellement, appuyez sur Ctrl+l, x (Cmd+l, x sur macOS) ou Ctrl+l, Ctrl+f juste après \ref{ et autres (la même touche que l'assistant de remplissage ci-dessous, qui fonctionne également pour \ref/\cite). Les commandes de référence et de citation de habilef, fantaisieref, varioref, natbib et biblatex sont également reconnues.

Le troisième est le Fill Helper. Tapez \usepackage{, \include{, \input{, \includegraphics{, etc., et il propose une liste de packages ou de fichiers disponibles : packages installés pour \usepackage{ et fichiers dans le répertoire actuel pour les commandes de fichiers (filtrés en fichiers image pour \includegraphics). Ceci également est affiché automatiquement par défaut ou invoqué manuellement avec Ctrl+l, Ctrl+f. La seule étape de préparation est l'achèvement du package : exécutez LaTeXTools : Build cache for LaTeX packages à partir de la palette de commandes une fois pour créer le cache du package.

SyncTeX (recherche avant/inverse)

SyncTeX enregistre la correspondance entre les lignes source et les positions dans le PDF, permettant la recherche avant — passer de votre position d'édition au PDF — et la recherche inverse — passer d'un endroit dans le PDF à la ligne source. La commande de build par défaut de LaTeXTools inclut -synctex=1, donc une build Ctrl+B ordinaire émet les données de synchronisation (.synctex.gz) pour vous. Pour le japonais via DVI, le but est de transmettre également -synctex=1 à $latex dans .latexmkrc, comme indiqué ci-dessus. Le contexte de la façon dont cela fonctionne est couvert sur la page SyncTeX.

La recherche avant s'exécute à partir d'une clé LaTeXTools. Lors de l'édition d'un .tex, appuyez sur Ctrl+l, j (Cmd+l, j sur macOS) et la page PDF correspondant à votre curseur s'affiche. Une recherche avant s'exécute également automatiquement juste après une construction, donc Ctrl+B ouvre à lui seul le bon endroit. (Ctrl+l est normalement « étendre la sélection à la ligne », mais pour les fichiers .tex avec LaTeXTools actif, il est remappé en Ctrl+l, Ctrl+l, libérant Ctrl+l comme préfixe pour les commandes du plugin.) Pour ouvrir simplement le PDF sans synchronisation, utilisez Ctrl+l, v.

La recherche inverse (PDF → source) nécessite que le spectateur rappelle Sublime Text. Le geste de clic diffère selon le spectateur :

• Skim (macOS) — Cmd+Shift+click dans le PDF.
• SumatraPDF (Windows) — double-cliquez dans le PDF.
• Evince (Linux) — Ctrl+clic gauche dans le PDF (Okular : Shift+clic gauche ; Zathura : Ctrl+clic gauche).

Sur macOS — Skim, activez la recherche inverse dans les préférences de Skim : ouvrez l'onglet Préférences → Sync, décochez « Vérifier les modifications de fichiers » et choisissez simplement le préréglage « Sublime Text ». Sur les anciennes versions de Skim sans le préréglage, choisissez « Personnalisé » et définissez Command sur le chemin absolu de subl (/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl) et Arguments sur "%file":%line.

Sur Windows — SumatraPDF, ajoutez d'abord SumatraPDF à votre PATH afin que LaTeXTools puisse le trouver facilement. Les paramètres de recherche inverse UI apparaissent uniquement lorsque vous ouvrez un PDF contenant des données de synchronisation (.synctex.gz), alors construisez une fois avec Ctrl+B, ouvrez le PDF à Sumatra et sous Settings → Options enregistrez la ligne de commande de recherche inverse ci-dessous (ajustez le chemin ST à votre installation) :

"C:\\Program Files\\Sublime Text\\sublime_text.exe" "%f:%l"

Avec un visualiseur dépourvu de support, la clé de recherche avant (Ctrl+l, j) se comporte simplement comme « ouvrez le PDF ». Lorsque la recherche inverse se comporte mal, vérifiez dans cet ordre : si la construction a été exécutée avec -synctex=1, si le préréglage/commande du spectateur est correct et - via LaTeXTools: Check System - si sublime_executable (l'emplacement de subl) est visible.

Vérification LaTeXTools de premier passage

• Vérifiez d'abord : exécutez LaTeXTools: Check System et confirmez que les commandes TeX, le visualiseur PDF et l'exécutable subl sont visibles.
• Décision relative au document japonais : utilisez program = lualatex pour LuaLaTeX ; pour upLaTeX, omettez %!TEX program et mettez la route dans .latexmkrc.
• En cas d'échec : si Ctrl+B indique qu'une commande est manquante, inspectez texpath ; si les références ne sont pas mises à jour, enregistrez et reconstruisez ; si PDF-to-source échoue, vérifiez le paramètre de recherche inverse de la visionneuse.
• Quand en faire un projet : une fois les figures ou les fichiers de chapitre multipliés, épinglez le maître avec un projet Sublime ou %!TEX root afin que Ctrl+B de n'importe quel onglet cible le même PDF.