Débogue tes humanités

# 1. Qu’est-ce que un langage de balisage ?

Un langage de balisage est un système de codage de texte consistant en un ensemble de symboles insérés dans un document texte pour en contrôler la structure, le formatage ou la relation entre ses parties.

Quelques exemples :

• LaTeX : se concentre généralement sur la typographie et la présentation
• XML : décrit les composantes sémantiques du texte, qui peuvent ensuite être traitées et mises en forme
• HTML : décrit principalement la structure sémantique du texte

# 2. Le traitement numérique du texte

Avec l’utilisation des logiciels de bureautique, on observe une confusion entre structure et mise en forme

Deux paradigmes pour les éditeurs de texte :

• WYSIWYG What You See Is What You Get
• WYSIWYM What You See Is What You Mean

La structure sémantique permet de :

• se repérer dans le texte
• automatiser le traitement

# 3. Les formats de balisage sémantique

• Markdown
• HTML
• XML Dans cette séance, nous approfondissons les caractéristiques de Markdown et de HTML.

# 4. Rappel : de Markdown à HTML avec Pandoc

1. ouvrir son terminal ;
2. créer un fichier en markdown (commande : touch nom-fichier.md) ;
3. insérer un titre, un sous-titre et un paragraphe de quelques mots ;
4. convertir le texte en html via pandoc.

#!/bin/bash

pandoc texte-de-depart.md -o texte-de-sortie.html

5. observer les balises html et ouvrir le document html dans votre navigateur
6. ajouter l’option standalone dans la commande pandoc

#!/bin/bash

pandoc --standalone texte-de-depart.md -o texte-de-sortie.html

7. observer les nouvelles balises html et ouvrir le document dans votre navigateur : remarquez-vous des différences entre les deux conversions ?

# 5. Markdown et HTML : les balises principales

• Les principales balises du HTML
• Les correspondances entre markdown et HTML

# 5. Markdown

# 5.1. Markdown, un «  standard  » ?

«  Markdown  » c’est deux choses : une syntaxe de balisage de texte brut et un outil logiciel qui convertit le balisage de texte brut en HTML pour la publication sur le web. Markdown n’est pas un standard, parce qu’il n’est spécifié de manière non ambiguë.

A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. (John Gruber, inventeur de Markdown)

• CommonMark : il propose une version standard et minimaliste de Markdown

# 5. Markdown

# 5.2. Markdown et ses saveurs

Il existent nombreuses variantes de la syntaxe de Markdown, qui sont des sur-ensembles de la syntaxe de base. Voici quelques exemples :

• Multimarkdown : tableaux, citations, notes de bas de page, etc. Version minimaliste, se préoccupe de maintenir l’interopérabilité et la convertibilité des balises (par exemple en HTML ou en PDF en passant pas LaTeX).
• GitHub Flavored Markdown (GFM) : pensé pour l’interface en ligne de GitHub. listes des tâches, ~texte barré~, insertion automatique de liens, possibilité de visualiser les couleurs spécifiés, etc.
• Markdown Extra : librairie dédié (PHP Markdown Lib). classes et attributs à certains éléments, support pour les abbreviations (<abbr>), deux niveaux des classes pour les notes de bas de page, etc.
• R Markdown : conçu pour la science des données. Exécution du code et intégration les résultats. Attention : l’exécution marche dans des environnements spécifiquement pensés pour R ou Python, comme RStudio IDE. Extension du format : .Rmd

# 5. Markdown : les balises principales

# 5.3. Markdown et ses usages

N.B. Notre objectif n’est pas connaître la syntaxe de tous les saveurs de markdown, me de connaître la syntaxe de base et éventuellement les saveurs qui répondent le mieux à nos besoins.

Si vous êtes curieux­·ses, vous pouvez comparer les différences entre les versions de Markdown :

• Babelmark
• Un résumé sur GitHub

# 6. Où écrire en Markdown ?

Les éditeurs de texte qui supportent Markdown sont beaucoup, mais voici quelques exemples :

• Stylo
• StackEdit
• HedgDoc (collaboratif !)
• Un éditeur dédié tel que Zettlr (pensé pour la rédaction scientifique), Obsidian (avec une vue sous forme de graph), Typora (avec prévisualisation à même le texte balisé), iA Writer (application dont l’ergonomie est professionnellement épurée).
• Un éditeur de texte(!), comme TextEdit (macOS), Notepad (Windows), GEdit ou éditeur de texte (distributions linux), nano/vim/emacs/… (éditeur basé dans le terminal).

# 7. La conversion en HTML

Attention à la «  saveur  » de Markdown supportée par vote outil de conversion.

Par exemple, Pandoc propose une variante particulière : Pandoc’s Markdown.

# 7. La conversion en HTML

# 7.1. des outils permettant la conversion

