Folio Writer ☰

Plier le compilateur :
les filtres Lua de pandoc dans Folio Writer

La chaîne de compilation de Folio Writer couvre 99 % des besoins — citations, renvois, modèles, formats. Les filtres Lua sont l’échappatoire pour le dernier 1 % : la règle maison bizarre d’une revue, vos propres abréviations, ce qu’aucune case à cocher n’a prévu. Un filtre, ce sont quelques lignes de Lua qui réécrivent le document pendant la compilation, et pandoc les exécute nativement — rien à installer.

Ce qu’est vraiment un filtre

Quand pandoc compile votre manuscrit, il commence par analyser le Markdown pour en faire un arbre de document — paragraphes, titres, spans, citations. Un filtre Lua est un ensemble de fonctions portant le nom de ces éléments ; chacune est appelée avec chaque élément correspondant et peut renvoyer un remplacement. Ne renvoyez rien pour le laisser tel quel, renvoyez {} pour le supprimer, renvoyez de nouveaux éléments pour le transformer. C’est tout le modèle.

En associer un dans Folio Writer

1. Enregistrez votre filtre dans un fichier .lua — le garder dans le projet (par exemple dans un sous-dossier Filters de Research) lui permet de se synchroniser et de voyager avec le manuscrit.
2. Dans l’onglet Style de la fenêtre de compilation : Filtres Lua ▸ Ajouter un filtre Lua…. Ajoutez-en plusieurs et ils s’exécutent dans l’ordre, après pandoc-crossref.
3. Les filtres sont enregistrés avec le profil de compilation — ainsi « Soumission Elsevier » et « Brouillon pour mon directeur » peuvent chacun avoir leur propre jeu.

Exemple 1 · Une date toujours à jour

Tapez @@today n’importe où ; le document compilé porte la date de compilation — pratique pour les lettres de motivation et les filigranes de brouillon :

-- today.lua
function Str(el)
  if el.text == "@@today" then
    return pandoc.Str(os.date("%B %e, %Y"))
  end
end

Exemple 2 · Des notes de brouillon qui ne partent jamais

Écrivez vos notes pour vous-même dans un div délimité, visible pendant la rédaction et garanti absent de la sortie :

::: draft
Ask Wei whether the 2019 calibration applies here.
:::

-- strip-draft.lua
function Div(el)
  if el.classes:includes("draft") then
    return {}          -- deleted from every compiled format
  end
end

Associez-le uniquement à vos profils de soumission et les notes continuent d’apparaître dans votre profil « brouillon pour le directeur » — les filtres par profil servent exactement à cela.

Exemple 3 · Votre propre balisage en ligne

Donnez à [key result]{.highlight} un vrai sens selon le format — un marquage jaune en HTML, un surlignage dans les PDF LaTeX :

-- highlight.lua
function Span(el)
  if not el.classes:includes("highlight") then return nil end
  if FORMAT:match("latex") then
    local out = pandoc.Inlines(pandoc.RawInline("latex", "\\hl{"))
    out:extend(el.content)
    out:insert(pandoc.RawInline("latex", "}"))
    return out
  elseif FORMAT:match("html") then
    local out = pandoc.Inlines(pandoc.RawInline("html", ""))
    out:extend(el.content)
    out:insert(pandoc.RawInline("html", ""))
    return out
  end
end

Pour la branche LaTeX, ajoutez une fois pour toutes le paquet de surlignage dans les métadonnées de format : header-includes: \usepackage{soul}.

Déboguer sans tâtonner

Deux habitudes rendent l’écriture de filtres indolore. Pour voir l’arbre sur lequel vous travaillez, lancez pandoc -t native sur un extrait dans le Terminal — il affiche exactement les éléments que vos fonctions recevront. Et quand une compilation se comporte mal, le Journal de compilation et d’aperçu montre la ligne de commande pandoc complète et sa sortie, erreurs de filtres comprises. Une remarque propre à Folio Writer : un filtre dont le fichier a été déplacé est ignoré plutôt que de faire échouer la compilation — consultez le journal si un filtre semble inactif sans rien dire.

Pour aller plus loin

La documentation des filtres Lua de pandoc recense chaque élément et chaque fonction utilitaire, et la collection de filtres de la communauté regorge de filtres prêts à l’emploi — gestion des abréviations, retouches de tableaux, rendu de diagrammes. Tout ce qui s’y trouve se glisse directement dans la fenêtre de compilation.

Télécharger Folio Writer gratuitement → · Plus de guides