# References

_a reference that cites a document rather than the code or an outside service_

**Intent.** This check exists so that a reference leads to something that can settle the claim above it. A citation to another document moves the question rather than answering it, and a reader following one should arrive at the code, or at the documentation of the service being described.

A reference whose link contains `.md` anywhere, **or names a PDF inside the wiki**, is refused, because a
document is another claim that can be wrong in the same way.[^document][^pdfcite] What every sentence must
carry is described on [Citations](../index.md).

## Refusals

Outside documentation passes when its address has no `.md`, so **a README on GitHub is refused like a
project document**.[^document]

## Scope

Every reference on every page is read, and the check names the page rather than the line.[^document]

## Exceptions

A reference naming a document without linking it passes, as does one naming nothing.[^document]

## Enforcement

Each problem is listed with every other problem `wiki check` finds.[^order]

## Clearing

A refused reference passes once it names the file and function that do the thing, or the outside service's
own documentation at an address that is not a markdown file.[^document]

[^document]: `src/builder/build.py` — `citation_problems()` matches `DOCUMENT_LINK`, a markdown link whose
    address contains `.md` anywhere, inside each footnote; its comment gives the reason.
[^pdfcite]: `src/builder/build.py` — `citation_problems()` also matches `PDF_DOCUMENT_LINK`, a markdown link to
    a `.pdf` address with no scheme and no leading `//`, inside each footnote.
[^order]: `src/builder/build.py` — `check()` adds `citation_problems()` to the problems it lists.