Skip to content

GitLab

Commit 7ac98780 authored by marviro's avatar marviro
Browse files

initial commit

parents
Hide whitespace changes
Inline Side-by-side
LICENSE 0 → 100644
View file @ 7ac98780
Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
You are free to:
Share — copy and redistribute the material in any medium or format
Adapt — remix, transform, and build upon the material
for any purpose, even commercially.
This license is acceptable for Free Cultural Works.
The licensor cannot revoke these freedoms as long as you follow the license terms.
README.md 0 → 100644
View file @ 7ac98780
# Tutoriel pour apprendre à utiliser la chaîne d'écriture markdown+pandoc
En premier lieu, veuillez [vous créer un compte sur Framagit](https://framagit.org/users/sign_in?redirect_to_referer=yes) (et envoyez-moi votre username) et [d'installer les outils nécessaires](./parcours/03_outils.md).
## Plan du tutoriel
0. Introduction générale ([parcours/00_introduction](./parcours/00_introduction.md))
1. Un peu de théorie ([parcours/01_theorie](./parcours/01_theorie.md))
- Gestion de fichiers : arborescence, nomenclature et versionnage
- Formats de texte
- Chaines éditoriales
- Edition savante
2. Exercice 1 - Stylo ([parcours/02_stylo](./parcours/02_stylo.md))
- présentation
- édition d'un article
- export d'un article
3. Outils ([parcours/03_outils](./parcours/03_outils.md))
- Installation des outils
- Prise en main de git ([parcours/03b_git](./parcours/03b_git.md))
4. Exercice 2 - édition ([parcours/04_edition](./parcours/04_edition.md))
- Prise en main de Pandoc
- Exercice de conversion
- Templating
## Pour aller plus loin
Produire un ouvrage en HTML, Pdf (LaTeX) et Epub, à partir d'une édition Markdown.
5. Initialisation de l'ouvrage ([parcours/05_livre](./parcours/05_livre.md))
6. Production du HTML ([parcours/06_livreHTML](./parcours/06_livreHTML.md))
7. Production du PDF ([parcours/07_livreLatex](./parcours/07_livreLatex.md))
8. Production de l'Epub ([parcours/08_livreEpub](./parcours/08_livreEpub.md))
- créer une chaine 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.
- 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»).
- Voir la documentation [Filtres](http://pandoc.org/filters.html) et [Filtres Lua](http://pandoc.org/lua-filters.html).
- utiliser des [préprocesseurs](https://github.com/jgm/pandoc/wiki/Pandoc-Extras#preprocessors) pour complexifier le markdown source.
- consulter le [wiki Pandoc](https://github.com/jgm/pandoc/wiki) qui référence de multiples ressources.
---
[Démarrer](./parcours/00_introduction.md)
media/stylo_3f_marqued.svg 0 → 100644
View file @ 7ac98780
This source diff could not be displayed because it is too large. You can view the blob instead.
parcours/00_introduction.md 0 → 100644
View file @ 7ac98780
# Introduction générale
**Objectifs de l'atelier:**
- créer et éditer des documents divers
- devenir autonome dans l'utilisation de chaines de publications alternatives
- comprendre les enjeux liés aux formats et aux outils
- savoir trouver l'information qu'il vous manque
**Fonctionnement de l'atelier**
- ressource principale : https://framagit.org/laconis/edn6102
- un wiki pour collaborer : https://framagit.org/laconis/edn6102/wikis/home
**Evaluation**
Aucun rendu n'est demandé pour cet atelier, qui sera évalué entièrement sur la présence et la participation.
---
Voir la suite [[01_theorie](./01_theorie.md)]
parcours/01_theorie.md 0 → 100644
View file @ 7ac98780
# Un peu de théorie
## Gestion de fichiers
### L'arborescence des fichiers
Il faut d'abord comprendre comment est organisé votre ordinateur et où se trouvent vos fichiers.
Votre disque dur peut être compris comme une grande boîte dans laquelle se trouvent d'autres boîtes (dossiers).
La boîte principale est ce qu'on appelle "racine". Dans un ordinateur Unix (Mac ou Linux) la racine est `/`. Dans un ordinateur Windows, la racine est `C:/`.
Dans la racine vous trouvez plusieurs "boîtes".
![arborescence](https://image.jimcdn.com/app/cms/image/transf/dimension=1920x400:format=jpg/path/s2bf1aa8287716b07/image/ic069251148aebd24/version/1522921075/image.jpg)
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`
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
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-numérique_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.
Récapitulatif :
- pas de caractères spéciaux
- pas d'espaces
- extension
- nom parlant
- camelCase
- exemples : `2019-01-11notesEDN6102marcelloVitaliRosati.md`
[pour aller plus loin](http://ptaff.ca/blogue/2008/06/29/les_3_rgles_dor_pour_nommer_un_fichier/).
### Versionnage
## Formats de document
Le format d'un document déclare les principes de structuration du document.
On distinguera deux catégories de formats :
1. **Formats propriétaires** : doc, docx, pdf, indd, rtf, kindle, etc.
- appartiennent à des entités privés
- conditionnent les pratiques
- posent des problèmes de perennité
- exigences commerciales avant les exigences de recherche
- peuvent être ouverts (exemple du format pdf)
2. **Formats libres** : txt, HTML, XML, TeX, OpenDocument, EPUB, Markdown, etc.
- appartiennent à la communauté, ce qui favorise la perennité
- sont standards, ce qui favorise la perennité
- sont rédéfinis par les pratiques
- exigences de recherche en premier !
## Chaînes éditoriales
À nouveau, on distingue :
- des chaines basées sur des formats propriétaires : de [Microsoft Word](https://fr.wikipedia.org/wiki/Microsoft_Word) à [Adobe InDesign](https://fr.wikipedia.org/wiki/Adobe_InDesign) par exemple.
- des chaines basées sur des formats libres et standards : [XML](https://fr.wikipedia.org/wiki/Extensible_Markup_Language), [TeX](https://fr.wikipedia.org/wiki/TeX), [Markdown](https://fr.wikipedia.org/wiki/Markdown), etc.
[Markdown](https://daringfireball.net/projects/Markdown/license) (`.md`) est un format de plus en plus utilisé comme format pivot dans les chaines de publication car il permet une édition structurée très simple capable de produire à peu près tous les formats.
Remarque: ce cours est édité en Markdown (cliquez sur ![display source](./media/displaySource.png) pour voir la source).
Getty, O'Reilly sont deux exemples de chaines de publication basées sur des formats de markup simple (respectivement Markdown et AsciiDoc). Pour en savoir plus, voir [le mémoire d'Antoine Fauchié](http://memoire.quaternum.net/).
Dans la prochaine partie, nous expérimenterons la chaîne _Stylo_, basée sur Markdown comme format pivot.
## Edition savante
Exigences particulières du secteur de l'édition savante.
Enjeu principal de l'édition savante, c'est la structuration du document :
- choisir des formats qui permettent d'expliciter précisément la fonction de chaque élément du document (titre, citation, métadonnées, références bibliographiques, etc.)
Chaine markdown particulièrement adapté pour des contenus basés sur le texte.
### Contenus et Métadonnées
### Bibliographie
Quelques ressources :
- [Qu'est-ce que Zotéro ?](http://editorialisation.org/ediwiki/index.php?title=Zotero)
- [Comment installer et utiliser Zotéro ?](http://www.bib.umontreal.ca/lgb/Zotero/tutoriel/1-installer-zotero.htm)
- [Comment importer rapidement une bibliographie vers Zotéro ?](http://www.youtube.com/watch?v=S-f3J9LOqdQ)
---
Voir la suite [[02_stylo](./02_stylo.md)]
parcours/02_stylo.md 0 → 100644
View file @ 7ac98780
# Exercice 1 : Stylo
## Présentation de l'outil
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).
### Chaine de publication
![Chaine de publication Stylo](./media/chaine_stylo_sp.png)
## Fonctionnalités
L'environnement de travail de Stylo intègre une chaîne éditoriale complète basée sur [Pandoc](http://pandoc.org/) et outillée des modules suivants :
- **un éditeur de métadonnées**
- **un versionnage**
- **une gestion de la bibliographie**
- **différents formats exports** : HTML5, XML (TEI, Erudit), pdf...
- **l'annotation**
- **le partage de document**
### Édition
Un article dans Stylo est composé par trois éléments distincts :
- un corps de texte
- des métadonnées
- une bibliographie structurée
![Stylo_3elements](./media/stylo_3f_marqued.png)
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
![Stylo_Modules](./media/stylo_fullopen_marqued.png)
## Exercice
### Prise en main
Après vous être créé un compte sur [stylo.ecrituresnumeriques.ca](http://stylo.ecrituresnumeriques.ca), connectez-vous à Stylo. La première interface liste les documents que vous [n']avez [pas encore] créé.
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
À é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
Vous pouvez à tout moment visualiser un rendu du document en cours d'édition avec le bouton **[Annotate]**.
### Edition d'un article
L'exercice va consister à éditer un article simple à l'aide de Stylo dans le format Markdown.
- Article source : «Stratégie anti-pauvreté» de Niels Planel [sur Sens Public](http://sens-public.org/article1359.html).
**Consignes :**
1. créer un nouveau document dans Stylo
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 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 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))
Les deux références utilisés en bibtex :
```bibtex
@book{castel1995metamorphoses,
title={Les m{\'e}tamorphoses de la question sociale},
author={Castel, Robert},
year={1995},
publisher={Paris, Fayard}
}
```
```bibtex
@article{hinton2016war,
title={From the War on Poverty to the War on Crime: The Making of Mass Incarceration in America},
author={Hinton, Elizabeth},
year={2016},
publisher={Harvard University Press, Cambridge, MA}
}
```
## Exports de Stylo
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)
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.
|bouton|fonction|
|:-:|:--|
|![[preview]](uploads/images/preview.png) | pour ouvrir l'aperçu html de l'article |
|![[HTML]](uploads/images/html.png) | pour télécharger une version html prête à mettre en ligne |
|![[XML (erudit])](uploads/images/xml.png) | pour prévisualiser une version xml au schéma Erudit |
|![[ZIP]](uploads/images/zip.png) | pour télécharger les trois composants de l'article : métadonnées (.yaml), bibliographie (.bib), corps de texte (.md) |
Au prochain exercice, nous allons utiliser les sources du `.zip` pour personnaliser la production de document.
---
Voir la suite [[03_outils](./03_outils.md)]
parcours/03_outils.md 0 → 100644
View file @ 7ac98780
**Sommaire**
<!-- TOC depthFrom:1 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
- [Quelques outils indispensables](#quelques-outils-indispensables)
- [un éditeur de texte/code](#un-diteur-de-textecode)
- [un convertisseur de format](#un-convertisseur-de-format)
- [un compte sur framagit.org](#un-compte-sur-framagitorg)
- [un gestionnaire de version : Git](#un-gestionnaire-de-version-git)
- [LaTeX](#latex)
- [Prise en main de Git](#prise-en-main-de-git)
- [Exercice - créer son premier répertoire](#exercice-crer-son-premier-rpertoire)
- [Prise en main de Pandoc](#prise-en-main-de-pandoc)
- [Exercice de conversion](#exercice-de-conversion)
- [Les templates dans Pandoc](#les-templates-dans-pandoc)
<!-- /TOC -->
# 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.
## 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).
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).
## 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.
Nous utilisons [Pandoc](https://pandoc.org) en ligne de commande.
- Installation de pandoc : https://pandoc.org/installing.html
- Documentation à consulter en cas de problème, pour les cas particuliers : https://pandoc.org/MANUAL.html
Nous aurons aussi besoin de l'extension **pandoc-citeproc** pour gérer les références bibliographiques.
## 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.
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
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 :
- 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)
## LaTeX
LaTeX est un langage et un système de composition de documents.
Vous pouvez télécharger Latex [depuis le site officiel](https://www.latex-project.org/get/)
parcours/03b_git.md 0 → 100644
View file @ 7ac98780
# Prise en main de Git
Git est un outil de versionning 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.
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 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 diff` : présente les changements de chaque fichier modifié.
- `git log` : présente une liste de commit. C'est l'état du registre.
## 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.
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.
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..
6. Git télécharge le répertoire et crée un nouveau répertoire [monprenom] dans le répertoire gitlab. Naviguez dans ce nouveau répertoire `cd monprenom`.
7. `ls` ou `ls -a` ou encore `ll` permet de lister tous les fichiers du répertoire. Pour le moment, il n'y a pas grand chose.
8. nous allons récupérer les sources de votre article édité sur Stylo en lançant un export ZIP. Une fois le dossier compressé téléchargé, décompressez le et copier les trois fichiers dans votre répertoire [monprenom]. Renommez les fichiers selon une bonne nomenclature.
9. nous pouvons maintenant ajouter ces fichiers à l'index Git : `git add .`, puis générer un premier commit pour ajouter ces fichiers au registre : `git commit -m "initialisation de l'article"`. On peut vérifier le registre avec `git log`.
10. essayons maintenant de synchroniser les modifications en local avec le serveur : `git push`. Sur le site de framagit, votre répertoire est maintenant mis-à-jour.
Vous êtes maintenant en mesure de faire des modifications et de les synchroniser avec le serveur framagit. Pendant le travail d'édition, vous pouvez régulièrement valider les modifications et synchroniser avec le serveur. Il suffit pour cela de répéter les opérations 9 et 10 :
- `git add .`
- `git commit -m "message"`
- `git push`
parcours/04_edition.md 0 → 100644
View file @ 7ac98780
# Edition avec Pandoc
## Prise en main de Pandoc
Pandoc permet de convertir des documents numériques en ligne de commande.
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.
- 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.
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.
Quelques options de la commande Pandoc à connaître :
- `--standalone` (produit un document complet incluant les métadonnées)
- `--bibliography=references.bib` (spécifie un fichier de références bibliographiques)
- `--template=mytemplate.html` (spécifie un modèle)
- `--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 :
pandoc -f docx -t markdown --extract-media=./ --atx-headers fichier.docx -o fichier.md
- vous souhaitez convertir en HTML un document en Markdown comprenant des références bibliographiques (references.bib) :
pandoc --standalone --ascii --bibliography=references.bib -f markdown -t html fichier.md -o fichier.html
## Exercice de conversion
- Export simple: (génère du html correctement formé, mais un document incomplet)
pandoc -f markdown -t html monfichier.md -o export.html
- Export complet "standalone": (génère un document html complet)
pandoc --standalone -f markdown -t html monfichier.md -o export.html
- Ajout des métadonnées en en-tête de fichier. Vous pouvez ajouter les lignes suivantes en entête de fichier markdown pour associer à votre document les principales métadonnées.
```yaml
---
title:
subtitle:
date:
author:
- Aristotle
- Peter Abelard
abstract:
keywords:
bibliography:
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 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`) :
pandoc --standalone -f markdown -t html monfichier.md metadonnees.yaml -o export.html
- Export en prenant en compte le fichier de bibliographie avec l'option `--bibliography=FILE`:
pandoc --standalone --bibliography=monfichier.bib --filter pandoc-citeproc -f markdown -t html monfichier.md -o export.html
- Vous pouvez aussi déclarer le fichier de référence une fois pour toute dans l'en-tête yaml :
```yaml
---
bibliography: monfichier.bib
---
```
et lancer la commande précédente (sans l'option `---bibliography=monfichier.bib`)
pandoc --standalone --filter pandoc-citeproc -f markdown -t html monfichier.md -o export.html
- Pour transformer les appels de références en hyperliens, ajouter une ligne dans l'en-tête yaml :
```yaml
---
link-citations: true
---
```
- Ajout d'une table des matières avec l'option `--toc`:
pandoc --standalone --toc --filter pandoc-citeproc -f markdown -t latex monfichier.md -o export.pdf
- Export en XML TEI avec l'option `-t tei`:
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`)
pandoc -f odt -t markdown --extract-media=./ --atx-headers export.odt -o exportMD.md
## Les templates dans Pandoc
Pandoc utilise des templates par défaut pour chacun des formats de sorties. Le principe du template est simple: Pandoc remplace les variables du template par les valeurs déclarées dans les métadonnées présentes soit dans un fichier yaml, soit dans l'entête yaml du fichier markdown.
Soit :
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.
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.
Pour créer un template personnalisé, commençons par récupérer le template par défaut d'un format (ici HTML) dans un fichier `montemplate.html`.
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).
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.
Dans les métadonnées yaml, nous allons ajouter la clé/valeur en ajoutant une simple ligne :
```yaml
image: auteur.jpg
```
Puis dans le template, nous pouvons ajouter une balise `<img>` :
`$if(image)$
<img src="$image$" width="30%"/>
$endif$
`
Enfin, pour que Pandoc prenne en compte le nouveau template, vous devez ajouter l'option `--template=FILE`, soit la commande complète suivante :
pandoc --standalone --filter pandoc-citeproc --template=montemplate.html -f markdown -t html monfichier.md metadata.yaml -o export_2.html
parcours/05_livre.md 0 → 100644
View file @ 7ac98780
# Initialisation de l'ouvrage
Nous allons préparer vos sources pour une édition en Markdown.
Dans votre répertoire de travail, créer un sous-dossier `ouvrage` et déplacez y votre.vos fichier.s source.s.
En ligne de commande :
mkdir ouvrage
cd ouvrage
cp /chemin/sources/monfichier.docx ./
Selon votre format d'entrée (docx, odt, html, autre ?), lancer la commande Pandoc pour convertir votre document en Markdown, en remplaçant `docx` par votre format :
pandoc -f docx -t markdown --extract-media=./ --atx-headers monfichier.docx -o monfichier.md
Vous pouvez maintenant :
1. éditer votre contenu en Markdown
2. produire une bibliographie structurée en bibtex
3. préparer les métadonnées génériques dans un fichier séparé (`monfichier.yaml`)
## Cas particulier
### Format d'entrée non reconnu (Pdf)
Certains formats ne sont pas reconnus en entrée par Pandoc, comme le Pdf. Dans ce cas, utiliser un convertisseur en ligne (vous pouvez faire une requête "pdf 2 text" dans votre moteur de recherche).
### Encodage du texte