Skip to main content

Module citations

Module citations 

Source
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):

  1. Family names and year: Shannon 1948, Chao & Jost 2012, List et al. 2017.
  2. 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. 2018 and Grü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.2 disambiguate-add-names; biblatex uniquelist=minyear).
  3. 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.2 disambiguate-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 in Cargo.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-citation and extra as additional references (the content of CITATION.cff, which cargo xtask gen prefixes 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 for dima cite --from), e.g. Tharanga S. dima: sequence diversity dynamics analyser for viruses (Rust implementation), version 1.0.0. https://github.com/….