Commit e859d31a authored by sauret's avatar sauret

update 03_outils

parent f3fbee06
......@@ -23,8 +23,8 @@ _pause déjeuner_
3. Outils ([parcours/03_outils](./parcours/03_outils.md))
- Installation des outils
- Versionnage avec git
- Conversion avec pandoc
- prise en main de git
- prise en main de pandoc
_pause_
......
......@@ -17,4 +17,4 @@
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.md)
Voir la suite [[01_theorie](./01_theorie.md)]
......@@ -76,7 +76,7 @@ On distinguera deux catégories de formats :
Remarque: ce cours est édité en Markdown (cliquez sur ![display source](./media/displaySource.png) pour voir la source).
Getty, O'Reilly ou Distill sont trois exemples de chaines de publication basées sur Markdown (voir [les travaux d'Antoine Fauchié](http://memoire.quaternum.net/)).
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.
......@@ -93,4 +93,4 @@ Quelques ressources :
- [Comment importer rapidement une bibliographie vers Zotéro ?](http://www.youtube.com/watch?v=S-f3J9LOqdQ)
---
[un peu de pratique](./02_stylo.md)
Voir la suite [[02_stylo](./02_stylo.md)]
......@@ -4,7 +4,13 @@
Stylo est un éditeur de texte simplifiant la rédaction et l'édition de documents scientifiques en sciences humaines et sociales.
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/), [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 :
......@@ -15,6 +21,7 @@ L'environnement de travail de Stylo intègre une chaîne éditoriale complète b
- **l'annotation**
- **le partage de document**
### Édition
Un article dans Stylo est composé par trois éléments distincts :
......@@ -24,8 +31,6 @@ Un article dans Stylo est composé par trois éléments distincts :
![Stylo_3elements](./media/stylo_3f_marqued.png)
### Édition
L'environnement d'édition est composé de 5 modules :
1. au centre : l'espace d'écriture, consacré au corps de texte de l'article
......@@ -85,7 +90,25 @@ L'exercice va consister à éditer un article simple à l'aide de Stylo dans le
- 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](./09_ressources.md))
- 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))
## 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.
3. sorties par défaut Stylo (15min)
---
Voir la suite [[03_outils](./03_outils.md)]
# Quelques outils pour travailler
# Quelques outils indispensables
Pour l'atelier vous aurez besoin d'amener votre propre ordinateur (indispensable) et d'installer quelques outils pour travailler ensemble.
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 (indispensable)
## 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 les syntaxes 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).
## un compte sur framagit.org (indispensable)
## un convertisseur de format
Sur [Framagit.org](https://framagit.org/users/sign_in?redirect_to_referer=yes), créez vous un compte. Cela vous sera utile pour :
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.
......@@ -21,18 +33,90 @@ 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 (indispensable)
## un gestionnaire de version : Git
Le gestionnaire de version git va vous permettre de communiquer votre code à Framagit. Nous verrons ensemble comment l'utiliser.
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)
- installer Git avec homebrew : `brew install git`
- Windows : [installez Git pour Windows](https://git-scm.com/downloads)
## LaTeX (indispensable)
## 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/)
# 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`
# 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`
- ``
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 un document en Markdown comprenant des références bibliographiques :
pandoc --standalone --ascii --filter pandoc-citeproc --bibliography=references.bib -f markdown -t html fichier.md -o fichier.html
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