Étant donné que plusieurs environnements d’écriture permettent d’exporter en HTML des textes écrits en markdown, bien qu’ils n’offrent pas les mêmes possibilités de personnalisation que Pandoc.

Voici quelques exemples :

• Stylo (qui utilise Pandoc pour la conversion)
• Hedgedoc
• Zettler

# 7. La conversion en HTML

# 7.2. Exercice : une présentation en HTML avec HedgeDoc

• ouvrir un document HedgeDoc « Demo instance » à CE LIEN
• copier le texte suivant dans le document
  • HTML
  • créé en 1989-1990
  • langage de balisage
  • né pour la structuration de documents hypertextes
• diviser le texte en 4 diapositives, en suivant les instructions à CETTE PAGE
• Menu > Slide Mode pour afficher les diapositives en HTML

# 7. La conversion en HTML

# 7.3. Exercice : personnaliser une présentation HedgeDoc

Consultez CETTE PRÉSENTATION pour comprendre les possibilités de personnalisation.

Par exemple, vous pouvez ajouter des métadonnées au début du document :

1
2
3
4
5
6

---
title: HTML
slideOptions:
  theme: simple
  transition: 'fade'
---

Ou une image de fond au début de chaque diapositive :

<!-- .slide: data-background="proto://lien/vers/l-image/de/fond.jpg" -->

# 8. HTML

# 8.1. Quel est l’intérêt de convertir en HTML ?

HTML est le langage du Web, utilisé par tous les navigateurs pour afficher du contenu.

Par exemple, nous pouvons encore afficher le contenu de ce site, créé par Tim Berners-Lee au CERN en 1990 : du HTML brut avec beaucoup d’hyperliens. C’est le site web le plus ancien que nous connaissons.

Regardons le site : pourquoi a-t-il l’air si « daté » ?

# 8. HTML

# 8.2. Rappel : la structure d’un document en HTML (un exemple)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<!DOCTYPE html>
<html lang="fr">
  <head>
	  <title>Ma page</title>
	  <link rel="icon" href= "favicon.ico" />
  </head>
	<body>
	  <p>Du texte.</p>
	</body>
</html>

# 8. HTML

# 8.3. Rappel : les principales caractéristiques de HTML

• HTML est un standard, mais il y a pas de systèmes de validation stricte (comme dans la cas de XML)
• Les balises sont imbriquées. Il n’est PAS possible de les chevaucher. Par exemple, cette syntaxe est incorrecte : <p><em>du texte</p></em>.

# 8. HTML

# 8.4. Exercice : trouvez l’erreur

Dans ce court texte HTML, il y a des erreurs. Pouvez-vous les trouver ?

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

<!DOCTYPE html>
<html>
  <head>
    <title>Exemple de page Web</title>	
  </head>
    <h1>Ma Page Web</h1>
    <p>Voici un paragraphe.</p>
    
    <h3>Une liste de courses</h3>
    <ul>
      <li>Pommes</li>
      <li>Oranges</li>
      <li><strong>Poires</li></strong>
    </ol>
    
    <h2>Une image de chat</h2>
    <img src="chat.jpg" alt="Un chat mignon">
    
    <p>C'est la fin de ma page.
  </body>
</html>

# 9. Pourquoi le format texte ?

« Des fichiers plutôt que des applis » par Steph Ango (l’un des créateurs du logiciel Obsidian) :

Les applications sont éphémères, mais vos fichiers ont une chance de durer.
(Apps are ephemeral, but your files have a chance to last.)

— Steph Ango, File over app.

# 10. La conversion avec Pandoc

# 10.1. Pour adapter la conversion à nos besoins : les modèles Pandoc – Partie 1

• créer un document markdown à partir de votre terminal avec commande touch
• inclure un texte de votre choix
• ajouter des métadonnées, qui seront traitées par votre modèle Par exemple :

1
2
3
4
5
6

---
title: Mon document markdown => HTML
author: Jeanne Doe
date: 2023-11-07
rights: Creative Commons BY-SA 4.0. Certains droits réservés.
---

• créer le document contenant votre modèle (commande: touch mon-template.html) et insérer votre modèle

# 10. La conversion avec Pandoc

# 10.2. Pour adapter la conversion à nos besoins : les modèles Pandoc – Partie 2

Grâce à l’option --template de Pandoc, nous pouvons appliquer le modèle à notre html de sortie.

#!/bin/bash

pandoc --template mon-template.html mon-document.md -o mon-document.html

Et si je veux ajouter le pied de page spécifié dans les métadonnées à mon modèle ?

Déb/u/o/gue tes humanités

CC BY-NC-SA Chaire de recherche du Canada sur les écritures numériques, Bibliothèque des lettres et des sciences humaines, Ouvroir d'histoire de l'art et de muséologie numérique. — giulia.ferretti@umontreal.ca ; louis-olivier.brassard@umontreal.ca