# Choisir un moteur de document

Comprenez comment les documents LaTeX, Typst, Markdown, Quarto et Calepin deviennent un PDF et choisissez le compilateur dont votre projet a besoin.

Un moteur transforme votre source dans le document que les gens lisent. Choisissez la langue du document au moment de créer un projet. Pour un projet LaTeX, vous pouvez aussi choisir quel compilateur LaTeX exécute la compilation.

## Choisir une langue

| Votre travail | Commencez par | Comment cela devient un PDF |
|---|---|---|
| Une soumission à une revue, une classe de thèse établie ou un projet `.tex` existant | LaTeX | Tectonic, ou un compilateur exécuté via `latexmk` |
| Un nouvel article, rapport ou CV avec une syntaxe de composition concise | Typst | Le Typst 0.15.1 intégré, ou une autre version de Typst que le projet épingle |
| Un brouillon en prose, des notes ou un document à exporter vers plusieurs formats | Markdown | Pandoc convertit la source en LaTeX ; Tectonic produit le PDF |
| Un rapport d'analyse, un article ou une présentation dont le code R, Python ou Julia produit les résultats | Quarto | Quarto convertit les fichiers `.qmd` ou `.Rmd` en PDF, en page web ou en diapositives |
| Un document Typst avec des blocs de code | Calepin | Calepin exécute le code, puis le Typst intégré construit le PDF |

Ce choix détermine la barre d'outils de l'éditeur, la syntaxe du source et les formats d'export disponibles. Changer de compilateur LaTeX ne traduit pas le document en Typst ni en Markdown. Pour déplacer un projet LaTeX vers Typst, [convertissez-le en un nouveau projet Typst](/docs/typst/#convert-a-latex-project-to-typst).

## Tectonic

Utilisez **Tectonic** pour une installation LaTeX simple. Il est fourni avec Oleafly, télécharge les paquets TeX dont une compilation a besoin et les met en cache pour les compilations suivantes. Commencez ici quand votre modèle n'exige pas un compilateur particulier.

Compilez une fois en ligne avant de voyager. Un projet en cache peut compiler hors ligne ; un nouveau paquet peut encore demander un téléchargement. Activez **Paramètres → Général → Mode hors ligne** pour demander à Tectonic d'utiliser son cache.

## pdfLaTeX

Choisissez **pdfLaTeX** quand un éditeur ou un projet existant le précise. Il suit le flux de travail LaTeX traditionnel et convient bien aux anciennes classes et combinaisons de paquets. Il exige une distribution TeX avec `latexmk` installé.

## XeLaTeX

Choisissez **XeLaTeX** pour un projet qui le demande, en particulier s'il utilise `fontspec`, des polices OpenType ou un texte multilingue. Assurez-vous que les polices nommées par la source sont installées ou incluses avec le projet. Il passe aussi par `latexmk`.

## LuaLaTeX

Choisissez **LuaLaTeX** pour un modèle qui l'exige, une composition fondée sur Lua ou le flux PDF balisé d'Oleafly. Les PDF balisés portent une structure de document que les technologies d'assistance peuvent utiliser. Lancez les [vérifications Preflight](/docs/preflight/) pour examiner le résultat ; le choix du compilateur seul n'établit pas la qualité des balises.

## Typst

Oleafly est livré avec Typst 0.15.1. Créez un projet Typst, écrivez dans des fichiers `.typ` et cliquez sur **Recompiler**. Il n'y a aucune installation TeX à effectuer.

**Paramètres → Moteurs → Typst** peut aussi installer Typst 0.11 à 0.15 et utiliser un Typst déjà installé sur votre ordinateur. Chaque projet épingle sa propre version, ainsi un article garde sa mise en page quand Oleafly passe à un Typst plus récent. Typst télécharge les paquets depuis Typst Universe la première fois qu'un document les importe, et le **Mode hors ligne** le limite aux paquets déjà en cache ou conservés dans le projet.

