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

mise à jour depuis formation edn6102 H2020 sur framagit

parent a0b0468d
......@@ -32,7 +32,7 @@ En premier lieu, veuillez [vous créer un compte sur Huma-Num](https://humanid.h
5. Exercice 2 - édition ([parcours/04_edition](./parcours/04_edition.md))
- Prise en main de Pandoc
- Exercice de conversion
- Templating
- Templating ([parcours/04_templating](./parcours/04_templating.md))
## Editer un livre
......
......@@ -10,7 +10,7 @@ L'édition savante impose des exigences particulières :
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.)
→ 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.)
## Formats de document
......@@ -20,17 +20,16 @@ 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)
- 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 !
- 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 !
Ne pas confondre le standard et l'outil !
......@@ -58,7 +57,7 @@ Quelques ressources :
[Markdown](https://daringfireball.net/projects/markdown) (`.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).
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/).
......
......@@ -8,7 +8,7 @@ Vous pouvez consulter [la documentation](http://stylo-doc.ecrituresnumeriques.ca
### Chaîne de publication
![Chaîne de publication Stylo](./media/chaine_stylo_sp.png)
![Chaîne de publication Stylo](../media/chaine_stylo_sp.png)
## Fonctionnalités
......@@ -29,7 +29,7 @@ Un article dans Stylo est composé de trois éléments distincts :
- des métadonnées
- une bibliographie structurée
![Stylo_3elements](./media/stylo_3f_marqued.png)
![Stylo_3elements](../media/stylo_3f_marqued.png)
L'environnement d'édition est composé de 5 modules :
......@@ -41,7 +41,7 @@ L'environnement d'édition est composé de 5 modules :
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)
![Stylo_Modules](../media/stylo_fullopen_marqued.png)
## Exercice
......@@ -118,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 citation : ![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.
......@@ -130,8 +130,7 @@ Il est possible de choisir entre deux styles de citation : ![moduleexport](./med
|![[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) |
Dans l'étape [[parcours/04_edition](./parcours/04_edition.md)], nous étudions comment utiliser les sources du `.zip` pour personnaliser la production de document.
Dans l'étape [[parcours/04_edition](./parcours/04_edition.md)], nous allons utiliser les sources du `.zip` pour personnaliser la production de document.
---
Voir la suite [[02_stylo_memoire](./02_stylo_memoire.md)] ou passer aux [[03_outils](./03_outils.md)]
......@@ -45,7 +45,7 @@ Sur [framagit.org](https://framagit.org/users/sign_in?redirect_to_referer=yes),
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/marviro/tutorielmdpandoc/wikis/home) de ce répertoire.
3. [participer au wiki](https://gitlab.huma-num.fr/ecrinum/manuels/tutoriel-markdown-pandoc/-/wikis/home) de ce répertoire.
Cliquez sur le bouton [Request Access] pour demander un accès au répertoire.
......@@ -61,6 +61,8 @@ Le gestionnaire de version Git va vous permettre de communiquer votre code à fr
- installer Git avec homebrew : `brew install git`
- Windows : [installez Git pour Windows](https://git-scm.com/downloads)
voir quelques notions du protocole git [[parcours/03b_git](parcours/03b_git.md)]
## LaTeX
LaTeX est un langage et un système de composition de documents.
......
......@@ -29,9 +29,9 @@ Vous allez créer un premier répertoire. Allons-y pas à pas :
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`.
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].
3. dans votre navigateur, allez sur votre compte Framagit 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..
5. dans le terminal, écrivez la commande `git clone ` puis coller l'url copiée, et lancez la commande complète, par exemple : `git clone https://framagit.org/monprenom/monprojet.git`
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.
......
......@@ -59,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) 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 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`) :
......
# Templating avec Pandoc
1. Créer un répertoire de test :
- `cd gitlab/monprenom/`
- `mkdir test`
2. Créer les fichier test.md test.yaml
- sur atom créer un nouveau fichier et sauvegarder dans le dossier test
3. générer le template html par défaut
- `pandoc -D html > templatehtml.html`
- explication : la première partie de la commande `pandoc -D html` "affiche" le template dans le terminal. La seconde partie de la commande `> fichier.html` "écrit" ce qui est affiché dans un nouveau fichier.
4. faire des tests :
- écrire du markdown dans le md
- écrire des métadonnées dans le yaml
- ajouter divers couples `key: value`, par exemple : `author: nicolas`
- vérifier quels sont les "clés" (ou "variables") comprises par Pandoc (voir [la documentation de pandoc](https://pandoc.org/MANUAL.html#variables))
- créer de nouvelles variables dans le yaml, et appliquez les dans votre template (`templatehtml.html`)
- jouer avec les conversions :
- Simple sans yaml : `pandoc -f markdown -t html test.md -o test.html`
- Complet avec yaml : `pandoc --standalone -f markdown -t html test.md test.yaml -o testyaml.html`
- Complet avec table des matières : `pandoc --standalone --toc -f markdown -t html test.md test.yaml -o testyaml.html`
- Complet avec son propre template : `pandoc --standalone --template=templatehtml.html -f markdown -t html test.md test.yaml -o testyaml.html`
5. mettre en forme :
Pour mettre en forme, on doit spécifier à pandoc quel fichier CSS on doit utiliser. Copier votre fichier `pandoc.css` dans le dossier `test`. Puis vous avez 2 options :
1. spécifier dans le yaml en ajoutant la clé/valeur `css: pandoc.css`
2. spécifier dans la commande pandoc : `pandoc --standalone --css:pandoc.css etc......`
## Quelques astuces
Pour ajouter en bibliographie tous les éléments du fichier `.bib`, même ceux qui ne sont pas cités dans le corps de texte, ajouter au yaml la ligne : `nocite: '@*'`
Comment gérer les espaces insécables en markdown :
- en insérant le code ASCII : `&nbsp` pour "Non-Breaking SPace"
- pandoc comprend aussi la syntaxe suivante : `\ ` (backslash + espace). Par exemple: `Allô\ ?`
- sur Stylo, la combinaison `CTRL+SHIFT+SPACE` ajoutera un espace insécable.
# Production du LaTeX
# Production du PDF (via LaTeX)
LaTeX est un logiciel qui permet de produire des textes mis en page de haute qualité à des fins d'impression.
......@@ -222,7 +222,7 @@ Quelques cas particuliers à traiter :
### Workflow #2 - personnaliser le template LaTeX
Il est aussi possible de créer son propre template LaTeX et de l'utiliser à la place du template par défaut. Cela permettra notamment de choisir en amont le gabarit de l'ouvrage que l'on cherche à produire.
Il est aussi possible de créer son propre template LaTeX pour Pandoc et de l'utiliser à la place du template par défaut. Cela permettra notamment de choisir en amont le gabarit de l'ouvrage que l'on cherche à produire.
Pour visualiser le template Latex par défaut :
......
# Production du PDF (via pagedJS)
## Qu'est ce que PagedJS ?
1. Une initiative de [Paged Media](https://pagedmedia.org) :
> "A blog which advocates for innovative approaches to making books in browsers."
2. Une bibliothèque JavaScript open source qui pagine le contenu des navigateurs. Cette bibliothèque permet de supporter l'utilisation du CSS pour l'impression dans les navigateurs web récents.
Autrement dit, avec PagedJS, il est possible de mettre en page un ouvrage au format HTML en utilisant uniquement des feuilles de style CSS.
## Comment l'utiliser ?
1. Éditer votre document/ouvrage en html
2. Ajouter au document le script [ressources/paged.polyfill.js](../ressources/paged.polyfill.js) :
a. Copier le fichier du script à proximité de votre source html
b. insérer dans le fichier HTML le code suivant : `<script src="paged.polyfill.js"></script>`
3. Ajouter au document la feuille de style CSS [ressources/interface-0.1.css](../ressources/interface-0.1.css)
4. lancer un serveur sur votre répertoire :
- soit : `python3 -m http.server 1337`
- soit : `python -m SimpleHTTPServer 1337`
- soit sur windows : `py -m http.server 1337`
5. Enfin, ouvrir le navigateur *Chrome* ou *Chromium*, et visitez la page http://localhost::1337
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