diff --git a/.gitignore b/.gitignore
index d2bd40f..6d0b8f5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
example.html
example.pdf
test.*
+release/
diff --git a/README.md b/README.md
index 4312344..1d0381d 100644
--- a/README.md
+++ b/README.md
@@ -5,19 +5,36 @@ id: 20230421111912
tags: [modèle, pagedjs, PDF, BUNIGE]
---
-# [Un modèle *pagedjs* pour la BUNIGE][projet]
+# [Un modèle *pagedjs* pour la BUNIGE][1]
## Licence
-Ce projet est sous [licence MIT][licence].
+Ce projet est sous [licence MIT][2].
## Description
Ce projet est un modèle et une mise en forme pour produire un PDF suivant la
-charte de la [Bibliothèque de l'Université de Genève][bunige].
+charte de la [Bibliothèque de l'Université de Genève][3].
-Il a pour objectif d'être ajouté rapidement à un projet utilisant
-[paged.js][pagedjs] pour générer des PDF à partir d'un contenu en markdown.
+Il a pour objectif d'être ajouté rapidement à un projet utilisant [paged.js][4]
+pour générer des PDF à partir d'un contenu en markdown.
+
+## Usage
+
+Une solution est de télécharger les fichiers et répertoires suivants à la
+racine de votre propre projet :
+
+- `static/`.
+- `style.css`.
+- `template.html`.
+- `interface.css`.
+- `heg-iso-690.csl`.
+
+Vous pouvez faire ces téléchargement à la main, ou télécharger le fichier
+`.zip` de la [publication de version][7].
+
+Une autre méthode est de cloner le projet et de rédiger votre document au sein
+de celui-ci.
## Structure du répertoire
@@ -26,9 +43,11 @@ Il a pour objectif d'être ajouté rapidement à un projet utilisant
- Le modèle lui-même : `template.html`.
- La feuille de style qui rend possible l'interface web pour la
prévisualisation du document au format HTML : `interface.css` (fichier
- faisant partie du projet [paged.js][pagedjs]).
+ faisant partie du projet [paged.js][4] : [interface.css][6]).
- Le fichier de style bibliographique qui fait partie à part entière du modèle,
- car il est la norme utilisée par la charte : `heg-iso-690.csl`.
+ car il est la norme utilisée par la charte : `heg-iso-690.csl`. Il est
+ extrait du répertoire des styles `.csl` :
+ [haute-ecole-de-gestion-de-geneve-iso-690.csl][5].
Dans le dossier `example` se trouvent les sources pour pouvoir donner un
exemple :
@@ -37,7 +56,7 @@ exemple :
- Une liste de références bibliographiques au format BibLaTeX :
`references.bib`.
-## Pré-requis
+## Prérequis
- `pandoc`.
- `pagedjc-cli` (`npm install -g puppeteer pagedjs pagedjs-cli`).
@@ -49,22 +68,64 @@ Lancer les commandes depuis le répertoire `./example`.
Pour générer le fichier HTML a visualiser dans le navigateur :
```bash
-pandoc --standalone --pdf-engine=pagedjs-cli \
+pandoc --citeproc \
--template=../template.html --css=../style.css \
- --toc --toc-depth=2 --citeproc \
+ --toc --toc-depth=2 \
--to=html --output=example.html example.md
```
-Pour générer directement le PDF :
+- `--citeproc` assure que les références bibliographiques soient traitées.
+- `--template=` et `--css=` définissent le modèle et les règles de style à
+ utiliser.
+- `--toc` et `toc-depth=2` génèrent la table des matière en se limitant au 2e
+ niveau.
+
+Puis lancer un serveur web à la racine du projet (par exemple avec `python -m
+http.server`), et ouvrir le fichier HTML généré avec Chromium (ou Chrome) pour
+pouvoir l'imprimer au format PDF.
+
+Pour générer directement le PDF, en utilisant `pagedjs` au moyen de `pandoc` :
```bash
-pandoc --standalone --citeproc \
+pandoc --citeproc \
--to=pdf --pdf-engine=pagedjs-cli \
- --css=../style.css --toc --toc-depth=2 \
+ --css=../style.css \
+ --toc --toc-depth=2 \
--output=example.pdf example.md
```
-[projet]: ./
-[licence]: ./LICENSE
-[bunige]: https://www.unige.ch/biblio/fr/ "Site officiel de la Bibliothèque de l'Université de Genève"
-[pagedjs]: https://pagedjs.org/
+- `--pdf-engine=` impose `pagedjs` pour la conversion en PDF.
+- Ici le `template` ne doit pas être utilisé, mais la feuille de style doit
+ l'être.
+
+Pour générer le PDF en utilisant directement `pagedjs` :
+
+```bash
+pandoc --citeproc \
+ --to=html --toc --toc-depth=2 \
+ --template=../template.html --css=../style.css \
+ --output example.html example.md \
+ && pagedjs-cli example.html --style ../style.css --output example.pdf
+```
+
+**Attention !** Chacune de ces méthodes produit des différences. À vous de les
+observer et de choisir laquelle vous convient le mieux.
+
+## Rédaction du document
+
+Pour la rédaction du document, il est utile de se référer à la documentation de
+la syntaxe markdown, mais aussi à la documentation de `pandoc`. Quelques points
+sont données en exemples dans le fichier `example/example.md`, comme par
+exemple [La police][8] ou [Les titres][9].
+
+
+
+[1]: ./
+[2]: ./LICENSE
+[3]: https://www.unige.ch/biblio/fr/ "Site officiel de la Bibliothèque de l'Université de Genève"
+[4]: https://pagedjs.org/
+[5]: https://raw.githubusercontent.com/citation-style-language/styles/blob/master/haute-ecole-de-gestion-de-geneve-iso-690.csl
+[6]: https://gitlab.coko.foundation/pagedjs/interface-polyfill/-/raw/master/interface.css
+[7]: https://git.milhit.ch/igor/bunige-pagedjs-template/releases/latest
+[8]: ./example/example.md#police
+[9]: ./example/example.md#titres
diff --git a/example/example.md b/example/example.md
index 50942a2..3360774 100644
--- a/example/example.md
+++ b/example/example.md
@@ -13,8 +13,9 @@ lang: fr
tags: [example, markdown, pagedjs]
bibliography: ./references.bib
csl: ../heg-iso-690.csl
-nocite: "@*"
link-citations: true
+nocite: |
+ @*
toc-title: Table des matières
---
@@ -37,7 +38,163 @@ Au terme de cet atelier, vous serez en mesure de :
[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 {#1st-section}
+## Principes généraux {#first-section}
-## Bibliographie
+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
+
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.js [sans date])
+
+
+
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.
+
+
+
+ Document paginé dans le navigateur
+
+
+```
+
+## 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}
+
+
+
+[1]: https://git.milhit.ch/igor/bunige-pagedjs-template
+[2]: https://pandoc.org/MANUAL#extension-multiline_tables
diff --git a/example/references.bib b/example/references.bib
index 7e0903c..80f29a0 100644
--- a/example/references.bib
+++ b/example/references.bib
@@ -2,18 +2,19 @@
title = {Indirect Reference Intervals Using an {{R}} Pipeline.},
author = {Bunch, Dustin R.},
date = {2022-04},
- journaltitle = {J Mass Spectrom Adv Clin Lab},
+ journaltitle = {Journal of mass spectrometry and advances in the clinical lab},
+ shortjournal = {J Mass Spectrom Adv Clin Lab},
volume = {24},
eprint = {35252947},
eprinttype = {pmid},
pages = {22--30},
- location = {{Netherlands}},
+ location = {Netherlands},
issn = {2667-145X 2667-1468},
doi = {10.1016/j.jmsacl.2022.02.004},
abstract = {BACKGROUND: Indirect reference intervals require robust statistical approaches to separate the pathological and healthy values. This can be achieved with a data pipeline created in R, a freely available statistical programming language. METHODS: A data pipeline was created to ingest, partition, normalize, remove outliers, and identify reference intervals for testosterone (Testo; n ~=~7,207) and aspartate aminotransferase (AST; n ~=~5,882) using data sets from NHANES. RESULTS: The estimates for AST and Testo determined by this pipeline approximated current RIs. Care should be taken when using this pipeline as there are limitations that depend on the pathology of the analyte and the data set being used for RI estimation. CONCLUSIONS: R can be used to create a robust statistical reference interval pipeline.},
langid = {english},
pmcid = {PMC8889237},
- keywords = {ANOVA; Analysis of variance,AST; aspartate aminotransferase,CLSI; Clinical Laboratory Standards Institute,cmu,EHR; electronic health record,IFCC; International Federation of Clinical Chemistry and Laboratory Medicine,LC-MS/MS; Liquid chromatography tandem mass spectrometry,LIS; Laboratory informatics system,markdown,Mixtools,non lu,pubmed,R markdown,R markdown tutorial,Reference interval,RI; reference interval,SDI; Standard deviation index,SDR; Standard deviation ratio,Testo; Testosterone,TukeyHSD; Tukey multiple pairwise-comparisons,z5; Critical z-score},
+ keywords = {ANOVA Analysis of variance,AST aspartate aminotransferase,CLSI Clinical Laboratory Standards Institute,cmu,EHR electronic health record,IFCC International Federation of Clinical Chemistry and Laboratory Medicine,LC-MS/MS Liquid chromatography tandem mass spectrometry,LIS Laboratory informatics system,markdown,Mixtools,non lu,pubmed,R markdown,R markdown tutorial,Reference interval,RI reference interval,SDI Standard deviation index,SDR Standard deviation ratio,Testo Testosterone,TukeyHSD Tukey multiple pairwise-comparisons,z5 Critical z-score},
file = {/home/igor/Zotero/storage/YYP9JQTY/Bunch_2022_Indirect reference intervals using an R pipeline.pdf}
}
@@ -21,13 +22,14 @@
title = {Expected a Posteriori Scoring in {{PROMIS}}(®).},
author = {Chapman, Robert},
date = {2022-06-03},
- journaltitle = {J Patient Rep Outcomes},
+ journaltitle = {Journal of patient-reported outcomes},
+ shortjournal = {J Patient Rep Outcomes},
volume = {6},
number = {1},
eprint = {35657454},
eprinttype = {pmid},
pages = {59},
- location = {{Germany}},
+ location = {Germany},
issn = {2509-8020},
doi = {10.1186/s41687-022-00464-9},
abstract = {BACKGROUND: The Patient-Reported Outcome Measurement Information System(®) (PROMIS(®)) was developed to reliably measure health-related quality of life using the patient's voice. To achieve these aims, PROMIS utilized Item Response Theory methods in its development, validation and implementation. PROMIS measures are typically scored using a specific method to calculate scores, called Expected A Posteriori estimation. BODY: Expected A Posteriori scoring methods are flexible, produce accurate scores and can be efficiently calculated by statistical software. This work seeks to make Expected A Posteriori scoring methods transparent and accessible to a larger audience through description, graphical demonstration and examples. Further applications and practical considerations of Expected A Posteriori scoring are presented and discussed. All materials used in this paper are made available through the R Markdown reproducibility framework and are intended to be reviewed and reused. Commented statistical code for the calculation of Expected A Posteriori scores is included. CONCLUSION: This work seeks to provide the reader with a summary and visualization of the operation of Expected A Posteriori scoring, as implemented in PROMIS. As PROMIS is increasingly adopted and implemented, this work will provide a basis for making psychometric methods more accessible to the PROMIS user base.},
@@ -37,16 +39,28 @@
file = {/home/igor/Zotero/storage/7R2KLGBS/Chapman_2022_Expected a posteriori scoring in PROMIS(®).pdf}
}
+@online{commonmarkCommonMark,
+ title = {{{CommonMark}}},
+ author = {CommonMark},
+ url = {https://commonmark.org/},
+ urldate = {2023-04-25},
+ langid = {english},
+ organization = {CommonMark},
+ keywords = {cmu,non lu},
+ file = {/home/igor/Zotero/storage/ESNTHT9H/commonmark.org.html}
+}
+
@article{considineToolEncourageMinimum2019,
title = {A {{Tool}} to {{Encourage Minimum Reporting Guideline Uptake}} for {{Data Analysis}} in {{Metabolomics}}.},
author = {Considine, Elizabeth C. and Salek, Reza M.},
date = {2019-03-05},
journaltitle = {Metabolites},
+ shortjournal = {Metabolites},
volume = {9},
number = {3},
eprint = {30841575},
eprinttype = {pmid},
- location = {{Switzerland}},
+ location = {Switzerland},
issn = {2218-1989},
doi = {10.3390/metabo9030043},
abstract = {Despite the proposal of minimum reporting guidelines for metabolomics over a decade ago, reporting on the data analysis step in metabolomics studies has been shown to be unclear and incomplete. Major omissions and a lack of logical flow render the data analysis' sections in metabolomics studies impossible to follow, and therefore replicate or even imitate. Here, we propose possible reasons why the original reporting guidelines have had poor adherence and present an approach to improve their uptake. We present in this paper an R markdown reporting template file that guides the production of text and generates workflow diagrams based on user input. This R Markdown template contains, as an example in this instance, a set of minimum information requirements specifically for the data pre-treatment and data analysis section of biomarker discovery metabolomics studies, (gleaned directly from the original proposed guidelines by Goodacre at al). These minimum requirements are presented in the format of a questionnaire checklist in an R markdown template file. The R Markdown reporting template proposed here can be presented as a starting point to encourage the data analysis section of a metabolomics manuscript to have a more logical presentation and to contain enough information to be understandable and reusable. The idea is that these guidelines would be open to user feedback, modification and updating by the metabolomics community via GitHub.},
@@ -60,12 +74,13 @@
title = {Dynamic Publication Media with the {{COPASI R Connector}} ({{CoRC}}).},
author = {Daas, Johanna C. J. and Förster, Jonas D. and Pahle, Jürgen},
date = {2022-06},
- journaltitle = {Math Biosci},
+ journaltitle = {Mathematical biosciences},
+ shortjournal = {Math Biosci},
volume = {348},
eprint = {35452633},
eprinttype = {pmid},
pages = {108822},
- location = {{United States}},
+ location = {United States},
issn = {1879-3134 0025-5564},
doi = {10.1016/j.mbs.2022.108822},
abstract = {In this article we show how dynamic publication media and the COPASI R Connector (CoRC) can be combined in a natural and synergistic way to communicate (biochemical) models. Dynamic publication media are becoming a popular tool for authors to effectively compose and publish their work. They are built from templates and the final documents are created dynamically. In addition, they can also be interactive. Working with dynamic publication media is made easy with the programming environment R via its integration with tools such as R Markdown, Jupyter and Shiny. Additionally, the COmplex PAthway SImulator COPASI (http://www.copasi.org), a widely used biochemical modelling toolkit, is available in R through the use of the COPASI R Connector (CoRC, https://jpahle.github.io/CoRC). Models are a common tool in the mathematical biosciences, in particular kinetic models of biochemical networks in (computational) systems biology. We focus on three application areas of dynamic publication media and CoRC: Documentation (reproducible workflows), Teaching (creating self-paced lessons) and Science Communication (immersive and engaging presentation). To illustrate these, we created six dynamic document examples in the form of R Markdown and Jupyter notebooks, hosted on the platforms GitHub, shinyapps.io, Google Colaboratory. Having code and output in one place, creating documents in template-form and the option of interactivity make the combination of dynamic documents and CoRC a versatile tool. All our example documents are freely available at https://jpahle.github.io/DynamiCoRC under the Creative Commons BY 4.0 licence.},
@@ -83,8 +98,8 @@
urldate = {2023-04-17},
eventtitle = {So-Mate 2022},
langid = {fre},
- venue = {{Pau}},
- keywords = {markdown,non lu,pandoc,Publication scientifique}
+ venue = {Pau},
+ keywords = {cmu,markdown,non lu,pandoc,Publication scientifique}
}
@online{eyssetteUtiliserMarkdownPour2023,
@@ -96,8 +111,8 @@
urldate = {2023-04-17},
abstract = {Utiliser le Markdown pour tout faire.Le diaporama (fait en markdown bien sûr !) qui m'a servi de support lors de mon atelier pour la Journée du Libre Éducatif 2023.https://eyssette.forge.aeif.fr/marp-slides/slides/2022-2023/utiliser-le-markdown-pour-tout-faire\#Markdown\#JDLE\#JDLE2023\#TeamEduc\#MastoProf},
langid = {french},
- organization = {{Mastodon}},
- keywords = {fediverse,markdown,mastodon,non lu},
+ organization = {Mastodon},
+ keywords = {cmu,fediverse,markdown,mastodon,non lu},
file = {/home/igor/Zotero/storage/7FYFNED6/110158455766516456.html}
}
@@ -108,7 +123,7 @@
url = {https://eyssette.forge.aeif.fr/marp-slides/slides/2022-2023/utiliser-le-markdown-pour-tout-faire},
urldate = {2023-04-17},
langid = {fre},
- keywords = {non lu},
+ keywords = {cmu,non lu},
file = {/home/igor/Zotero/storage/I7CTE3X5/utiliser-le-markdown-pour-tout-faire.html}
}
@@ -121,8 +136,8 @@
urldate = {2023-04-17},
abstract = {Un guide simple pour apprendre Markdown.},
langid = {fre},
- organization = {{flus}},
- keywords = {documentation,markdown,non lu},
+ organization = {flus},
+ keywords = {cmu,documentation,markdown,non lu},
file = {/home/igor/Zotero/storage/96VGWVYV/markdown.html}
}
@@ -130,12 +145,13 @@
title = {R {{Markdown}} as a Dynamic Interface for Teaching: {{Modules}} from Math and Biology Classrooms.},
author = {Grayson, Kristine L. and Hilliker, Angela K. and Wares, Joanna R.},
date = {2022-07},
- journaltitle = {Math Biosci},
+ journaltitle = {Mathematical biosciences},
+ shortjournal = {Math Biosci},
volume = {349},
eprint = {35623397},
eprinttype = {pmid},
pages = {108844},
- location = {{United States}},
+ location = {United States},
issn = {1879-3134 0025-5564},
doi = {10.1016/j.mbs.2022.108844},
abstract = {Advancing technologies, including interactive tools, are changing classroom pedagogy across academia. Here, we discuss the R Markdown interface, which allows for the creation of partial or complete interactive classroom modules for courses using the R programming language. R Markdown files mix sections of R code with formatted text, including LaTeX, which are rendered together to form complete reports and documents. These features allow instructors to create classroom modules that guide students through concepts, while providing areas for coding and text response by students. Students can also learn to create their own reports for more independent assignments. After presenting the features and uses of R Markdown to enhance teaching and learning, we present examples of materials from two courses. In a Computational Modeling course for math students, we used R Markdown to guide students through exploring mathematical models to understand the principle of herd immunity. In a Data Visualization and Communication course for biology students, we used R Markdown for teaching the fundamentals of R programming and graphing, and for students to learn to create reproducible data investigations. Through these examples, we demonstrate the benefits of R Markdown as a dynamic teaching and learning tool.},
@@ -153,8 +169,8 @@
url = {https://daringfireball.net/projects/markdown/},
urldate = {2023-04-17},
langid = {english},
- organization = {{Daring Fireball}},
- keywords = {documentation,markdown,non lu},
+ organization = {Daring Fireball},
+ keywords = {cmu,documentation,markdown,non lu},
file = {/home/igor/Zotero/storage/J7WP5B3D/markdown.html}
}
@@ -162,13 +178,14 @@
title = {{{JBrowseR}}: An {{R}} Interface to the {{JBrowse}} 2 Genome Browser.},
author = {Hershberg, Elliot A. and Stevens, Garrett and Diesh, Colin and Xie, Peter and De Jesus Martinez, Teresa and Buels, Robert and Stein, Lincoln and Holmes, Ian},
date = {2021-11-05},
- journaltitle = {Bioinformatics},
+ journaltitle = {Bioinformatics (Oxford, England)},
+ shortjournal = {Bioinformatics},
volume = {37},
number = {21},
eprint = {34196689},
eprinttype = {pmid},
pages = {3914--3915},
- location = {{England}},
+ location = {England},
issn = {1367-4811 1367-4803},
doi = {10.1093/bioinformatics/btab459},
abstract = {MOTIVATION: Genome browsers are an essential tool in genome analysis. Modern genome browsers enable complex and interactive visualization of a wide variety of genomic data modalities. While such browsers are very powerful, they can be challenging to configure and program for bioinformaticians lacking expertise in web development. RESULTS: We have developed an R package that provides an interface to the JBrowse 2 genome browser. The package can be used to configure and customize the browser entirely with R code. The browser can be deployed from the R console, or embedded in Shiny applications or R Markdown documents. AVAILABILITY AND IMPLEMENTATION: JBrowseR is available for download from CRAN, and the source code is openly available from the Github repository at https://github.com/GMOD/JBrowseR/.},
@@ -182,17 +199,18 @@
title = {{{SCHNAPPs}} - {{Single Cell sHiNy APPlication}}(s).},
author = {Jagla, Bernd and Libri, Valentina and Chica, Claudia and Rouilly, Vincent and Mella, Sebastien and Puceat, Michel and Hasan, Milena},
date = {2021-12},
- journaltitle = {J Immunol Methods},
+ journaltitle = {Journal of immunological methods},
+ shortjournal = {J Immunol Methods},
volume = {499},
eprint = {34742775},
eprinttype = {pmid},
pages = {113176},
- location = {{Netherlands}},
+ location = {Netherlands},
issn = {1872-7905 0022-1759},
doi = {10.1016/j.jim.2021.113176},
abstract = {Single-cell RNA-sequencing (scRNAseq) experiments are becoming a standard tool for bench-scientists to explore the cellular diversity present in all tissues. Data produced by scRNAseq is technically complex and requires analytical workflows that are an active field of bioinformatics research, whereas a wealth of biological background knowledge is needed to guide the investigation. Thus, there is an increasing need to develop applications geared towards bench-scientists to help them abstract the technical challenges of the analysis so that they can focus on the science at play. It is also expected that such applications should support closer collaboration between bioinformaticians and bench-scientists by providing reproducible science tools. We present SCHNAPPs, a Graphical User Interface (GUI), designed to enable bench-scientists to autonomously explore and interpret scRNAseq data and associated annotations. The R/Shiny-based application allows following different steps of scRNAseq analysis workflows from Seurat or Scran packages: performing quality control on cells and genes, normalizing the expression matrix, integrating different samples, dimension reduction, clustering, and differential gene expression analysis. Visualization tools for exploring each step of the process include violin plots, 2D projections, Box-plots, alluvial plots, and histograms. An R-markdown report can be generated that tracks modifications and selected visualizations. The modular design of the tool allows it to easily integrate new visualizations and analyses by bioinformaticians. We illustrate the main features of the tool by applying it to the characterization of T cells in a scRNAseq and Cellular Indexing of Transcriptomes and Epitopes by Sequencing (CITE-Seq) experiment of two healthy individuals.},
langid = {english},
- keywords = {*Sequence Analysis; RNA,*Single-Cell Analysis,*Software,CITE-Seq,cmu,Humans,Leukocytes; Mononuclear/*cytology/immunology,markdown,multi-omics data analysis,non lu,pubmed,R markdown,scRNA-seq,Shiny application},
+ keywords = {*Sequence Analysis RNA,*Single-Cell Analysis,*Software,CITE-Seq,cmu,Humans,Leukocytes Mononuclear/*cytology/immunology,markdown,multi-omics data analysis,non lu,pubmed,R markdown,scRNA-seq,Shiny application},
file = {/home/igor/Zotero/storage/PEARJ76P/Jagla et al_2021_SCHNAPPs - Single Cell sHiNy APPlication(s).pdf}
}
@@ -200,13 +218,14 @@
title = {Dashboard-Style Interactive Plots for {{RNA-seq}} Analysis Are {{R Markdown}} Ready with {{Glimma}} 2.0.},
author = {Kariyawasam, Hasaru and Su, Shian and Voogd, Oliver and Ritchie, Matthew E. and Law, Charity W.},
date = {2021-12},
- journaltitle = {NAR Genom Bioinform},
+ journaltitle = {NAR genomics and bioinformatics},
+ shortjournal = {NAR Genom Bioinform},
volume = {3},
number = {4},
eprint = {34988439},
eprinttype = {pmid},
pages = {lqab116},
- location = {{England}},
+ location = {England},
issn = {2631-9268},
doi = {10.1093/nargab/lqab116},
abstract = {Glimma 1.0 introduced intuitive, point-and-click interactive graphics for differential gene expression analysis. Here, we present a major update to Glimma that brings improved interactivity and reproducibility using high-level visualization frameworks for R and JavaScript. Glimma 2.0 plots are now readily embeddable in R Markdown, thus allowing users to create reproducible reports containing interactive graphics. The revamped multidimensional scaling plot features dashboard-style controls allowing the user to dynamically change the colour, shape and size of sample points according to different experimental conditions. Interactivity was enhanced in the MA-style plot for comparing differences to average expression, which now supports selecting multiple genes, export options to PNG, SVG or CSV formats and includes a new volcano plot function. Feature-rich and user-friendly, Glimma makes exploring data for gene expression analysis more accessible and intuitive and is available on Bioconductor and GitHub.},
@@ -216,6 +235,45 @@
file = {/home/igor/Zotero/storage/ZQD2WXNN/Kariyawasam et al_2021_Dashboard-style interactive plots for RNA-seq analysis are R Markdown ready.pdf}
}
+@online{masuttiRedigerManipulerDocuments2019,
+ title = {Rédiger et manipuler des documents avec Markdown},
+ author = {Masutti, Christophe},
+ date = {2019-05-08},
+ url = {https://golb.statium.link/post/20190528rediger-et-manipuler-des-documents-markdown/},
+ urldate = {2024-03-19},
+ langid = {fre},
+ organization = {Statium : blog},
+ keywords = {cmu,markdown,non lu,pandoc,publication numérique,Publication scientifique}
+}
+
+@article{ovadiaMarkdownLibrariansAcademics2014a,
+ title = {Markdown for {{Librarians}} and {{Academics}}},
+ author = {Ovadia, Steven},
+ date = {2014-04-03},
+ journaltitle = {Behavioral \& Social Sciences Librarian},
+ shortjournal = {Behavioral \& Social Sciences Librarian},
+ volume = {33},
+ number = {2},
+ pages = {120--124},
+ issn = {0163-9269, 1544-4546},
+ doi = {10.1080/01639269.2014.904696},
+ url = {http://www.tandfonline.com/doi/abs/10.1080/01639269.2014.904696},
+ urldate = {2023-05-02},
+ langid = {english},
+ keywords = {cmu,markdown,non lu,Publication scientifique},
+ file = {/home/igor/Zotero/storage/25MP4P3N/Ovadia_2014_Markdown for Librarians and Academics.pdf}
+}
+
+@online{paged.jsPagedJs,
+ title = {About {{Paged}}.Js?},
+ author = {Paged.js},
+ url = {https://pagedjs.org/about/},
+ urldate = {2024-03-08},
+ langid = {english},
+ organization = {Paged.js},
+ keywords = {édition numérique,non lu,publication numérique}
+}
+
@online{pandocWritingThesisThinking2023,
type = {Mastodon post},
title = {Writing a \#thesis? {{Thinking}} about Doing It in \#{{Markdown}}? {{No}} Problem, {{Tom Pollard}} Has You Covered.{{https://github.com/tompollard/phd\_thesis\_ma…}}},
@@ -226,22 +284,21 @@
urldate = {2023-04-17},
abstract = {Writing a \#thesis? Thinking about doing it in \#Markdown? No problem, Tom Pollard has you covered.https://github.com/tompollard/phd\_thesis\_markdown},
langid = {english},
- organization = {{Mastodon}},
- keywords = {fediverse,markdown,mastodon,non lu,pandoc,Publication scientifique},
+ organization = {Mastodon},
+ keywords = {cmu,fediverse,markdown,mastodon,non lu,pandoc,Publication scientifique},
file = {/home/igor/Zotero/storage/T354LYSW/110184589069297715.html}
}
-@online{perretFormatTexte2022,
- type = {Site personnel},
+@article{perretFormatTexte2022,
title = {Format texte},
author = {Perret, Arthur},
date = {2022-12-11},
+ journaltitle = {Arthur Perret},
url = {https://www.arthurperret.fr/cours/format-texte.html},
urldate = {2023-04-18},
abstract = {Cette page explique ce qu’est le format texte et donne des arguments en faveur de son utilisation. Elle ouvre vers d’autres ressources pour explorer l’écosystème du format texte.},
langid = {fre},
- organization = {{Arthur Perret}},
- keywords = {markdown,non lu,plain text},
+ keywords = {cmu,markdown,non lu,plain text},
note = {\begin{quotation}
\par
@@ -251,21 +308,33 @@
file = {/home/igor/Zotero/storage/3IM8K4DU/format-texte.html}
}
-@online{perretMarkdown2022,
- type = {Site personnel},
+@article{perretMarkdown2022,
title = {Markdown},
author = {Perret, Arthur},
date = {2022-12-11},
- publisher = {{arthurperret.fr/}},
+ journaltitle = {Arthur Perret},
+ publisher = {arthurperret.fr/},
url = {https://www.arthurperret.fr/cours/markdown.html},
urldate = {2023-04-17},
abstract = {Cette page explique ce qu’est Markdown, le plus populaire des langages de balisage léger, et renvoie vers un tutoriel interactif en français.},
langid = {french},
- organization = {{Arthur Perret}},
- keywords = {documentation,markdown,non lu},
+ keywords = {cmu,documentation,markdown,non lu},
file = {/home/igor/Zotero/storage/HZNSDQ7S/markdown.html}
}
+@online{perretMarkdownTraitementTexte2022,
+ title = {Markdown et traitement de texte~: une méthode pour collaborer},
+ shorttitle = {Markdown et traitement de texte},
+ author = {Perret, Arthur},
+ date = {2022-10-25},
+ url = {https://www.arthurperret.fr/blog/2022-10-25-markdown-traitement-de-texte-methode-pour-collaborer.html},
+ urldate = {2024-04-23},
+ langid = {fre},
+ organization = {arthurperret.fr},
+ keywords = {non lu},
+ file = {/home/igor/Zotero/storage/TQEHEIHA/2022-10-25-markdown-traitement-de-texte-methode-pour-collaborer.html}
+}
+
@software{pollardTemplateWritingPhD2023,
title = {Template for Writing a {{PhD}} Thesis in {{Markdown}}},
author = {Pollard, Tom},
@@ -274,20 +343,21 @@
url = {https://github.com/tompollard/phd_thesis_markdown},
urldate = {2023-04-17},
abstract = {Template for writing a PhD thesis in Markdown},
- keywords = {markdown,non lu,pandoc,Publication scientifique,thesis-template}
+ keywords = {cmu,markdown,non lu,pandoc,Publication scientifique,thesis-template}
}
@article{schneiderFacilitatingOpenScience2022,
title = {Facilitating Open Science Practices for Research Syntheses: {{PreregRS}} Guides Preregistration.},
author = {Schneider, Jürgen and Backfisch, Iris and Lachner, Andreas},
date = {2022-03},
- journaltitle = {Res Synth Methods},
+ journaltitle = {Research synthesis methods},
+ shortjournal = {Res Synth Methods},
volume = {13},
number = {2},
eprint = {34921744},
eprinttype = {pmid},
pages = {284--289},
- location = {{England}},
+ location = {England},
issn = {1759-2887 1759-2879},
doi = {10.1002/jrsm.1540},
abstract = {Researchers increasingly engage in adopting open science practices in the field of research syntheses, such as preregistration. Preregistration is a central open science practice in empirical research to enhance transparency in the research process and it gains steady adoption in the context of conducting research synthesis. From an interdisciplinary perspective, frameworks and particularly templates are lacking which support researchers preparing a preregistration. To this end, we introduce preregRS, a template to guide researchers across disciplines through the process of preregistering research syntheses. We utilized an R Markdown template file to provide a framework that structures the process of preparing a preregistration. Researchers can write up the preregistration using the template file similar to filling out a form, with the template providing additional hints and further information for the decisions along the framework. We integrated the R Markdown template in an R package for easy installation and use, but also provide a browser-based option for users granting low-barrier access. PreregRS constitutes a first step to facilitate and support preregistration with research syntheses for all disciplines. It further adds to establishing open science practices in conducting research syntheses.},
@@ -299,13 +369,14 @@
title = {Veridical Data Science.},
author = {Yu, Bin and Kumbier, Karl},
date = {2020-02-25},
- journaltitle = {Proc Natl Acad Sci U S A},
+ journaltitle = {Proceedings of the National Academy of Sciences of the United States of America},
+ shortjournal = {Proc Natl Acad Sci U S A},
volume = {117},
number = {8},
eprint = {32054788},
eprinttype = {pmid},
pages = {3920--3929},
- location = {{United States}},
+ location = {United States},
issn = {1091-6490 0027-8424},
doi = {10.1073/pnas.1901326117},
abstract = {Building and expanding on principles of statistics, machine learning, and scientific inquiry, we propose the predictability, computability, and stability (PCS) framework for veridical data science. Our framework, composed of both a workflow and documentation, aims to provide responsible, reliable, reproducible, and transparent results across the data science life cycle. The PCS workflow uses predictability as a reality check and considers the importance of computation in data collection/storage and algorithm design. It augments predictability and computability with an overarching stability principle. Stability expands on statistical uncertainty considerations to assess how human judgment calls impact data results through data and model/algorithm perturbations. As part of the PCS workflow, we develop PCS inference procedures, namely PCS perturbation intervals and PCS hypothesis testing, to investigate the stability of data results relative to problem formulation, data cleaning, modeling decisions, and interpretations. We illustrate PCS inference through neuroscience and genomics projects of our own and others. Moreover, we demonstrate its favorable performance over existing methods in terms of receiver operating characteristic (ROC) curves in high-dimensional, sparse linear model simulations, including a wide range of misspecified models. Finally, we propose PCS documentation based on R Markdown or Jupyter Notebook, with publicly available, reproducible codes and narratives to back up human choices made throughout an analysis. The PCS workflow and documentation are demonstrated in a genomics case study available on Zenodo.},
diff --git a/example/static/pagedjs-in-browser.png b/example/static/pagedjs-in-browser.png
new file mode 100644
index 0000000..7c75b05
Binary files /dev/null and b/example/static/pagedjs-in-browser.png differ
diff --git a/style.css b/style.css
index 7c1876a..98499af 100644
--- a/style.css
+++ b/style.css
@@ -1,21 +1,16 @@
@media print {
- body {
- font-family: TheSans, "Open Sans", Arial, Helvetica, sans-serif;
- counter-reset: figureNumber;
- }
- /* Définit que string(date) contient la date */
- .date {
- string-set: date content(text);
- display: none;
- }
- /* Définit que running(licenceBlock) contient le block licence */
- #licence {
- position: running(licenceBlock);
- }
+
+ /* **************************
+ * Définition des pages *
+ * ************************ */
+
@page {
size: A4;
- margin: 25mm 0;
+ margin: 25mm;
bleed: 6mm;
+ /* Numérotation de page au centre en bas
+ * de la page. Le compteur est définit
+ * dans le selecteur body. */
@bottom-center {
content: counter(page);
}
@@ -29,6 +24,8 @@
margin-right: 25mm;
}
@page:first {
+ /* Insertion en haut à droite du logo de la
+ * bibliothèque de l'UNIGE. */
@top-right {
content: "";
background-image: url("./static/bibliotheque-logo.svg");
@@ -36,6 +33,9 @@
background-repeat: no-repeat;
background-size: 25%;
}
+ /* Place le bloc de la licence en bas à gauche
+ * de la première page. Voir le sélecteur
+ * #licence plus bas. */
@bottom-left{
content: element(licenceBlock);
font-size: small;
@@ -43,29 +43,57 @@
@bottom-center {
content: none;
}
+ /* Insert la date en bas à droite de la
+ * première page. Voir le sélecteur .date */
@bottom-right {
content: string(date);
font-size: small;
}
}
- @page:nth(11) {
- @bottom-center {
- content: none;
- }
+
+ /* **************************
+ * Définitions globales *
+ * ************************ */
+
+ body {
+ font-family: "TheSansOsF", "Open Sans", Arial, Helvetica, sans-serif;
+ /* Définit les trois variables de compteur nécessaires */
+ counter-reset: figureNumber toc tableNumber;
}
- h2 {
- color: #d80669;
- text-decoration: underline;
+ /* Définit que string(date) contient la date indiquée dans le frontmatter
+ * de la source markdown */
+ .date {
+ string-set: date content(text);
+ display: none; /* Pour ne pas afficher la date sous le titre. */
}
- #1st-section,
- #bibliographie,
- .footnotes {
- break-before: page;
+ /* Définit que running(licenceBlock) contient le block licence.
+ * Le bloc licence est décrit dans le fichier markdown source, au-dessous
+ * de la section des objectifs. Le CSS permet de le placer correctement */
+ #licence {
+ position: running(licenceBlock);
}
+
+ /* *****************
+ * Page de titre *
+ * *************** */
+
+ .logo {
+ display: inline-flex;
+ justify-content: center;
+ width: 60%;
+ margin: 2em auto 1em auto;
+ }
+ .logo img {
+ max-width: 50%;
+ padding: .5em;
+ }
+
#title-block-header {
+ /* Concerne le bloc titre sur la page de titre */
text-align: center;
- margin: 2em 0 6em 0;
+ margin: 4em 0;
}
+
.authors {
display: flex;
justify-content: center;
@@ -74,14 +102,60 @@
margin: 0;
padding: 0 1em;
}
+
+ /* Les 4 règles suivantes mettent en forme la table des matières :*
+ * Suppression des liste à puce, numérotation des chapitres et affichage du
+ * numéro de page. */
+ #TOC ul {
+ list-style: none;
+ counter-reset: toc;
+ padding-left: 1.5em;
+ }
+ #TOC li {
+ counter-increment: toc;
+ }
+ #TOC li::before {
+ content: counter(toc) ". ";
+ }
+ #TOC a::after {
+ content: target-counter(attr(href url), page);
+ position: absolute;
+ right: 0;
+ }
+
+ /* ***************************
+ * Structure du document *
+ * ************************* */
+
+ /* Ajouter ou supprimer les ID de titre pour un saut de page.
+ * Les IDs #first-section et #bibliography peuvent être ajoutés
+ * dans la source markdown. */
+ #first-section,
+ #bibliography,
+ .footnotes {
+ break-before: page;
+ }
+
+ /* *************
+ * Contenu *
+ * *********** */
+
+ h2 {
+ color: #d80669;
+ text-decoration: underline;
+ }
+
pre {
- font-family:'Courier New', Courier, monospace;
- font-size: 90%;
background-color: #f2f1f1;
border: 2px solid #d80669;
border-radius: .5em;
- margin: 1em;
padding: .5em 1em;
+ /* Évite que les blocs de code ne soient séparés sur 2 pages */
+ break-inside: avoid;
+ }
+ pre > code {
+ border-radius: none;
+ padding: none;
}
code {
font-family:'Courier New', Courier, monospace;
@@ -90,18 +164,25 @@
padding: 2px;
border-radius: 5px;
}
+
.footnotes::before {
content: "Notes";
color: #d80669;
font-size: 120%;
font-weight: bold;
}
+ .footnote-ref {
+ text-decoration: none;
+ }
+
figure {
display: flex;
flex-direction: column;
border: 2px solid #d80669;
border-radius: .5em;
padding: .5em;
+ /* Évite que les figures ne soient séparés sur 2 pages */
+ break-inside: avoid;
}
figure img {
max-width: 85%;
@@ -116,33 +197,35 @@
figcaption::before {
content: "Figure " counter(figureNumber) " : ";
}
+
blockquote {
font-style: italic;
}
blockquote em {
font-style: normal;
}
+
div.csl-entry {
padding: .5em;
}
- .logo {
- display: inline-flex;
- width: 60%;
- margin: 2em auto 1em auto;
+
+ table {
+ width: 90%;
+ margin: 1em auto;
+ border-collapse: collapse;
}
- .logo img {
- max-width: 50%;
- padding: .5em;
+
+ th, td {
+ padding: 5px;
+ border: 1px solid;
}
- #TOC ul {
- list-style: none;
- counter-reset: tocCounter;
- padding-left: 1.5em;
+ table > caption {
+ counter-increment: tableNumber;
+ caption-side: bottom;
+ font-size: small;
+ padding-top: .5em;
}
- #TOC li {
- counter-increment: tocCounter;
- }
- #TOC li::before {
- content: counter(tocCounter) ". ";
+ table > caption:before {
+ content: "Table " counter(tableNumber) " : ";
}
}
+
+