Commit a0b0468d authored by Nicolas Sauret's avatar Nicolas Sauret
Browse files

Merge branch 'master' of gitlab.huma-num.fr:ecrinum/manuels/tutoriel-markdown-pandoc

parents 557e1e7b 9ffdfe57
# Tutoriel pour apprendre à utiliser la chaîne d'écriture markdown+pandoc
En premier lieu, vous pouvez [vous créer un compte sur Framagit](https://framagit.org/users/sign_in?redirect_to_referer=yes) et [installer les outils nécessaires](./parcours/03_outils.md).
En premier lieu, veuillez [vous créer un compte sur Huma-Num](https://humanid.huma-num.fr/register?skin=humanid&lmAuth=1HumanID) puis [demander la création d'un compte GitLab Huma-Num](https://gitlab.huma-num.fr), vous devez également [installer les outils nécessaires](./parcours/03_outils.md).
## Plan du tutoriel
## Introduction et théorie
......@@ -44,7 +47,7 @@ Produire un ouvrage en HTML, Pdf (LaTeX) et Epub, à partir d'une édition Markd
## Pour aller plus loin
1. **Créer une chaine** en automatisant une série d'actions ou de commandes en utilisant les scripts bash.
1. **Créer une chaîne** en automatisant une série d'actions ou de commandes en utilisant les scripts bash.
- Par exemple, pour produire d'un coup un epub et un pdf à partir d'une source markdown, voir le script [ressources/build.sh](./ressources/build.sh).
- Voir aussi [cette petite documentation](https://doc.ubuntu-fr.org/tutoriel/script_shell) pour créer des scripts.
2. **Utiliser des filtres** pour créer des traitements particuliers selon vos sorties (par exemple «supprimer tous les titres de niveau 3 pour les exports Pdf»).
......
......@@ -3,7 +3,7 @@
**Objectifs de ce tutoriel:**
- créer et éditer des documents divers
- devenir autonome dans l'utilisation de chaines de publications alternatives
- devenir autonome dans l'utilisation de chaînes de publications alternatives
- comprendre les enjeux liés aux formats et aux outils
- savoir trouver l'information qu'il vous manque
......
......@@ -7,7 +7,7 @@ L'édition savante impose des exigences particulières :
1. l'appareil critique accompagnant le texte (notes de bas de page, bibliographie, index, etc.)
2. la citabilité du document (identification, métadonnées)
3. une structuration rigoureuse (balisage non ambigu)
3. une structuration rigoureuse (balisage non ambigu, balisage sémantique)
4. la pérennité du document et des données
-> utiliser des formats qui répondent à ces exigences, permettant notamment d'expliciter la fonction de chaque élément du document (titre, citation, métadonnées, références bibliographiques, etc.)
......@@ -78,23 +78,24 @@ Dans la racine vous trouvez plusieurs "boîtes".
L'emplacement du Dossier correspond à ce qu'on appelle son "chemin" (_path_).
Par exemple, par rapport à l'image ci-dessus, le dossier "Vacances" aura le chemin `/Document Personnel/Images/Vacances (dans un système Unix)` et `C:/Dossier Personnel/Images/Vacances`
Par exemple, par rapport à l'image ci-dessus, le dossier "Vacances" aura le chemin `/Document Personnel/Images/Vacances` (dans un système Unix) et `C:/Dossier Personnel/Images/Vacances` (dans un système Windows).
Il est important que vous connaissiez la structure de l'arborescence de votre ordinateur car c'est ainsi qu'on accède aux fichiers.
### Nomenclature de fichier
_Quel nom donner à un fichier ?_ Une question pas si banale que ça. Il existe des règles qui sont fondamentales pour :
- classer un fichier,
- le retrouver facilement,
- partager ses fichiers avec d'autres personnes
- éviter des problèmes de comptabilité d'un système à un autre
- partager ses fichiers avec d'autres personnes,
- éviter des problèmes de comptabilité d'un système à un autre.
Quelques règles à appliquer :
1. **les noms de fichier ne doivent pas contenir des caractères spéciaux, des accents NI des espaces.** Ce types de caractères peuvent poser des problèmes car l’ordinateur ne les reconnais pas immédiatement, il doit les convertir et dans la conversion il y a souvent des erreurs. Le fichier `mémoire de maîtrise.doc` sera difficile à retrouver. On préférera `memoire_de_maitrise.doc`.
2. **les noms des fichiers doivent être significatifs.** Le fichier `chapitre1.md` ne précise pas de quel ouvrage il est le chapitre 1. On préférera `Espace-numerique_chapitre1.md`.
3. **faites attention aux extensions que vous utilisez.** Par principe, ne masquez pas les extensions de fichiers dans vos navigateurs de fichiers. L'extension est une information primordiale pour la machine et les utilisateurs. Elle renseigne sur le format du contenu du fichier et sur ce qu'on doit/peut faire avec ce fichier. Un fichier `.doc` ne contient pas les mêmes données qu'un fichier `.pdf` par exemple.
1. **Les noms de fichier ne doivent pas contenir des caractères spéciaux, des accents NI des espaces.** Ce types de caractères peuvent poser des problèmes car l’ordinateur ne les reconnais pas immédiatement, il doit les convertir et dans la conversion il y a souvent des erreurs. Le fichier `mémoire de maîtrise.doc` sera difficile à retrouver. On préférera `memoire_de_maitrise.doc` ou `memoire-de-maitrise.doc`.
2. **Les noms des fichiers doivent être significatifs.** Le fichier `chapitre1.md` ne précise pas de quel ouvrage il est le chapitre 1. On préférera `espace-numerique-chapitre-1.md`.
3. **Faites attention aux extensions que vous utilisez.** Par principe, ne masquez pas les extensions de fichiers dans vos navigateurs de fichiers. L'extension est une information primordiale pour la machine et les utilisateurs. Elle renseigne sur le format du contenu du fichier et sur ce qu'on doit/peut faire avec ce fichier. Un fichier `.doc` ne contient pas les mêmes données qu'un fichier `.pdf` par exemple.
Récapitulatif :
......@@ -103,17 +104,11 @@ Récapitulatif :
- extension
- nom parlant
- camelCase
- exemples : `2019-01-11notesEDN6102marcelloVitaliRosati.md`
- exemples : `2019-01-11-notes-EDN6102-marcello-Vitali-Rosati.md`
[pour aller plus loin](http://ptaff.ca/blogue/2008/06/29/les_3_rgles_dor_pour_nommer_un_fichier/).
[Pour aller plus loin](http://ptaff.ca/blogue/2008/06/29/les_3_rgles_dor_pour_nommer_un_fichier/).
### Versionnage
---
Dans la prochaine partie, nous expérimenterons la chaîne _Stylo_, basée sur Markdown comme format pivot.
---
Voir la suite [[02_stylo](./02_stylo.md)]
......@@ -4,11 +4,11 @@
Stylo est un éditeur de texte simplifiant la rédaction et l'édition de documents scientifiques en sciences humaines et sociales.
Vous pouvez consulter [la documentation](http://stylo-doc.ecrituresnumeriques.ca/), [une présentation vidéo](https://www.youtube.com/watch?v=qcwEqbcxBF8).
Vous pouvez consulter [la documentation](http://stylo-doc.ecrituresnumeriques.ca/) ainsi qu'[une présentation vidéo](https://www.youtube.com/watch?v=qcwEqbcxBF8).
### Chaine de publication
### Chaîne de publication
![Chaine de publication Stylo](./media/chaine_stylo_sp.png)
![Chaîne de publication Stylo](./media/chaine_stylo_sp.png)
## Fonctionnalités
......@@ -17,13 +17,13 @@ L'environnement de travail de Stylo intègre une chaîne éditoriale complète b
- **un éditeur de métadonnées**
- **un versionnage**
- **une gestion de la bibliographie**
- **différents formats exports** : HTML5, XML (TEI, Erudit), pdf...
- **différents formats exports** : HTML5, XML (TEI, Érudit), PDF...
- **l'annotation**
- **le partage de document**
### Édition
Un article dans Stylo est composé par trois éléments distincts :
Un article dans Stylo est composé de trois éléments distincts :
- un corps de texte
- des métadonnées
......@@ -36,10 +36,10 @@ L'environnement d'édition est composé de 5 modules :
1. au centre : l'espace d'écriture, consacré au corps de texte de l'article
2. à droite : le bouton [Metadata] ouvre l'éditeur de métadonnées
3. à gauche :
3.1. les Versions pour naviguer et agir sur les différentes versions de l'article
3.2. le Sommaire de l'article liste les titres de niveau 2 et 3
3.3. la Bibliographie liste les références bibliographiques
3.4. les Statistiques offrent quelques données quantitatives sur l'article
1. les Versions pour naviguer et agir sur les différentes versions de l'article
2. le Sommaire de l'article liste les titres de niveau 2 et 3
3. la Bibliographie liste les références bibliographiques
4. les Statistiques offrent quelques données quantitatives sur l'article
![Stylo_Modules](./media/stylo_fullopen_marqued.png)
......@@ -53,19 +53,21 @@ Après vous être créé un compte sur [stylo.ecrituresnumeriques.ca](http://sty
Dans la liste des articles, ouvrez et consultez le document **How-to** qui vous permettra de découvrir les fonctionnalités de Stylo, et vous donnera l'essentiel de la syntaxe Markdown pour éditer un document.
À découvrir :
- le module de versionnage
- le sommaire
- la gestion des références
- les métadonnées
- la comparaison de versions
- le module de versionnage
- le sommaire
- la gestion des références
- les métadonnées
- la comparaison de versions
À éditer :
- déclarer un titre et niveaux de titre
- ajouter un italique
- ajouter une citation
- ajouter une image
- ajouter une note de bas de page
- ajouter une référence
- déclarer un titre et niveaux de titre
- ajouter un italique
- ajouter une citation
- ajouter une image
- ajouter une note de bas de page
- ajouter une référence
Vous pouvez à tout moment visualiser un rendu du document en cours d'édition avec le bouton **[Annotate]**.
......@@ -81,16 +83,16 @@ L'exercice va consister à éditer un article simple à l'aide de Stylo dans le
2. reporter le texte dans Stylo
3. éditer le texte en Markdown et traiter notamment :
- les hyperliens: `[texte du lien](http://lien.ca)`
- les italiques: `un mot *en italique*`
- les italiques: `un mot _en italique_`
- les espaces insécables: en ASCII ` `, ou sur Stylo `CTRL+ESPACE`
- les citations: avec `> ` en début de ligne
4. à titre pédagogique, ajouter des éléments supplémentaires :
- 2 niveaux de titre: `#` niveau 1 et `##` niveau 2
- une ou plusieurs note.s de bas de page: `[^note]`
- une ou plusieurs note.s de bas de page: `[^note]` pour l'appel de note dans le texte et `[^note]: Ma note.` pour le texte de la note en fin de document
- une image: `![Légende de l'image](http://lien.ca/vers/image.jpg)`
5. traiter les deux références bibliographiques:
- générer les références en bibtex (voir tutoriel [Comment importer rapidement une bibliographie vers Zotéro ?](http://www.youtube.com/watch?v=S-f3J9LOqdQ))
- intégrer les clés bibtex dans l'article (voir [Références en markdown/bibtex](./parcours/09_ressources.md#r%C3%A9f%C3%A9rences-en-markdownbibtex))
- intégrer les clés BibTeX dans l'article (voir [Références en Markdown/BibTeX](./parcours/09_ressources.md#r%C3%A9f%C3%A9rences-en-markdownbibtex))
Les deux références utilisés en bibtex :
......@@ -116,7 +118,7 @@ Les deux références utilisés en bibtex :
Stylo permet de produire plusieurs formats à partir du format pivot en Markdown.
Il est possible de choisir entre deux styles de citations : ![moduleexport](./media/exportmodal.png)
Il est possible de choisir entre deux styles de citation : ![moduleexport](./media/exportmodal.png)
1. _inline citations_ : la référence de type _(Goody, 1976)_ est ajoutée dans le corps du texte,
2. _footnotes citations_ : la référence est intégrée avec un appel de note.
......
......@@ -18,18 +18,17 @@
# Quelques outils indispensables
Pour la suite de l'atelier vous aurez besoin
d'installer les outils ci-dessous. L'utilisation de votre ordinateur personnel est recommandée.
Pour la suite de l'atelier vous aurez besoin d'installer les outils ci-dessous. L'utilisation de votre ordinateur personnel est recommandée.
## un éditeur de texte/code
## Un éditeur de texte/code
Les éditeurs de code sont plus ou moins simples selon les fonctionnalités qu'ils offrent. À minima pour l'atelier, l'éditeur devra pouvoir colorer la syntaxe Markdown, LaTeX, html et css (ce qu'ils font tous).
Les éditeurs de code sont plus ou moins simples selon les fonctionnalités qu'ils offrent. À minima, pour l'atelier, l'éditeur devra pouvoir colorer la syntaxe Markdown, LaTeX, HTML et CSS (ce qu'ils font tous).
Suggestion : [Atom.io](https://atom.io/) qui fonctionnera sur toutes les plateformes.
Voir d'autres éditeurs sous [Windows](https://alternativeto.net/software/atom/?platform=windows), [Max](https://alternativeto.net/software/atom/?platform=mac), [Linux](https://alternativeto.net/software/atom/?platform=linux).
Voir d'autres éditeurs sous [Windows](https://alternativeto.net/software/atom/?platform=windows), [Mac](https://alternativeto.net/software/atom/?platform=mac), [Linux](https://alternativeto.net/software/atom/?platform=linux).
## un convertisseur de format
## Un convertisseur de format
Un convertisseur de format permet comme son nom l'indique de convertir le format d'un document en un autre format. Le convertisseur génère alors un nouveau document.
......@@ -40,23 +39,24 @@ Nous utilisons [Pandoc](https://pandoc.org) en ligne de commande.
Nous aurons aussi besoin de l'extension **pandoc-citeproc** pour gérer les références bibliographiques.
## un compte sur framagit.org
## Un compte sur framagit.org
Sur [framagit.org](https://framagit.org/users/sign_in?redirect_to_referer=yes), créez vous un compte. Cela vous sera utile pour :
1. partager votre code avec moi (et la classe si vous le souhaitez),
2. publier des documents en ligne,
3. [participer au wiki](https://framagit.org/edn6102-h2019/edn6102/wikis/home) de ce répertoire.
3. [participer au wiki](https://framagit.org/marviro/tutorielmdpandoc/wikis/home) de ce répertoire.
Cliquez sur le bouton [Request Access] pour demander un accès au répertoire.
**Merci de m'envoyer ensuite votre username.**
## un gestionnaire de version : Git
## Un gestionnaire de version : Git
Le gestionnaire de version Git va vous permettre de communiquer votre code à framagit. Nous verrons ensemble comment l'utiliser.
- Linux: déjà installé
- Mac: déjà installé sinon, dans un terminal :
- Linux : déjà installé
- Mac : déjà installé sinon, dans un terminal :
- installer homebrew : `/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`
- installer Git avec homebrew : `brew install git`
- Windows : [installez Git pour Windows](https://git-scm.com/downloads)
......
# Prise en main de Git
Git est un outil de versionning et de synchronisation de fichier.
Git est un outil de versionnement (_versioning_) et de synchronisation de fichier.
Pourquoi utiliser Git plutôt que Dropbox ? Quand on travaille à plusieurs sur des dossiers complexes, il est utile de documenter nos faits et gestes pour que chacun sache ce qui a été fait. Cela permet de limiter les erreurs, de mieux se répartir les tâches, de rapidement vérifier et valider le travail de chacun.
Par ailleurs, contrairement à une Dropbox, Git n'enregistre d'une version à l'autre que les éléments qui ont été modifiés.
Git gère ainsi un registre, dans lequel toute modification de fichier est inscrite et documentée. Cela permet notamment d'écrire de manière collaborative sur des codes sources, mais aussi sur du texte.
Git gère ainsi un registre, dans lequel toute modification de fichier est inscrite et documentée. Cela permet notamment d'écrire de manière collaborative sur du code source, mais aussi sur du texte.
Dans cet atelier, nous n'exploiterons pas toutes les possibilités de Git, notamment le principe du fork ou de la branche, car chacun travaillera sur son propre répertoire.
Quelques commandes de base :
- `git clone [repertoire]` : clone un "répertoire distant" sur la machine locale dans un "répertoire local", par exemple depuis le serveur framagit.org. Exemple : `git clone https://framagit.org/edn6102-h2019/edn6102.git`
- `git add .` : ajoute tous les fichiers à l'index pour préparer un "commit".
- `git add fichier.md` : ajoute un fichier à l'index pour préparer un "commit" ciblé.
- `git commit -m "message pour documenter la modification"` : valide un commit, c'est-à-dire aussi, déclare et inscrit les modifications au registre Git.
- `git clone [repertoire]` : clone un "répertoire distant" sur la machine locale dans un "répertoire local", par exemple depuis le serveur framagit.org. Exemple : `git clone https://framagit.org/marviro/tutorielmdpandoc.git`
- `git add .` : ajoute **tous** les fichiers à l'index pour préparer un "commit".
- `git add fichier.md` : ajoute **un** fichier à l'index pour préparer un "commit" ciblé.
- `git commit -m "message pour documenter la modification"` : valide un commit avec un message d'information, et donc déclare et inscrit les modifications au registre Git.
- `git pull` : synchronise le répertoire local depuis le répertoire distant, ce qui permet de récupérer des modifications faites par d'autres contributeurs (on _tire_ les modifications des autres depuis le serveur).
- `git push` : synchronise le répertoire distant à partir du répertoire local, ce qui permet de partager son travail avec d'autres contributeurs (on _pousse_ ses modifications vers le serveur).
- `git status` : présente un état du répertoire : quels fichiers ont été ajoutés, modifiés, supprimés.
- `git status` : présente un état du répertoire : quels fichiers ont été ajoutés, modifiés, supprimés, non ajoutés au registre, etc.
- `git diff` : présente les changements de chaque fichier modifié.
- `git log` : présente une liste de commit. C'est l'état du registre.
- `git log` : présente une liste de commit. C'est l'état du registre, une forme d'historique des modifications.
## Exercice - créer son premier répertoire
Vous allez créer un premier répertoire. Allons-y pas à pas :
1. ouvrez un terminal.
Par défault, le terminal s'ouvre dans votre dossier personnel.
Par défaut, le terminal s'ouvre dans votre dossier personnel.
Lancez la commande `ls` pour vous en assurer.
2. créer un dossier gitlab : `mkdir gitlab` et naviguez dedans `cd gitlab`. Le terminal est maintenant positionné dans le répertoire gitlab.
2. créer un dossier gitlab : `mkdir gitlab` et naviguez dedans `cd gitlab`. Le terminal est maintenant positionné dans le répertoire `gitlab`.
3. dans votre navigateur, allez sur https://framagit.org/edn6102-h2019 puis cliquer sur [New Project]. Renseigner le _Project name_ avec votre prénom (sans accents), puis cochez la case "Initialize repository with a README", et enfin le bouton [Create project].
4. vous venez de créer un projet git. Vous allez maintenant le cloner, c'est-à-dire récupérer le répertoire sur votre machine en local. Pour cela, commencez par copier-coller l'url de clonage en cliquant sur le bouton bleu [Clone] en haut à droite, et en copiant l'url HTTPS.
5. dans le terminal, lancez la commande `git clone https://framagit.org/edn6102-h2019/monprenom.git` en remplaçant votreprenom.git par votre prénom..
......
# Edition avec Pandoc
# Édition avec Pandoc
## Prise en main de Pandoc
Pandoc permet de convertir des documents numériques en ligne de commande.
Pandoc permet de convertir des documents numériques en ligne de commande via un terminal.
La commande `pandoc` appelle un ou plusieurs fichier en entrée ainsi que le.leur format d'entrée, un format de sortie ou de conversion, et le fichier de sortie.
La commande `pandoc` appelle un ou plusieurs fichiers en entrée ainsi que leur format d'entrée, un format de sortie ou de conversion, et le fichier de sortie.
- par exemple pour convertir un fichier au format Markdown en HTML: `pandoc -f md -t html fichier.md -o fichier.html`
Par exemple pour convertir un fichier au format Markdown en HTML: `pandoc -f md -t html fichier.md -o fichier.html`
La commande pandoc est hautement configurable. Il faut consulter la [documentation](https://pandoc.org/MANUAL.html) régulièrement en fonction de vos besoins d'éditeur.
La commande `pandoc` est hautement configurable. Il faut consulter la [documentation](https://pandoc.org/MANUAL.html) régulièrement en fonction de vos besoins d'éditeur.
Pour convertir d'un format à l'autre, Pandoc utilise des _templates_ ou des modèles de documents. Il est possible de personnaliser ces modèles, comme nous allons le voir dans la suite de l'atelier.
......@@ -21,7 +21,6 @@ Quelques options de la commande Pandoc à connaître :
- `--toc` (table of contents)
- `--help` (résume les options existantes)
Quelques utilisations possibles :
- vous souhaitez récupérer le contenu d'un document Word (.docx) et poursuivre son édition en Markdown :
......@@ -60,7 +59,7 @@ lang:
---
```
Ces métadonnées sont celles que Pandoc utilise par défaut pour produire les documents dans les différents formats. Mais selon les formats, il en existe d'autres, et il est par ailleurs possible de créer ses propres métadonnées et de les utiliser en modifiant les modèles par défaut de Pandoc.
Ces métadonnées sont celles que Pandoc utilise par défaut pour produire les documents dans les différents formats. Mais selon les formats (il en existe d'autres) il est possible de créer ses propres métadonnées et de les utiliser en modifiant les modèles par défaut de Pandoc.
Ces métadonnées peuvent soit être placées en tête de fichier Markdown, soit être placées dans un fichier séparé, au format YAML (extension : `.yaml`). Dans ce cas, la commande Pandoc précédente devra préciser où sont les métadonnées (ici dans un fichier `metadonnes.yaml`) :
......@@ -98,7 +97,7 @@ link-citations: true
pandoc --standalone --filter pandoc-citeproc -f markdown -t tei monfichier.md -o export.xml
- Conversion d'un fichier ODT (docx fonctionne aussi) en markdown, ce qui produit une meilleure base de travail (remarque: l'option `--extract-media` permet d'extraire les médias du document dans un sous-dossier `/media`)
- Conversion d'un fichier ODT (docx fonctionne aussi) en markdown, ce qui produit une meilleure base de travail (remarque : l'option `--extract-media` permet d'extraire les médias du document dans un sous-dossier `/media`)
pandoc -f odt -t markdown --extract-media=./ --atx-headers export.odt -o exportMD.md
......@@ -112,7 +111,7 @@ Yaml | template | Html (par exemple)
:--|:--|:--
`auteur: Niels Planel` | `<meta name="author" content="$auteur$">` | `<meta name="author" content="Niels Planel">`
Pandoc ne nous permet pas réellement de toucher au corps du texte, à moins d'utiliser des options (voir la documentation) ou des filtres particuliers que l'on peut soit-même créer, selon ses besoins.
Pandoc ne nous permet pas réellement de toucher au corps du texte, à moins d'utiliser des options (voir [la documentation](https://pandoc.org/MANUAL.html)) ou des filtres particuliers que l'on peut soit-même créer, selon ses besoins.
Le corps du texte (c'est-à-dire l'intégralité du fichier markdown par exemple) est ajouté au document de sortie avec la variable `$body$`. S'il n'est pas possible d'intervenir dans le template de ce corps de texte, il est par contre possible d'intervenir avant ou après la variable `$body$` (pour ajouter du contenu générique par exemple), et d'intervenir sur les métadonnées du document.
......@@ -120,11 +119,11 @@ Pour créer un template personnalisé, commençons par récupérer le template p
pandoc -D html > montemplate.html
nb: cette commande fonctionne pour tous les formats de sortie (sauf docx/odt qui sont gérés autrement, voir la documentation Pandoc).
Note : cette commande fonctionne pour tous les formats de sortie (sauf docx/odt qui sont gérés autrement, voir la documentation Pandoc).
Vous pouvez maintenant ouvrir le fichier `montemplate.html` dans Atom pour voir comment il est structuré.
Comme exercice, nous allons ajouter une donnée dans le yaml, modifier le template en fonction et déclarer dans la commande Pandoc de prendre en compte le nouveau template.
Comme exercice nous allons ajouter une donnée dans le yaml, modifier le template en fonction et déclarer dans la commande Pandoc la prise en compte du nouveau template.
Dans les métadonnées yaml, nous allons ajouter la clé/valeur en ajoutant une simple ligne :
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment