---
name: docxology/infrastructure-reference-citation
source: https://app.decimal.ai/s/docxology-infrastructure-reference-citation@1/SKILL.md
source_sha256: 1566ec8d9f71
---

# Citation Submodule

BibTeX I/O matching `projects/templates/template_code_project/manuscript/references.bib`.

## Reading

```python
from infrastructure.reference.citation import parse_bibfile, parse_bibtex

db = parse_bibfile("projects/templates/template_code_project/manuscript/references.bib")
print(len(db))                      # 8
print(db.keys())                    # ['nocedal2006numerical', ...]
entry = db.find("boyd2004convex")
print(entry.entry_type)             # 'article'
print(entry.get("author"))          # 'Boyd, Stephen and Vandenberghe, Lieven'
print(db.preamble)                  # The @comment{...} block
```

## Writing

```python
from collections import OrderedDict
from infrastructure.reference.citation import (
    BibEntry, BibDatabase, render_database, write_bibfile
)

db = BibDatabase()
db.add(BibEntry(
    "article", "smith2024example",
    OrderedDict([
        ("title", "An Example Paper"),
        ("author", "Smith, Alice and Jones, Bob"),
        ("journal", "Cambridge UP"),
        ("year", "2024"),
        ("pages", "1-10"),       # auto-normalised to "1--10"
        ("doi", "10.1234/example"),
    ]),
))
print(render_database(db))
write_bibfile("output/refs.bib", db)
```

## Convert from a search result

```python
from infrastructure.reference.citation import paper_to_bibentry, generate_citation_key
from infrastructure.search.literature import Paper

paper = Paper(id="x", title="Adam", authors=["Kingma, Diederik P", "Ba, Jimmy"], year=2014, venue="ICLR", venue_type="conference")
entry = paper_to_bibentry(paper)        # entry_type → "inproceedings", key → "kingma2014adam"

# Override either field:
entry = paper_to_bibentry(paper, citation_key="my_custom_key", entry_type="misc")

# Or generate a key without converting:
key = generate_citation_key(authors=["Cauchy, Augustin-Louis"], year=1847, title="Méthode générale")
# → "cauchy1847methode"
```

## CLI

```bash
# Validate
uv run python -m infrastructure.reference.citation.cli validate refs.bib --strict

# Re-format in canonical layout
uv run python -m infrastructure.reference.citation.cli format refs.bib

# Convert literature-search JSON → BibTeX
uv run python -m infrastructure.reference.citation.cli convert papers.json refs.bib
```

## LaTeX escaping

```python
from infrastructure.reference.citation import escape_latex, unescape_latex
escape_latex("Smith & Co")            # 'Smith \\& Co'
unescape_latex(r"Smith \& Co")        # 'Smith & Co'
```

The writer applies escaping automatically; you only need these helpers when
constructing values manually.

## Format Guarantees

The writer's output round-trips through the parser without semantic loss
and matches the exemplar `references.bib` byte-for-byte:

* 2-space field indent
* Trailing comma after every field except the last
* `pages={N--M}` (BibTeX em-dash) regardless of input form
* DOIs / URLs / years / volumes emitted verbatim
* Unicode preserved (Pandoc / XeLaTeX handle it natively)
* `book` / `phdthesis` / `techreport` / `misc` entries never get a stray
  `journal=` field