SO-MATE 2022 – Pau

Atelier

En mode texte

Markdown - Stylo - Pandoc - Notebooks - …

Gaëlle Deletraz (IR - UMR TREE) / Julien Rabaud (Bibas - SCD UPPA)

Liens à retenir pour apprendre Markdown

(*) Ne traite pas des références bibliographiques, spécificité de Pandoc.
Voir Manuel Pandoc > Citations

Fichiers binaires, fichiers textes

  • Fichiers binaires : nécessitent un logiciel spécifique (souvent avec license) pour être lus et édités :
    • .docx, .odt, .pdf
  • Fichiers textes : lisibles et modifiables dans un simple éditeur de texte :
    • .md, .html, .tex, .csv, .json, .bib, .css, .py, …
  • + peuvent être manipulés par des utilitaires standards du monde libre, très puissants :
    • awk, sed, grep, git, bash, …

Markdown est un langage de balisage léger créé en 2004 par John Gruber avec l’aide d’Aaron Swartz. Il a été créé dans le but d’offrir une syntaxe facile à lire et à écrire.
Un document balisé par Markdown peut être lu en l’état sans donner l’impression d’avoir été balisé ou formaté par des instructions particulières.

source : Wikipedia (fr) – Markdown

Fond - Structuration - Balisage

Forme - Composition - Feuille de style

/!\ Je ne suis pas sémiologue

Ma rencontre avec Markdown

Des logiciels qui l’implémentent

  • Framanotes (fermé)

    • (Instance de Turtle - alternative à Pocket)

  • -> Zotermite (R. de Mourat) - [sources]

  • Les notes dans Vivaldi (navigateur web, non-libre),

  • La zone de transcription dans Tropy,

  • Les fichiers README.md des dépôts Github…

Aujourd’hui encore plus

Exemples récents :

Des collègues qui l’utilisent

Frédérique Flamerie de la Chapelle

Open access and data librarian - Université de Bordeaux

Cécile Arènes

Conservatrice des bibliothèques
Chargée de mission Données de la recherche et Humanités numériques à la bibliothèque de Sorbonne Université.

Des chercheurs en design et en SIC

Robin de Mourat

Designer de recherche en méthodes numériques
Medialab – Science-Po

Antoine Fauchié

Doctorant – Chaire de recherche du Canada en Écritures numériques.

Arthur Perret

Doctorant – Laboratoire MICA, UBM.

la rubrique veille de son blog est une mine aussi !

Mes expériences

“en mode texte”

L’inventaire Jacques Blot

  • Documentation du projet (site perso)

    Gaelle Chancerel, Julien Rabaud. Bibliothèque Omeka Jacques Blot : Valorisation d’un fonds patrimonial des monuments protohistoriques basques. Omeka — Projets scientifiques, culturels et/ou documentaires, Octobre 2020, Nancy. ⟨hal-03025301⟩

  • Collection OmekaS

    • Les medias html des items monuments ont été généré avec Pandoc.

Mémoire de master en littérature

Accompagnement d’un étudiant. Écriture avec Zettlr (et Zotero).
Exports .docx (avec modèle), html (template, css, javascript) et pdf (template).

Des diaporamas

markdown -> reveal.js

Un blog personnel avec Eleventy

Générateur de site statique
(comme Jekyll, Hugo ou Gatsby…)

Carnet de UjuBib

/!\ pas actualisé depuis un an !

Prises de notes avec Obsidian

Depuis deux ans.

Auto-hébergement d’une instance HedgeDoc

Découverte des Notebooks

Markdown en pratique

Sources de la présentation et fichiers pour les exercices --> Gitlab UPPA

Écrire en markdown dans Stylo

  • Aller dans le sous-dossier Stylo du dossier Gitlab.
  • Copier-coller dans Stylo le contenu du fichier texte.txt

Un autre éditeur en ligne d’articles scientifiques,
collaboratif et basé sur markdown : Authorea

Les citations avec Better BibTeX for Zotero

https://retorque.re/zotero-better-bibtex/

–> démo

Exercices Pandoc

Conversion de documents avec Pandoc

  • Se placer dans le dossier Projets/Article

  • Ouvrir article.md

Modèles de documents et templates

Démo docx
Démo html (css, templates)
Démo pdf (Paramètres LaTeX, templates)

YAML

YAML Ain't Markup Language
(Yet Another Metadata Language)

Métadonnées, options & paramètres

Pour tous les writers

Pour Html

Pour LaTeX/pdf

Les Defaults Files

Guide Pandoc

pandoc -d file

Des métadonnées sémantiques

Metadata for markdown / MkDocs :

What does JSON-LD in YAML look like?

The metadata that we use for OCX is a profile of schema.org / LRMI,  OERSchema and few bits that we have added because we couldn’t find them elsewhere. Here’s what (mostly) schema.org metadata looks like in YAML:

"@context":
    - "http://schema.org"
    - "oer": "http://oerschema.org/"
    - "ocx": "https://github.com/K12OCX/k12ocx-specs/"
"@id": "#Lesson1"
"@type":
    - oer:Lesson
    - CreativeWork
learningResourceType: LessonPlan
hasPart:
    "@id": "#activity1-1"
author:
    "@type": Person
    name: Phil Barker

AutoPandoc

Notebooks

Jupyter

Installer avec Anaconda ou en ligne de commandes avec les outils python standards (pip).

Documentation officielle : https://docs.jupyter.org/en/latest/

Un format de soumission :

Journal for digital history

Google Colab

https://colab.research.google.com

Rmarkdown et Quarto

Comment R Markdown produit-il un document ?

Comment Rmarkdown produit-il un document ?

source : https://www.book.utilitr.org/rmarkdown.html

Paramètres dans l’en-tête

--- 
title: "Produire des documents avec R Markdown"
author: "Daffy Duck"
date: "2022-04-22"
output: 
  html_document:
    keep_md: true
    self_contained: true
    highlight: kate
    toc: yes
  pdf_document: 
    fig_caption: yes
    highlight: kate
bibliography: book.bib
description: "Un document où je révèle que je ne suis pas un canard"
---

source : https://www.book.utilitr.org/rmarkdown.html

Paramètres des blocs de code R (chunks)

  • nommage (recommandé) {r mon_bloc}

    ```{r calcul1}
x <- 2+7
x

  • permet de les appeler dans RStudio

  • options d’affichage (pour le rendu par knitr) :
    {r echo=FALSE, warning=FALSE}

    Option Valeurs possibles Valeur par défaut
    echo TRUE/FALSE TRUE
    eval TRUE/FALSE TRUE
    include TRUE/FALSE TRUE
    results 'hide'/'asis'/'markup'/'hold' 'markup'
    error TRUE/FALSE TRUE
    warning TRUE/FALSE TRUE
    message TRUE/FALSE TRUE

source : https://www.book.utilitr.org/rmarkdown.html

  • dimensions de la figure (si figure)
```{r, fig.width=12, fig.height=8}
hist(iris$Sepal.Length)
...

source : https://www.book.utilitr.org/rmarkdown.html

Observable

Questions ?

MERCI !