Typst a sa propre syntaxe, ses paquets et sa gestion des polices. [Projets Typst](/docs/typst/) couvre les versions, les paquets, les polices et les variantes de compilation. Le [guide d'écriture Typst](/docs/writing/typst/) contient un document de départ complet et les commandes de la barre d'outils.

## Markdown

Markdown utilise **Pandoc** pour préparer un document composé et Tectonic pour construire son PDF. Ouvrez **Paramètres → Moteurs → Markdown** pour installer Pandoc lorsqu'il manque. Ouvrez ensuite votre projet Markdown et compilez-le.

Consultez [Écriture en Markdown](/docs/writing/markdown/) pour les titres, les listes, les mathématiques et l'éditeur visuel. Le [guide d'export](/docs/export/) explique les formats de sortie que le projet propose.

## Quarto

Quarto transforme les documents `.qmd` et `.Rmd` en PDF, en page web ou en diapositives. Oleafly utilise le Quarto installé sur votre ordinateur s'il en trouve un. Sinon, ouvrez **Paramètres → Moteurs → Quarto** et sélectionnez **Télécharger Quarto 1.10.19**. Le bouton affiche aussi la taille du téléchargement. Oleafly vérifie le téléchargement avant de le décompresser et garde la copie dans son propre dossier d'application. Si vous compilez avant que Quarto soit installé, l'aperçu propose de l'installer sur-le-champ, ou **Ouvrir les paramètres du moteur**.

Le premier format que déclare le document détermine ce que vous obtenez :

- `pdf`, `typst` et `beamer` produisent un PDF. `format: typst` ne demande aucune installation TeX. `pdf` et `beamer` passent par LaTeX : installez donc TinyTeX depuis **Paramètres → Moteurs → LaTeX** si vous n'avez pas encore TeX.
- `html`, `revealjs` et `dashboard` produisent une page web. Sélectionnez **Ouvrir dans le navigateur** dans l'aperçu pour la voir.

Quand le document ne déclare aucun format, Oleafly en cherche un dans `_quarto.yml` ou `_metadata.yml`, dans le dossier du document et les dossiers au-dessus jusqu'à la racine du projet. Sans format nulle part, Quarto produit une page web. Un fichier `.Rmd` qui nomme une sortie R Markdown `output:`, comme `pdf_document`, reçoit le format Quarto correspondant.

Le code s'exécute dans le R, le Python ou le Julia déjà présent sur votre ordinateur. Oleafly ne les installe jamais, et **Langages**, dans le même onglet des paramètres, affiche ceux qu'il a trouvés. Le code Python demande aussi Jupyter dans ce Python. L'export propose DOCX et HTML, tous deux produits par Quarto. La boîte de dialogue **Nouveau projet** propose deux modèles Quarto : **Quarto article**, un PDF construit via Typst, et **Quarto slides**, une présentation reveal.js.

## Calepin

Calepin exécute le code d'un document Typst et place les résultats dans le PDF. Un document Calepin est un fichier `.typ` qui importe `/.calepin/calepin.typ`. Créez-en un à partir du modèle **Calepin report**, ou ouvrez la flèche à côté de **Recompiler** dans un projet Typst et choisissez **Calepin** sous **Moteur (ce projet)**.

Installez-le depuis **Paramètres → Moteurs → Calepin** de la même façon que Quarto, avec **Télécharger Calepin 0.0.61**. Calepin compile avec le Typst fourni avec Oleafly. Un bloc dont le langage n'est pas installé affiche une courte note, et le reste du document se construit quand même. L'export propose HTML, produit par Calepin.

## Autoriser le code dans un projet

Le code d'un document Quarto ou Calepin s'exécute avec vos droits : il reste donc désactivé dans chaque projet tant que vous ne l'autorisez pas. Après une compilation qui avait besoin de code, un bandeau au-dessus de l'éditeur indique que le code est désactivé et propose **Autoriser le code dans ce projet**. Vous pouvez aussi ouvrir la flèche à côté de **Recompiler** et choisir **Exécuter le code sur cet ordinateur** sous **Code (cet ordinateur)**. **Désactivé** le désactive de nouveau. N'autorisez le code que si vous faites confiance à chaque fichier du projet.

Ce choix ne s'applique qu'à cet ordinateur. Il n'est pas enregistré dans le projet, et changer le moteur du projet désactive de nouveau le code. Dans un [projet partagé](/docs/collaboration/), Oleafly redemande, car toute personne qui peut modifier le projet peut changer son code.

Tant que le code est désactivé :

