References and derivations

A reference is a named result that the learner looks up: a formula, a rule, a definition. It has a title, a statement, an optional equation, an optional legend, and an optional derivation that says why it holds.

The app collects the references of a section into one set, at the end of the section. A topic shows its own references at its end too. The interface names these sets with the references label of the domain: References by default, or Formulary in a domain that sets references: Formulary (The root and the domain).

A reference

A reference lives in the deck that teaches it, after the flashcards of the deck.

::: reference quadratic-formula
# The quadratic formula

For $a x^2 + b x + c = 0$ with $a \ne 0$, the solutions are

::: equation
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}.
:::

::: legend
$x$: the solutions (roots)
$a$: coefficient of the square term
$b$: coefficient of the linear term
$c$: constant term
:::

::: derivation
Divide by $a$ and complete the square:

$$ x^2 + \frac{b}{a}\,x = -\frac{c}{a}, \qquad \left(x + \frac{b}{2a}\right)^2 = \frac{b^2 - 4ac}{4a^2}. $$

The numerator on the right is the discriminant.[The discriminant](reference:discriminant)
Take the square root of both sides and isolate $x$ to get the formula. ∎
:::
:::

A reference holds only these three blocks: ::: equation, ::: legend and ::: derivation. A reference can sit in a deck only. It cannot sit in a checkpoint or in an index.md.

The id

The id is required, and it is unique in its domain. A reference: link names the reference by its id alone, from any deck of the domain, so one id must give one reference.

ERROR ./math/alg/linears/solving.md:23: `::: reference` needs an id, like `::: reference ohms-law`: a `reference:` link names a reference by it
ERROR ./math/alg/linears/solving.md:26: `r1` is already the id of a reference, at math/alg/linears/solving.md: ids are unique per kind

The title

The first line with text in the reference must start with # . The learner finds the reference by its title.

ERROR ./math/alg/linears/solving.md:23: reference `r1` has no `# Title` line: the title is what the learner looks the reference up by

The equation

The ::: equation block holds the bare equation in LaTeX, with no $ or $$ around it. The app shows it as display math. Math, figures and assets lists the LaTeX that works. LaTeX that does not parse is an error, at its line:

ERROR ./math/alg/linears/solving.md:13: the LaTeX `\frac{V}` will not render: parsing error: expected a token

The legend

The ::: legend block says what each symbol stands for. Write one row per line, as $symbol$: what it means.

::: legend
$I$: current, in amperes
$V$: voltage across the conductor, in volts
$R$: resistance, in ohms
:::

The first : on a line splits the symbol from its meaning, so a meaning can contain a colon. The app shows the symbol as math. The meaning is plain text with inline math: write its math in $…$, as in a card. A meaning takes no Markdown and no links. A row without a : is an error:

ERROR ./math/alg/linears/solving.md:26: `$x$ the unknown` is not a legend row: each line reads `$symbol$: what it means`, and this one has no `:`

The symbol is LaTeX, and LaTeX that does not parse is an error at its row. The math in a meaning follows the same rule. A $ without a partner in a meaning is an error too, so a meaning cannot hold a lone dollar sign:

ERROR ./math/alg/linears/solving.md:17: the LaTeX `\nosuch` will not render: parsing error: unknown primitive command found
ERROR ./math/alg/linears/solving.md:18: a `$` has no closing `$` in "costs $5"

The derivation

The ::: derivation block says why the reference holds. Write it as a log:

• State the goal.
• Put each step on its own line.
• Use real numbers, in order.
• State the result with its units.
• End with ∎.

A derivation that uses another reference links it, right after the step that uses it. The app lists these links under the derivation as Rests on. Do not write that list yourself, and link only the references the derivation stands on.

A derivation is not a solution. A solution is the worked answer to one flashcard, and it lives in that flashcard (Flashcards and solutions).

Links

A link to a reference is a Markdown link with the reference: scheme.

The app shows the link as a small Σ mark. The text of the link is not shown: it names the reference for a screen reader and in the tooltip. A click opens the reference in the references of its section. So put the link right after the clause that uses the result, as a marker:

Each drops a voltage by Ohm's law: $V_1 = I R_1$.[Ohm's law](reference:ohms-law)

A reference: link works in these places:

• a card and a figure;
• the question, the answer and the solution of a flashcard or of an exam question;
• the statement and the derivation of a reference;
• the instructions and the questions of an exam.

It does not work in a legend or in an equation.

Other links

What the checker finds

The checker resolves every link, with the same code as the import (Check your repository). Each fault names the file and the line of the link:

A link in an answer counts like every other link: it is checked, and it is an edge from the flashcard.

A link cannot leave its repository. The other repository can be absent from the device of the learner, and its domain ids are hashes that you cannot write. So keep domains that link to each other in one repository.

The three edges

The links give the app a graph with three kinds of edge.

The checker refuses a cycle in requires and in uses, inside one domain and across the domains of the repository. It names the cycle:

ERROR ./math/alg/linears/solving.md:9: `uses` is cyclic: /math/a -> /math/b -> /math/a
ERROR ./math/alg/linears/index.md: `requires` is cyclic: /math/alg/linears -> /math/alg/quadratics -> /math/alg/linears

requires

A topic lists the topics to read first:

---
title: Quadratics
tier: entrance
requires: [linears]
order: [quadratic-formula]
---

The menu dims a topic until the learner has read every deck of the topics it requires. It is a cue, not a gate: the learner can still open the topic.

The checker refuses a target that is not there, and a target in another repository:

ERROR ./math/alg/linears/index.md: `fundamentals` names no topic in this section
ERROR ./math/alg/linears/index.md: `/math/geo/lines` names no topic in domain `math`
ERROR ./math/alg/linears/index.md: `/phy/eam/fields` points outside this repository, and a reference cannot cross one: move that content here, or drop the link

uses

The links in a derivation are the references it rests on. The app lists them under the derivation as Rests on, and the learner can follow them one step at a time.

reference

Every other reference: link says that a card, a flashcard or a statement uses a result.