201 lines
7.5 KiB
Markdown
201 lines
7.5 KiB
Markdown
---
|
||
title: Un modèle pour la BUNIGE
|
||
date: Printemps 2023
|
||
creation_date: 2023-04-21T11:30:49+02:00
|
||
id: 20230421113057
|
||
author:
|
||
- Igor Milhit^[Uni CMU]
|
||
- Jane Doe^[Uni MAIL]
|
||
logo:
|
||
- ./static/pagedjs-logo.svg
|
||
- ./static/markdown-logo.svg
|
||
lang: fr
|
||
tags: [example, markdown, pagedjs]
|
||
bibliography: ./references.bib
|
||
csl: ../heg-iso-690.csl
|
||
link-citations: true
|
||
nocite: |
|
||
@*
|
||
toc-title: Table des matières
|
||
---
|
||
|
||
## Objectifs
|
||
|
||
Au terme de cet atelier, vous serez en mesure de :
|
||
|
||
- Générer un fichier PDF en utilisant le modèle.
|
||
- Convertir les sources en markdown en HTML afin de l'afficher dans un
|
||
navigateur web.
|
||
- Modifier les règles de styles pour adapter le modèle.
|
||
|
||
|
||
|
||
:::{#licence}
|
||
 \
|
||
[CC BY-SA 4.0][cc-by-sa] --- [Sources][sources]
|
||
:::
|
||
|
||
[cc-by-sa]: https://creativecommons.org/licenses/by-sa/4.0/deed.fr "Texte de la licence en français"
|
||
[sources]: https://git.milhit.ch/igor/bunige-pagedjs-template
|
||
|
||
## Principes généraux {#first-section}
|
||
|
||
L'idée de base est de rédiger le contenu du document dans un fichier markdown.
|
||
Puis d'obtenir un fichier PDF mis en forme selon les modèles utilisé par la
|
||
bibliothèque de l'UNIGE pour ses formations.
|
||
|
||
Pour y parvenir, plusieurs méthode sont possibles. Par exemple, le document que
|
||
vous lisez est rédigé dans le fichier `example.md`, situé dans le dossier
|
||
`/example/example.md` du projet [*bunige-pagedjs-template*][1]. Ce fichier
|
||
« source » est converti par `pandoc` au format HTML. Puis, ce fichier est à son
|
||
tour converti en PDF au moyen de `pagedjs`.
|
||
|
||
Il est parfaitement possible de convertir directement le fichier markdown en
|
||
PDF au moyen de `pandoc`. Mais cela suppose avoir une distribution LaTeX
|
||
installée. De plus, pour obtenir un document correspondant à la charte de
|
||
l'UNIGE, cela demande d'être en mesure de modifier les modèles LaTeX utilisé
|
||
par `pandoc`. La section suivante tente d'expliquer en quoi `Paged.js` facilite
|
||
cette mise en forme.
|
||
|
||
### Paged.js
|
||
|
||
> Paged.js is a free and open source JavaScript library that paginates content
|
||
> in the browser to create PDF output from any HTML content. This means you can
|
||
> design works for print (eg. books) using HTML and CSS! [@paged.jsPagedJs]
|
||
|
||
Concrètement, cela permet d'afficher un document HTML dans le navigateur, mais
|
||
découpé en page comme le serait un document imprimé, par exemple un livre.
|
||
|
||
|
||
|
||
Comme il s'agit d'un simple document HTML, il peut être mis en forme au moyen
|
||
d'une feuille de style CSS, comme pour n'importe quelle page web. Selon ses
|
||
compétences, on peut préférer mettre en forme un PDF de cette manière,
|
||
notamment grâce à l'inspecteur du navigateur, permettant de tester directement
|
||
des modifications.
|
||
|
||
Pour obtenir un document proche des modèles utilisés par la bibliothèque pour
|
||
ses documents de formation, les règles ont été placées dans le fichier
|
||
`style.css` à la racine du projet.
|
||
|
||
Écrire le fichier HTML directement permet une grande souplesse. Mais la
|
||
rédaction d'un texte au format HTML n'est pas spécialement pratique. Pour cela,
|
||
le format markdown semble préférable. Il suffit de comparer les extraits
|
||
suivants, d'abord en markdown, puis en HTML :
|
||
|
||
```markdown
|
||
### Paged.js
|
||
|
||
> Paged.js is a free and open source JavaScript library that paginates
|
||
> content in the browser to create PDF output from any HTML content.
|
||
> This means you can design works for print (eg. books) using HTML and
|
||
> CSS! [@paged.jsPagedJs]
|
||
|
||
Concrètement, cela permet d'afficher un document HTML dans le
|
||
navigateur, mais découpé en page comme le serait un document
|
||
imprimé, par exemple un livre.
|
||
|
||
|
||
```
|
||
|
||
```html
|
||
<h3 id="paged.js">Paged.js</h3>
|
||
<blockquote>
|
||
<p>Paged.js is a free and open source JavaScript library that paginates
|
||
content in the browser to create PDF output from any HTML content. This
|
||
means you can design works for print (eg. books) using HTML and CSS!
|
||
<span class="citation" data-cites="paged.jsPagedJs">
|
||
(<a href="#ref-paged.jsPagedJs"
|
||
role="doc-biblioref">Paged.js [sans date]</a>)
|
||
</span></p>
|
||
</blockquote>
|
||
<p>Concrètement, cela permet d’afficher un document HTML dans le
|
||
navigateur, mais découpé en page comme le serait un document imprimé,
|
||
par exemple un livre.</p>
|
||
<figure>
|
||
<img src="./static/pagedjs-in-browser.png"
|
||
alt="Pagination d’un document dans le navigateur à l’aide de Paged.js" />
|
||
<figcaption aria-hidden="true">
|
||
Document paginé dans le navigateur
|
||
</figcaption>
|
||
</figure>
|
||
```
|
||
|
||
## Police
|
||
|
||
Pour que la police *TheSans* puisse s'appliquer correctement, elle doit être
|
||
installée sur votre système d'exploitation. Malheureusement, elle n'est pas
|
||
publiée avec une licence libre, ce qui en réduit l'usage. Les polices de
|
||
remplacement sont dans l'ordre *Open Sans*, *Arial*, *Helvetica*, ou la police
|
||
*sans-serif* par défaut de votre système ou de votre navigateur.
|
||
|
||
La police peut être facilement configurable au moyen du sélecteur `body` dans
|
||
le fichier `style.css` (règle déjà existante, dans la section *Définitions
|
||
globales*).
|
||
|
||
## Titres
|
||
|
||
Il y a une particularité avec les titres, qui découlent de l'usage de
|
||
`pandoc`. La première et qu'il est possible de définir l'attribut `id=` des
|
||
titres avec la syntaxe suivante :
|
||
|
||
```markdown
|
||
## Titre {#identifiant}
|
||
```
|
||
|
||
Le *template* en fait usage pour obtenir l'identifiant `first-section` pour le
|
||
premier titre du contenu, celui qui vient immédiatement après les [objectifs].
|
||
Ainsi, un sélecteur unique est disponible pour appliquer un saut de page à ce
|
||
titre, quel que soit son texte. Une logique similaire est appliquée au titre de
|
||
la bibliographie (`bibliography`).
|
||
|
||
## Citation
|
||
|
||
> Tout d’abord un bon éditeur est un éditeur avec coloration syntaxique. Avec
|
||
> cela, les éléments importants de la syntaxe Markdown, ainsi que les titres,
|
||
> les mots en italique, etc., apparaissent en évidence. Ensuite, un bon éditeur
|
||
> de texte est presque entièrement configurable : il vous sera très bénéfique
|
||
> de configurer selon vos goûts le thème de la coloration syntaxique et de
|
||
> l’interface, ainsi que la police. Cela vous assurera surtout un confort
|
||
> d’écriture. [@masuttiRedigerManipulerDocuments2019]
|
||
|
||
## Tableaux
|
||
|
||
Voici un exemple de table avec une légende et une numérotation automatique des
|
||
tableaux, comme c'est le cas pour les images (figures).
|
||
|
||
| ID | Nom | Prénom | Adresse |
|
||
|:---:| ------- | ------ | ---------------- |
|
||
| 1 | Dupont | Jean | Ch. de la Lune 1 |
|
||
| 2 | Dupond | Pierre | Ch. de la Lune 2 |
|
||
| 3 | Schmidt | Mark | Mondweg 3 |
|
||
|
||
Table: Exemple de tableau.
|
||
|
||
L'exemple suivant est directement copié-collé depuis la [documentation
|
||
officielle][2] de `pandoc`. Il montre que `pandoc` permet des extensions de la
|
||
syntaxe markdown.
|
||
|
||
-------------------------------------------------------------
|
||
Centered Default Right Left
|
||
Header Aligned Aligned Aligned
|
||
----------- ------- --------------- -------------------------
|
||
First row 12.0 Example of a row that
|
||
spans multiple lines.
|
||
|
||
Second row 5.0 Here's another one. Note
|
||
the blank line between
|
||
rows.
|
||
-------------------------------------------------------------
|
||
|
||
Table: Here's the caption. It, too, may span
|
||
multiple lines.
|
||
|
||
|
||
## Bibliographie {#bibliography}
|
||
|
||
<!-- références -->
|
||
|
||
[1]: https://git.milhit.ch/igor/bunige-pagedjs-template
|
||
[2]: https://pandoc.org/MANUAL#extension-multiline_tables
|