126 lines
4.2 KiB
Markdown
126 lines
4.2 KiB
Markdown
# notes — Quarto extension for course notes
|
|
|
|
The same copy lives in every course (`<course>/_extensions/notes/`). Each filter
|
|
documents its syntax in the comment at its top; this page is the overview.
|
|
|
|
| File | What it does |
|
|
|---|---|
|
|
| `calc-notes.lua` | `\begin{calc}` / `calc*` derivations with `\note{}` / `\mnote{}`; label with `$$ … $$ {#eq-x}` |
|
|
| `exo.lua` | `::::{.exo}` exercises with `.hint` and `.solution` placed where written; hand-in mode |
|
|
| `quiz.lua` | `::::{.quiz}` tick-box self-checks with a **Check** button and per-option `.why` |
|
|
| `glossary.lua` | `.gls-def`, `\gls{key}`, `[term]{.gls}`, `::: {.glossary}`; resolves across chapters |
|
|
| `latex-tables.lua` | `tabular` environments rendered as HTML tables |
|
|
| `i18n.lua` | one source, several languages: `::: {.de}`, `[…]{.fr}`, `@tr{key}` |
|
|
| `si-mathjax.lua` | `\SI`, `\si`, `\num`, `\ang` in HTML (PDF uses siunitx) |
|
|
| `fenced-divs.lua` | repairs `:::` divs indented deeper than pandoc accepts (in numbered parts) |
|
|
|
|
## Options (in `_quarto.yml`)
|
|
|
|
```yaml
|
|
notecolor: "#B45309" # accent colour of notes, exercises, hints
|
|
|
|
exo:
|
|
pdf-solutions: inline # PDF: solutions in place (default: end of chapter)
|
|
label: "Exercice" # labels follow `lang` (en/fr/de); override any of
|
|
hint: "Indice" # label, hint, solution, solutions, part, page
|
|
|
|
quiz:
|
|
pdf-answers: inline # PDF: answers under the quiz (default: end of chapter)
|
|
label: "Quiz" # labels follow `lang` (en/fr/de); override any of
|
|
question: "Question" # label, question, answers, answer, check, reset,
|
|
check: "Vérifier" # right, wrong, score, true, false, hint, page
|
|
|
|
siunitx-html: mathjax # leave \SI & co. to a MathJax siunitx extension
|
|
|
|
glossary-page: glossary.html
|
|
glossary-back: "→ definition in context" # follows `lang` (en/fr/de) by default
|
|
```
|
|
|
|
## Exercises
|
|
|
|
```markdown
|
|
::::{.exo title="Stefan-Boltzmann law"}
|
|
Statement.
|
|
|
|
1. First part.
|
|
|
|
:::{.hint}
|
|
A hint for this part.
|
|
:::
|
|
|
|
:::{.solution}
|
|
Solution of part 1.
|
|
:::
|
|
|
|
2. Second part.
|
|
|
|
:::{.solution}
|
|
Solution of part 2.
|
|
:::
|
|
::::
|
|
```
|
|
|
|
Each solution is labelled with its part ("Solution (Part 2)"). Override with
|
|
`:::{.solution part="b"}`. Empty solutions (placeholders) are not shown.
|
|
|
|
## Quizzes
|
|
|
|
```markdown
|
|
::::{.quiz title="Landau notation"}
|
|
::: {.question}
|
|
Decide which statements are true.
|
|
|
|
- [x] $n + 2 = o(n^2)$
|
|
- [ ] $n = \mathcal{O}(\log^2 n)$
|
|
|
|
:::{.why}
|
|
$n$ eventually outgrows every power of $\log n$.
|
|
:::
|
|
:::
|
|
::::
|
|
```
|
|
|
|
`- [x]` is a true statement, `- [ ]` a false one. A `.why` inside an option
|
|
explains that option; a `.why` written directly in the question explains the
|
|
question as a whole. Both are shown only to a reader who got it wrong.
|
|
|
|
A quiz holds any number of `::: {.question}` divs (a quiz with none is read as
|
|
a single question). Numbering is chapter.n, as for exercises.
|
|
|
|
In HTML the options are real checkboxes and one **Check** button at the end of
|
|
the quiz marks every option, reveals the explanations for the mistakes and
|
|
scores the quiz; **Reset** clears it. A question counts as correct only when
|
|
*all* of its options are in the right state — the exam's multiple-true-false
|
|
rule.
|
|
|
|
In the PDF the boxes are empty, to tick with a pen, and the answers are
|
|
printed at the end of the chapter with a page reference back to the quiz
|
|
(`quiz: pdf-answers: inline` keeps them in place).
|
|
|
|
Correct answers are part of the built HTML, as solutions are: the quiz is a
|
|
self-check, not an assessment.
|
|
|
|
## Tools
|
|
|
|
**Hand in solutions.** Renders only the chosen exercises to `_handin/`, and
|
|
lists each one with any empty solution:
|
|
|
|
```bash
|
|
_extensions/notes/handin.sh 1.3 1.5 --subtitle "Series 2"
|
|
_extensions/notes/handin.sh 2 --no-statement # all of chapter 2, solutions only
|
|
_extensions/notes/handin.sh 1.2 --profile fr # a language of a multilingual book
|
|
_extensions/notes/handin.sh --help
|
|
```
|
|
|
|
**Keep every course on the same version.** After changing the extension in
|
|
one course, push it to all the others:
|
|
|
|
```bash
|
|
_extensions/notes/sync.sh --dry-run # what would change
|
|
_extensions/notes/sync.sh
|
|
```
|
|
|
|
A copy that was edited in place (or has a higher `version:`) is skipped with a
|
|
diff, so nothing is overwritten silently. Bump `version:` in `_extension.yml`
|
|
when you change something.
|