Archives par étiquette : markdown

logo zotero

Zotero & Zettlr

Zotero est un logiciel de gestion de données bibliographiques gratuit et OpenSource qu’il est possible de combiner à Zettlr pour créer une environnement d’écriture complet pour la recherche.

L’installation de l’extension Better BibTeX pour Zotero (voir Prérequis logiciels) permet de générer des clefs de citations qui, dans les grandes lignes, assurent un lien entre les entrées de votre bibliothèque Zotero et votre environnement d’écriture Zettlr. Ce processus est donc comparable à celui des plugins Zotero pour Word ou LibreOffice.

Lier sa bibliothèque Zotero à Zettlr

Une fois l’extenstion Better BibTeX pour Zotero installée, il est nécessaire d’exporter votre bibliothèque afin que Pandoc Citeproc puisse en citer les références.

Sous Windows ou MacOS, sélectionnez dans Zotero la bibliothèque ou la sous-collection de références que vous souhaitez utiliser avec Zettlr. Cliquez sur Fichier puis Exporter la bibliothèque…. Sélectionnez Better CSL JSON comme format d’export et cochez la case Tenir à jour.

Il s’agit ensuite de lier votre bibliothèque à Zettlr.

Sous Windows ou MacOS, allez dans l’onglet Citations dans les Préférences de Zettlr. Cliquez sur l’icône page (📄) à droite du champ de saisie Fichier de références bibliographiques (au format CSL JSON ou BibTex).
Une boîte de dialogue apparaîtra alors pour naviguer vers le fichier .csl. Sélectionnez-le et Zettlr chargera automatiquement la base de références.

Dès lors, Better BibTex s’assurera de maintenir ainsi la synchronisation entre Zotero et le fichier .csl créé. Par conséquent, chaque changement effectué dans Zotero sera automatiquement et immédiatement mobilisable dans Zettlr.

Personnaliser les clefs de citation

Il est possible de personnaliser les clefs de citation à partir de l’onglet Better BibTeX dans les Préférences de Zotero. La génération des clefs se fait à l’aide de fonctions et de filtres dont on trouve une liste commentée sur le site du développeur (voir Documentation).

Fenêtre des Préférences de Zotero pour la configuration de Better BibTeX.

ATTENTION — La mise à jour des clefs de citation dans Zotero ne se fait pas automatiquement, mais manuellement.

Sous Windows ou MacOS, sélectionnez l’ensemble des entrées, puis Clic droit > Better BibTeX > Rafraîchir la clé de citation.
La modification peut prendre de quelques secondes à plusieurs minutes avant de s’afficher.

Prérequis logiciels

Systèmes

  • Windows (10 ou plus récent)
  • Mac OS X (11.6 ou plus récent)
  • Linux

Éditeur de texte

Il existe de nombreux éditeurs de texte dédiés au langage de balisage léger (LBL) Markdown. Nous avons fait le choix de développer plus spécifiquement notre chaîne de production de contenus autour de Zetllr.

  • Zettlr (version 2)

Sous Windows, téléchargez l’application (.exe) à partir de la ⇩ page de téléchargement et de double-cliquez dessus pour l’ouvrir.
Sous MacOS, téléchargez le fichier image disque (.dmg) à partir de la ⇩ page de téléchargement et double-cliquez dessus pour le monter. Faites ensuite glisser l’icône Zettlr dans le répertoire Applications.
Sous Linux, il existe des paquets deb et rpm pré-construits qu’il suffit d’installer.

Logiciels requis

Pour importer et exporter des fichiers, Zettlr s’appuie sur Pandoc qui, dans le cas de l’export en fichiers PDF, s’appuie lui-même sur LaTeX.

N.B. Il existe différentes méthodes d’installation pour Pandoc et LaTeX. Nous décrivons ici celle qui nous semble la plus simple.

  • Pandoc (version 3) est un progiciel gratuit et OpenSource de conversion de documents numériques en ligne de commande. Il est considéré comme le “couteau-suisse de l’édition”.