- Quarto affiche le code de chaque bloc sans l'exécuter. Les filtres, les shortcodes, `_extensions`, les scripts de pré-rendu et de post-rendu, et le code R en ligne exécutent du code même dans ce cas : un document qui les utilise ne compile donc pas tant que vous n'autorisez pas le code.
- Calepin ne peut pas ignorer le code. Oleafly construit le PDF avec Typst seul, à partir des résultats que Calepin a enregistrés lors de sa dernière exécution. S'il n'y en a pas, la compilation s'arrête et vous demande d'autoriser le code.

Un dossier que vous [ouvrez en place](/docs/library/#folders-opened-in-place) doit aussi recevoir votre confiance avant que Quarto ou Calepin puisse le compiler. La synchronisation entre la source et le PDF n'est disponible pour aucun de ces deux moteurs.

## Définir une valeur par défaut pour les nouveaux projets

Ouvrez **Paramètres → Moteurs → LaTeX** et choisissez **Moteur de compilation par défaut** : **Tectonic (intégré)** ou **latexmk (TeX du système)**. Tout projet LaTeX que vous créez ensuite démarre dessus :

- Un projet vierge ou un modèle de la boîte de dialogue **Nouveau projet**, ainsi qu'un projet de recherche.
- Un ZIP, un dossier, un article arXiv ou un dépôt GitHub importé.
- Un document que vous convertissez en projet LaTeX, comme un fichier Word ou un PDF.

Le moteur est écrit dans le `project.json` du projet, ainsi un coauteur qui ouvre le projet le compile de la même façon. Un projet importé qui nomme pdfLaTeX, XeLaTeX ou LuaLaTeX garde ce compilateur quand il arrive sur `latexmk`. Le compilateur enregistré d'un projet existant reste son propre choix.

Un dossier que vous [ouvrez en place](/docs/library/#folders-opened-in-place), sans moteur propre, suit la valeur par défaut dès que vous lui accordez votre confiance. Jusque-là, il s'affiche et se compile avec Tectonic. Oleafly n'écrit rien dans le dossier dans un cas comme dans l'autre.

Pour Typst, ouvrez **Paramètres → Moteurs → Typst** et choisissez la version par défaut. Les nouveaux projets Typst épinglent la version qui est la valeur par défaut au moment de leur création. Modifier la valeur par défaut ensuite ne déplace pas les projets existants.

## Changer le compilateur du projet actuel

Ouvrez la flèche à côté de **Recompiler** dans la [barre d'outils du projet](/docs/project-toolbar/). Dans un projet LaTeX, choisissez Tectonic, Auto, pdfLaTeX, XeLaTeX ou LuaLaTeX sous **Compilateur (ce projet)**, puis compilez. Lisez le journal si un modèle réclame un paquet ou une police que l'installation sélectionnée n'a pas.

Dans un projet Typst, le même menu propose plutôt **Version de Typst (ce projet)**. Choisissez une version installée, ou **Par défaut** pour suivre les Paramètres. Son groupe **Moteur (ce projet)** fait passer le document de **Typst** à **Calepin**, et inversement.

## Détecter une distribution TeX existante

Ouvrez **Paramètres → Moteurs → LaTeX** et examinez la chaîne d'outils détectée. Oleafly vérifie la présence d'une installation de compilation complète, y compris `latexmk` et les outils associés. Une installation système partielle ne prend pas le pas sur une installation gérée fonctionnelle.

## Installer le TinyTeX géré

Utilisez le contrôle d'installation dans les paramètres du moteur LaTeX si vous avez besoin d'un compilateur traditionnel et n'en avez pas. Oleafly télécharge sa propre installation TinyTeX sous `~/.oleafly/tinytex` ; aucun accès administrateur n'est requis. Prévoyez environ 250 Mo pour le téléchargement initial et de l'espace supplémentaire pour les paquets.

## Gérer les paquets

La liste des paquets dans les paramètres du moteur LaTeX permet de filtrer les paquets, d'examiner leurs descriptions et de les ajouter ou retirer. Des badges de balisage identifient les paquets qui demandent une attention particulière lors de la production d'un PDF balisé. Ces contrôles gèrent la distribution TeX utilisée par `latexmk` ; Tectonic a un cache distinct.

[Lire le guide des paquets LaTeX et du PDF balisé →](/docs/latex-engines/)