Skip to content

Docs Citations & Bibliography — crediting the work we build on — Design Spec (#TBD)

Milestone: docs-citations-bibliography Manual: TBD — a “Credits & bibliography” page the docs site can link from every manual: the DH methods, projects, and code libraries Fichero builds on, each with its licence and citation.

Design-led (Testing Constitution). Status: DRAFT — awaiting creative-director approval. Tags: [OK] built · [PARTIAL] exists · [MISSING] not built.

Scope boundary: this is SCHOLARLY / dependency attribution for the DOCS — crediting the DH methods, projects, and code libraries Fichero builds on. It is NOT source-provenance (a claim back to its archival page-segment) — that lives in kg-readable-representation.md (kg.read.cite-to-segment). Two different “citations”; keep them apart.

Why this spec exists

Fichero stands on a large body of prior work — the factoid model, the Reiter & Dale NLG pipeline, Six Degrees of Francis Bacon, MapLibre, Grape, HGIS de las Indias, and the code libraries in the manifests. Today that credit is scattered in prose or absent. Scholarship (and good manners) require it be explicit, resolvable, and exportable — readable for a person AND emittable as BibTeX for a paper.

Intent (the design)

One canonical bibliography (docs/references.bib, BibTeX) is the single source of truth. Docs in docs/user_manual/ and docs/contributor_manual/ cite entries by key; a guardrail proves every citation resolves and the file parses. Docs render a human-readable References section (not raw keys), and the bibliography exports (BibTeX now; CSL/other later) for papers and for the “sources” surfaces. References are categorized by what they inform (a spec, a feature, a doc) so “what are we building on for X?” is answerable. Code/library dependencies are credited too, drawn from the dependency manifests, kept distinct from the scholarly entries.

Behaviors

  • cite.bibtex-canonical [MISSING] (#4654) — docs/references.bib is the one BibTeX store; every scholarly/tool reference is an entry with a stable key (e.g. six-degrees-francis-bacon).
  • cite.docs-resolve [MISSING, hard] (#4655) — every citation key used in docs/user_manual/** and docs/contributor_manual/** resolves to a .bib entry; an orphan citation fails the gate (scripts/check_doc_citations.py). Mirrors how check_specs_have_tests binds specs to tests. A citation is written in Pandoc’s [@key] syntax (ruled 2026-10-04).
  • cite.unused-flagged [MISSING] (#4655) — the same guardrail also flags a .bib entry no doc cites (a dead reference). (Ruled 2026-10-04.)
  • cite.human-readable [MISSING] (#4656) — a doc renders its References as author/title/year/URL a person can read, generated from the .bib — the key is the source, the rendering is derived.
  • cite.code-deps [MISSING] (#4658) — code/library dependencies (from pyproject.toml / SwiftPM) are credited in a generated “Dependencies & credits” doc, distinct from the scholarly entries.
  • cite.categorized [MISSING] (#4658) — each entry is tagged with what it informs (spec/feature slug), so a spec’s “Related work” list is generated, not hand-maintained.
  • cite.exportable [MISSING] (#4658) — the bibliography exports as BibTeX (and later CSL-JSON) for papers and for the app’s future “sources / where this comes from” surface.
  • cite.surfaces [MISSING] (#4657) — the credits render in THREE places from the one .bib: the app’s About box, the user guide (docs/user_manual/), and the website — generated, never hand-copied, so they never drift.
  • cite.people-first [MISSING] (#4654) — ordering puts specific people / articles first (the scholarship and the humans behind it), then projects, then code libraries — credit the thinking before the tooling.

Test matrix

Leg This surface? Pins File
Guardrail (py) y every doc citation key resolves to a .bib entry; .bib parses scripts/check_doc_citations.py
Pure rule (py) y .bib → human-readable reference string; categorization lookup fichero-server/tests/unit/scripts/test_check_doc_citations.py
Gate wiring y the guardrail runs in verify_all.sh (auto-discovered)

Hard-gate: cite.docs-resolve (no orphan citations — a claimed source must exist).

Rulings

  • 2026-10-04 (maintainer): citations in Markdown docs use Pandoc’s [@key] syntax.
  • Ruled 2026-10-04 (design lead, applying the spec’s own lean): the guardrail flags unused .bib entries as well as orphan citations (cite.unused-flagged); code-dependency credits live in a separate generated file built from the manifests, and the .bib is for scholarship (cite.code-deps); docs come first, and the app’s “where this comes from” surface follows later from the export (cite.exportable).

Open questions for the creative director

None outstanding: all four are answered (see Rulings). 1. Answered (maintainer 2026-10-04: Pandoc citations): Pandoc-style [@key]. Citation syntax in Markdown docs — Pandoc-style [@key], or a plainer {{cite:key}}? 2. Answered (design lead 2026-10-04, applying the spec’s own lean): Yes, unused entries are flagged too. Should the guardrail also flag UNUSED .bib entries (dead references), or only orphans? 3. Answered (design lead 2026-10-04, applying the spec’s own lean): A separate generated file from the manifests; the .bib is for scholarship. Do code-dependency credits live in the same .bib or a separate generated file? 4. Answered (design lead 2026-10-04, applying the spec’s own lean): Docs first; the export makes the app surface cheap later. Is the app’s “where this comes from” surface in scope now, or docs-only first?

Triaged from the backlog (2026-10-04)

  • cite.generated-client-transport — [GAP] (#3254) bibliography, reference and render-citation calls go through the generated OpenAPI client with typed returns; EntityService+Bibliography.swift still uses untyped endpointData Data (citationUsages already migrated, EntityService.swift:116).