Sous Windows, téléchargez le programme d’installation (.zip ou .msi) à partir de la ⇩ Page de téléchargement et de double-cliquez dessus pour l’ouvrir.
Sous MacOS, téléchargez le programme d’installation (.zip ou .pkg) à partir de la ⇩ Page de téléchargement et de double-cliquez dessus pour le lancer.
Sous Linux, utilisez le gestionnaire de packages pour rechercher et installer Pandoc.

N.B. Une fois Pandoc installé, il est automatiquement reconnu par Zettlr.

  • LaTeX est un système de composition de documents gratuit et OpenSource destiné à faciliter l’utilisation du processeur de texte TeX. LaTeX désigne aussi un langage informatique de balisage.

Sous Windows, téléchargez le programme d’installation (.exe) à partir de la ⇩ Page de la distribution MiKTeX et double-cliquez dessus pour le lancer.
Sous MacOS, téléchargez le programme d’installation (.pkg) à partir de la ⇩ Page de la distribution BasicTeX et double-cliquez dessus pour le lancer.
Sous Linux, utilisez le gestionnaire de packages pour rechercher et installer les packages LaTeX disponibles. Il s’agit en général du package XeTeX.

N.B. Une fois LaTeX installé, il est automatiquement reconnu par Zettlr.

Logiciel additionnel

Zettlr permet la citation grâce à un moteur de citation composé de trois éléments : une bibliothèque de références pouvant être citées, une feuille de style pour modifier l’apparence des citations et un moteur de prévisualisation. Zotero, associé au plugin BetterBibTex, est l’application recommandée pour gérer les références bibliographiques.

  • Zotero (version 6) est un logiciel de gestion de données bibliographiques gratuit et OpenSource.

Sous Windows, téléchargez le programme d’installation (.exe) à partir de la ⇩ Page de téléchargement et double-cliquez dessus pour le lancer.
Sous MacOS, téléchargez le fichier image disque (.dmg) à partir de la ⇩ Page de téléchargement et double-cliquez dessus pour le monter. Faites ensuite glisser l’icône Zotero dans le répertoire Applications.
Sous Linux, téléchargez l’archive (.tar.bz2) à partir de la ⇩ Page de téléchargement et double-cliquez dessus pour en extraire les contenus et exécutez zotero pour lancer le logiciel.

N.B. Afin de pouvoir récupérer automatiquement les métadonnées des bases de données documentaires en ligne, Zotero nécessite l’installation d’un connecteur pour votre navigateur web. Nous ne détaillons pas ici cette procédure (voir Documentation).

  •  BetterBibTex (version 6) est un plugin qui permet d’associer à chaque référence de la bibliothèque Zotero un identifiant unique.

Sous Windows, MacOS et Linux téléchargez le plugin (.xpi) à partir de la ⇩ Page de téléchargement. Cliquez sur Outils > Extensions > > Install Add-on From File et sélectionnez le fichier du plugin (.xpi) préalablement téléchargé. Relancez Zotero.

Photo de Jordan Harrison sur Unsplash

logo yaml

YAML

Ce billet est en cours d’écriture, les informations ne sont donc pas encore complètes.

Le YAML est un format simple de représentation de données conçu pour être lisible par des humains, tout en travaillant avec des langages de programmation (c’est presque la quadrature du cercle !). Dans le cadre du Markdown, le langage YAML est avant tout utilisé pour déclarer en en-tête des informations sur le fichier qui ne font pas partie du contenu à proprement parler, c’est-à-dire des métadonnées comme le nom de l’auteur, les mots-clés, ou le titre.

Exemple d’en-tête YAML. 

À savoir

