Expand description
Bibliographic references: the single source for every citation surface.
CLI help, the JSON run.references, dima cite, the GUI’s Cite DiMA dialog and tooltips,
the documentation bibliography and CITATION.cff are all produced from this module, so a
reference can never disagree between surfaces.
References are ranked by the repository’s citation policy (see AGENTS.md): domain venues
first (Tier::Domain), then general statistics, mathematics (including numerical analysis),
HCI or computer science only where they are the primary source of a number, algorithm or
result (Tier::General), then standards and specifications, cited for what they define
(Tier::Standard).
§In-text labels
In-text labels (Citation::short) are computed once over the whole registry, so a work has
the same label on every surface (D114):
- Family names and year:
Shannon 1948,Chao & Jost 2012,List et al. 2017. - Works that share that label show as many names as needed to tell them apart, the same
number for each work of the group:
Grüning, Dale et al. 2018andGrüning, Chilton et al. 2018. “et al.” always stands for two or more names, so a list at most one name longer than shown is written in full (APA 7 §8.18; CSL 1.0.2disambiguate-add-names; biblatexuniquelist=minyear). - Works whose names are still identical get year letters
a,b, …,z,aa, … in title order, ignoring a leading A, An or The (APA 7 §8.19 and §9.47; CSL 1.0.2disambiguate-add-year-suffix).
Letters appear in labels and in dima’s own name-year reference lists
(Citation::listed_text: the documentation pages and the Bibliography). They never appear
in exported records (Citation::text: run.references, dima cite, BibTeX, RIS, CFF),
because a citing document assigns its own.
A standard whose publisher gives it a short name is labelled by that designation instead,
without a year (D115): RFC 8259 (RFC 7322, Section 3.5), UAX #15 (the Unicode
Consortium’s abbreviated citations), WCAG 2.2 (the W3C’s reference tags). Designations are
unique by construction and need no letters. dima’s own reference lists start the entry with
the designation, so the label leads to it; exported records do not carry it.
Structs§
- Citation
- One bibliographic reference.
- Cite
- A use of a reference, optionally pointing at a specific rule, figure or section
(for example
Cite::new("list2017").at("Rule 5")).
Enums§
- Kind
- Publication type, used to choose the BibTeX/RIS/CFF entry type.
- Tier
- Citation-policy tier of a reference (
AGENTS.md, “Citation policy”).
Constants§
- DIMA_
PAPER - Citation key of the DiMA paper (Tharanga et al. 2025).
- DOCS_
URL - The documentation this build links to (D113): that of its own version (
…/vX.Y/) for a release build, that of the development version (…/latest/) otherwise. - SOFTWARE_
AUTHORS - Authors of this software (
(family, given)), as listed inCargo.toml. - SOFTWARE_
KEYWORDS - Keywords describing this software (CITATION.cff, .zenodo.json).
- SOFTWARE_
REPOSITORY - Public source repository of this software.
- SOFTWARE_
TITLE - Title of this software in citations.
- SOFTWARE_
VERSION - Version of this software.
Functions§
- all
- Every reference, sorted by key.
- by_key
- Looks a reference up by key.
- cff_
document - A CFF 1.2.0 document describing a release of this software, with the DiMA paper as
preferred-citationandextraas additionalreferences(the content ofCITATION.cff, whichcargo xtask genprefixes with a generated-file comment). - dima_
paper - The DiMA paper: Tharanga et al., Brief Bioinform 2025;26(1):bbae607.
- release_
docs_ url - The documentation of a release of this software, e.g.
…/dima-perf/v1.0/for 1.0.0. - software_
bibtex - BibTeX entry for a release of this software.
- software_
ris - RIS record for a release of this software.
- software_
text - Plain-text citation of a release of this software (usually
SOFTWARE_VERSION; the version recorded in a results file fordima cite --from), e.g.Tharanga S. dima: sequence diversity dynamics analyser for viruses (Rust implementation), version 1.0.0. https://github.com/….