Commit 0d302a65 authored by Antoine Fauchié's avatar Antoine Fauchié

Merge branch '1-relecture-corrections' into 'master'

Corrections mineures, formulations

Closes #1

See merge request marviro/tutorielmdpandoc!3
parents e79fc815 3cb20d63
Pipeline #1037 failed with stages
in 19 seconds
# 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 :
......
Markdown is supported
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