Un certains nombres de paramètres d’affichage dépendent des déclarations du YAML. Par exemple, la création d’une bibliographie finale du document, d’une table des matières, mais aussi des éléments de ponctuations selons les normes anglaises ou françaises (citation, guillemets, etc.), il est donc important de compléter le YAML avant l’export. D’autres paramètres vont dépendre de Pandoc1.

La langue

Pour déclarer la langue, il faut utiliser des valeurs de la norme BCP-47. Elle est composée d’une première valeur qui indique la langue et d’une deuxième valeur pour indiquer la région. Les deux valeurs sont séparées par un tiret :

en-US pour l'anglais américain.

En plus d’intervenir au moment de l’export sur la ponctuation, cette variable contrôle la langue des éléments généré automatiquement comme, par exemple, le titre de la bibliographie2.

Quelques exemples de clés de langue

  • Allemand : de-DE
  • Anglais : en-GB ; en-US ; en-CA
  • Français : fr-FR ; fr-CA (Canada) ; fr-CH (Suisse) ; fr-BE (Belgique)
  • Espagnol : es-ES ; es-US ; es-MX (Mexique)
  • Italien : it-IT ; it-CH
  • Néerlandais : nl-BE ; nl-NL
  • Chinois : zh-CN ; sh-HK (Hong Kong) ; zh-TW (Taiwan)

  1. Voir à ce sujet les billets “Du markdown au word” ; “Du markdown au pdf” ; “Du markdown au html”. []
  2. Ce titre n’existe pas dans le corps du fichier md, il est ajouté si le YAML déclare une bibliographie finale []
suite de livres

[Ressources] Markdown

À tout seigneur, tout honneur : la page dédiée au Markdown sur le site de son créateur John Gruber, “Markdown”, Daring fireball, décembre 2004, <https://daringfireball.net/projects/markdown>, consulté le 2 février 2022.

Une ressource fort utile, “à la fois plaidoyer et petit manuel”, orientée vers l’écriture académique avec Markdown et Pandoc : Markdown et vous (https://infolit.be/md), décembre 2021. Ce site est le fruit du travail de Bernard Pochet, maître de conférences en agronomie et directeur des Presses universitaires de Liège.

Sur Zettlr, lire le retour d’expérience d’Arthur Perret, Zettlr 2.0, octobre 2021, <https://www.arthurperret.fr/blog/2021-10-20-zettlr-2.html>, consulté le 1er février 2022. De façon générale, nous recommandons la lecture des articles et billets sur les processus d’écriture d’Arthur Perret, doctorant en sciences de l’information et de la communication à l’université Bordeaux Montaigne.

Antoine Fauchié, Fabriques de publication : Zettlr, Quaternum.net, août 2020, <https://www.quaternum.net/a-propos/>, consulté le 1er février 2022. Là encore, il ne faut pas hésiter à regarder les autres ressources du carnet de ce “veilleur du numérique et de ses formes”, actuellement en doctorat à l’université de Montréal. Il est l’un des artisans de l’outil d’écriture Stylo.

La lumineuse leçon de Dennis Tenen et Grant Wythoff, “Rédaction durable avec Pandoc et Markdown”, Programming Historian, <doi.org/10.46430/phfr0013>, consulté le 2 février 2022. Leur développement sur la philosophie du Markdown est éclairant et ouvre de nombreuses pistes de réflexion.

La documentation de Zettlr (https://docs.zettlr.com/fr), disponible dans de nombreuses langues dont le français, est très bien construite. On y trouve de nombreux exemples et quelques vidéos (en anglais) pour un pas-à-pas des manipulations à réaliser.

Quelques ressources complémentaires pour aller plus loin sur le Markdown et Pandoc :

Photo de Laura Kapfer sur Unsplash

logo zettlr

Zettlr, un outil pour l’écriture académique

Si éditer du Markdown peut se faire sur un simple éditeur de texte, la démocratisation de ce langage a conduit au développement de nombreux éditeurs spécifiques, aujourd’hui disponibles sur tous les systèmes d’exploitation ou en ligne. Citons notamment Typora, Ulysses, iA Writer, Apostrophe, Stylo, etc.

Parmi ceux-là, Zettlr (à prononcer Settler) a retenu plus particulièrement notre attention. Cet éditeur open-source gratuit et multiplateforme (Windows, Mac OS et Linux) a été développé par Hendrik Erz, qui contrairement à ce que vous pourriez penser n’est pas développeur informatique, mais chercheur en Sciences humaines et sociales ! Un outil conçu par et pour des chercheurs, c’est donc la voie vertueuse empruntée par Zettlr — c’est aussi celle suivie par l’éditeur en ligne Stylo développé dans le cadre de la chaire de recherche du Canada sur les Écritures numériques — et qui permet aujourd’hui aux auteurs académiques de se réapproprier leurs outils d’écriture et donc leur pensée (voir notamment sur ce point les travaux de Jack Goody ou Françoise Waquet1).

Exemple de vue proposée par Zettlr : à gauche, l’arborescence des documents ; au centre, l’éditeur de texte ; à droite, plusieurs vues complémentaires comme la table des matières, la liste des mots clefs, la bibliographie ou les fichiers joints au document.
Exemple de vue proposée par Stylo : à gauche, la table des matières du document ; au centre, l’éditeur de texte ; à droite, les différentes strates de métadonnées liées au document.

Mais, la force de Zettlr réside aussi dans le fait qu’il associe à la simplicité du Markdown la puissance de Pandoc, véritable couteau suisse pour la conversion de documents numériques, et celle du fameux langage et système de composition LateX (à prononcer Latèk, pour ne pas se trahir dans les soirées mondaines du numérique 😌).

En outre, la refonte qu’a récemment connue l’interface de Zettlr, a permis un gain de performance et une intégration plus ergonomique de Pandoc. Pour celles et ceux qui à ce stade seraient inquiets, rassurez-vous : il n’est plus question d’user ses yeux à entrer d’ésotériques lignes de commande pour faire fonctionner Pandoc. Un panneau dédié permet de paramétrer finement tous les exports à l’aide de fichiers de configurations YAML, pour “YAML Ain’t Markup Language” ( YAML n’est pas un langage de balisage … les développeurs ne manquent pas d’humour 😉).

Zettlr et son environnement

  • un langage pour structurer son propos (Markdown) ; 
  • un outil pour gérer des références bibliographiques et faciliter leur citation (Zotero et Better BibTeX) ; 
  • un convertisseur pour produire des documents publiables sous différentes formes (Pandoc et LaTeX).

Astuces

Zettlr et Word — Il n’est pas possible de récupérer le texte d’un document Word par un simple copier-coller (Ctrl/Cmd+V). Zettlr convertit en effet  le texte en image et l’importe en tant que telle. Pour copier-coller du texte depuis Word, il faut réaliser un collage sans forme (Shift+Ctrl/Cmd+V).

Avis

Zettlr a produit un comparatif avec d’autres éditeurs qui, même s’il participe à la mise en avant des qualités de la solution développée par Hendrik Erz, donne une vue intéressante sur les caractéristiques de ce type d’outils (aperçu, personnalisation du thème, langues, moteur de recherche intégré, tag management, etc.).

  1. Jack Goody, La raison graphique. La domestication de la pensée sauvage, trad. Jean Bazin et Alban Bensa, Paris, Les Éditions de Minuit, coll. “Le sens commun”, 1979. Françoise Waquet, L’ordre matériel du savoir Comment les savants travaillent (XVIe-XXIe siècles), Paris, CNRS Éditions, 2015. []
balise dans la mer

Syntaxe du markdown

Emphase

Pour créer des caractères gras ou italiques, il suffit de les encadrer à l’aide d’astérisques (*) ou de tirets bas ou underscore (_) : un seul pour l’italique et deux pour le gras. 

*italique* ou _italique_
**gras** ou __gras__

Le gras italique sera produit par la combinaison des deux codes, c’est-à-dire trois astérisques ou tirets bas.

Continuer la lecture

Histoire et philosophie du markdown

Le Markdown a été créé en 2004 par John Gruber en collaboration avec Aaron Swartz — prodige de l’informatique et militant de la première heure pour  la “culture libre” dont le destin tragique a fortement marqué les esprits dans le monde du numérique et au-delà1. Initialement pensé dans le but de générer aisément du code HTML pour le Web, le Markdown a été progressivement étendu afin de produire d’autres formats de documents et notamment du PDF qui, bien que n’étant pas un format ouvert au sens strict, est actuellement le plus utilisé dans nos échanges et notre documentation. 

De ce fait, il existe aujourd’hui plusieurs dialectes Markdown qui sont autant d’implémentations de la syntaxe originelle. Malgré ces évolutions, la philosophie initiale du projet n’a pas évolué2. Cette couche de formatage du texte — à l’inverse d’autres — ne doit pas être perçue comme une complication supplémentaire, mais comme un pas vers une forme de décroissance du numérique (low-tech). Par ailleurs, le Markdown répond au principe du Single-source publishing qui vise à produire des documents dans différents formats (HTML, ePub, PDF, Word, etc.) à partir d’un seul et même fichier source (ou pivot)3. Il est ainsi possible de télécharger le billet originel (modifié en janvier 2023), à l’origine de cette série sur le Markdown, sous plusieurs formats et différentes mises en forme, le tout généré à partir d’un seul et même fichier Markdown :

Fichier Markdown
Fichier PDF Document
Fichier PDF LaTeX
Fichier Word
Fichier LaTeX
Fichier HTML

En un mot, la sobriété numérique du Markdown permet une fluidité dans le traitement informatique et un gain d’énergie dans le processus d’éditorialisation, allant de l’écriture à l’illustration, puis de l’édition à la publication dans un continuum économe et aussi pérenne que possible.

Exemple de vue proposée par un éditeur Markdown (iA Writer) pour visualiser au fil de l’écriture le rendu du code4.

Les points forts du markdown s’appuient sur un ensemble de principes, tels que ceux exposés par Dennis Tenen et Grant Wythoff5 :

  • Pérennité6 ;
  • Priorité à la lisibilité humaine ;
  • Séparation de la forme et du contenu ;
  • Compatibilité avec la recherche universitaire ;
  • Indépendance vis-à-vis des plateformes.

  1. Voir le film documentaire The Internet’s Own Boy, 2014. []
  2. Voir John Gruber, “Markdown”, Daring fireball, décembre 2004, <https://daringfireball.net/projects/markdown>, consulté le 2 février 2022. []
  3. Outre la légèreté du fichier en lui-même (en termes de stockage), cela évite les doublons et le travail de report de modification dans différents documents en vue de les maintenir à jour. Seul le fichier pivot est corrigé et permet de régénérer l’ensemble des autres fichiers selon les besoins. []
  4. Les dispositifs d’iA Writer en faveur de la concentration de l’aut·eur·rice sont, selon nous, efficaces et très confortables. Nous nous permettons donc cette petite exception publicitaire pour un logiciel propriétaire. []
  5. Dennis Tenen et Grant Wythoff, “Rédaction durable avec Pandoc et Markdown”, Programming Historian, <doi.org/10.46430/phfr0013>, consulté le 2 février 2022. []
  6. “Le texte brut permet d’assurer la transparence et répond aux normes de préservation à long terme. MS Word pourrait disparaître comme l’a déjà fait Word Perfect, mais le texte brut restera toujours facile à lire, cataloguer, explorer et transformer. De plus, le texte brut facilite une gestion des versions du document simple et puissante, ce qui profite à la collaboration et à l’organisation des brouillons. Vos fichiers en texte brut seront accessibles sur téléphones, tablettes et possiblement même sur un ordinateur peu puissant dans une bibliothèque isolée. Le texte brut est à compatibilité descendante et à l’épreuve du temps. Peu importe quels logiciels et matériel informatique le futur nous réserve, ils seront en mesure de comprendre le texte brut.” []

[Annonce] Atelier sur les écritures multisupports

Quatre rendez-vous sur le markdown et les écritures multisupports sont au programme 2022-2023 des évènements du laboratoire ILLE. Ils seront l’occasion de réfléchir aux processus d’écriture scientifique et de sobriété numérique. L’objectif est de réussir à employer différents supports à partir d’un même texte, et donc de limiter le temps de traitement et le travail de mise en forme de la recherche. L’enjeux n’est pas seulement technique, il est aussi intellectuel. Le temps consacré à la reprise formel des textes, au travail de versionning et de conversion est source de charge mentale pour les chercheurs. Pouvons-nous faire plus simple et plus vite ?

Au programme :

  • 19 janvier (16h-18h) : Du brouillon à la note, de la note à l’article. Atelier sur Pandoc
  • 10 février (10h-12h) : Exposer à partir de ses notes. Atelier sur Marp
  • 16 mars : Grapher ses notes. Atelier sur Cosma
  • 20 avril : Surfer sur ses notes. Atelier sur Hugo

Les ressources utilisées durant les séances seront déposées au fur et à mesure de l’avancée de l’atelier. Elles pourront être enrichies en fonction des discussions et retours / relectures proposées, n’hésitez pas à m’écrire !

Photo by Laura Chouette on Unsplash.

machine à écrire

[Annonce] Atelier sur l’écriture multisupport

Quatre rendez-vous sur le blogging et la vulgarisation scientifique sont au programme 2023 des évènements EVEille. Ils sont l’occasion de réfléchir ensemble aux façons d’écrire, présenter et partager nos recherches.

  • 19 janvier : Du brouillon à la note, de la note à l’article. Atelier sur Pandoc
  • 16 février : Exposer à partir de ses notes. Atelier sur Marp
  • 16 mars : Grapher ses notes. Atelier sur Cosma
  • 20 avril : Surfer sur ses notes. Atelier sur Hugo

Les ressources utilisées durant les séances seront déposées au fur et à mesure de l’avancée de l’atelier. Elles pourront être enrichies en fonction des discussions et retours / relectures proposées, n’hésitez pas à m’écrire !

Photo by Florian Klauer on Unsplash

[Introduction] Markdown, se réapproprier ses outils d’écriture

Ce billet a été complètement remanié en janvier 2023. Son contenu n’a pas été supprimé, mais redistribué et augmenté dans plusieurs billets-ressources à l’occasion de l’atelier sur les écritures multisupports. Ces textes sont amenés à évoluer et à s’enrichir au fil des séances de l’atelier et de nos expérimentations1.

Nos savoir-faire en matière d’écriture académique semblent encore trop souvent conditionnés par nos seuls parcours de formation ou notre inscription dans un champ disciplinaire. Pourtant, comme le résument Alexandre Hobeika et Florent Bédécarrats, “l’édition scientifique fait aujourd’hui face à plusieurs transformations : réduction des budgets et des “personnels de renfort” éditoriaux, transition des supports vers le numérique, et crise de la reproductibilité des résultats2”. Chacune d’entre elles, par les conséquences qu’elle porte sur les auteur·rice·s, conduit à interroger nos pratiques et nos outils d’écriture.

Continuer la lecture
  1. Un grand merci à Anne Réach-Ngô, Régis Witz, Pierre Willaime, Romane Marlhoux, Michela Lagnena, Marie-Lou Solbach et Yanet Hernández pour les échanges avant et pendant l’atelier []
  2. Alexandre Hobeika et Florent Bédécarrats, « Une alternative à Word : écrire en RMarkdown », Data Sciences Sociales [en ligne], 25 février 2017. Consulté le 24 janvier 2023. []