Word reference

Word Reference Manager

Overview

Word Reference Manager handles all citation and reference-related operations in academic paper Word documents. It integrates with Zotero for automated bibliography generation, uses citeproc-py for precise citation formatting, and manages footnotes/endnotes.

When to Use

• Formatting a reference list per a specific citation style
• Pulling references from Zotero and inserting into the document
• Checking that in-text citations match the reference list
• Adding, editing, or deleting footnotes/endnotes
• Converting references between citation styles

When NOT to Use

• Checking cross-references (figures/tables) → use word-check
• Editing body text → use word-edit
• Formatting non-reference parts → use word-format

---

Feature A: Reference List Formatting

With Zotero Integration

Step 1: Identify references
  → Scan document for in-text citations: [1], [2] or (Author, Year)
  → Or user provides a Zotero collection name

Step 2: Fetch from Zotero
  → search_items / get_item to retrieve reference metadata
  → export_bibliography for batch export

Step 3: Format with citeproc-py
  → Load appropriate CSL style file
  → Generate formatted reference list

Step 4: Write to document
  → replace_paragraph_block_below_header: replace content under "参考文献" or "References"
  → Or add_paragraph for each reference entry
  → Apply reference font/size per Format Spec via STYLE definitions (style-first, 禁止 run 级直接格式化):
     Bash: python3 scripts/format_document.py "{file_path}" styles \
       --name "Bibliography" --cn-font 宋体 --en-font "Times New Roman" \
       --font-size 五号 --line-spacing 1.0
     若参考文献段落使用 Normal 样式而需单独行距/字号，用段落范围覆盖:
     Bash: python3 scripts/format_document.py "{file_path}" paragraph \
       --style Normal --range "{ref_start},{ref_end}" --line-spacing 1.0

Without Zotero (Manual Formatting)

Step 1: Read existing reference list from document
Step 2: Parse each entry to extract metadata (author, year, title, journal...)
Step 3: Reformat each entry per the target citation style
Step 4: Replace the reference list in the document

Using citeproc-py

Step 0 (MANDATORY): Check that the CSL file exists before running citeproc-py.

CSL files live in {plugin_root}/references/csl/ (expected: china-national-standard-gb-t-7714-2015-numeric.csl, apa.csl). Check with Glob/Bash first:

IF references/csl/{style}.csl 不存在:
  1. 提示用户下载地址:
     - GB/T 7714-2015 顺序编码制:
       https://raw.githubusercontent.com/citation-style-language/styles/master/china-national-standard-gb-t-7714-2015-numeric.csl
     - APA 7th:
       https://raw.githubusercontent.com/citation-style-language/styles/master/apa.csl
     - 其他样式: https://www.zotero.org/styles 搜索下载
     下载后放入插件的 references/csl/ 目录（保持原文件名）。
  2. 降级为手工格式化（"Without Zotero (Manual Formatting)" 流程）:
     按目标引文样式的规则逐条重排参考文献条目，不经过 citeproc-py。
  3. 不要在 CSL 文件缺失时调用 citeproc-py —— 会直接抛 FileNotFoundError。

python3 << 'PYEOF'
import json
from citeproc import CitationStylesStyle, CitationStylesBibliography
from citeproc import Citation, CitationItem
from citeproc.source.json import CiteProcJSON

# Load CSL style (path relative to plugin root; verify existence first — see Step 0)
style = CitationStylesStyle('references/csl/china-national-standard-gb-t-7714-2015-numeric.csl')

# Reference data (from Zotero or manual input)
references = [
    {
        "id": "ref1",
        "type": "article-journal",
        "title": "Biodiversity and ecosystem functioning",
        "author": [{"family": "Tilman", "given": "David"}],
        "issued": {"date-parts": [[2001]]},
        "container-title": "Nature",
        "volume": "411",
        "page": "689-695"
    }
]

source = CiteProcJSON(references)
bib = CitationStylesBibliography(style, source)

# Register citations
for ref in references:
    bib.register(Citation([CitationItem(ref["id"])]))

# Generate formatted bibliography
for item in bib.bibliography():
    print(str(item))
PYEOF

Feature B: Citation Consistency Check

Step 1: Extract in-text citations
  → Numbered: [1], [2], [1-3], [1,3,5]
  → Author-year: (Author, Year), (Author1 & Author2, Year)

Step 2: Extract reference list entries
  → Parse numbered entries: [1] Author. Title...
  → Parse author-year entries: Author (Year). Title...

Step 3: Cross-check
  → Missing: cited in text but not in reference list
  → Orphan: in reference list but never cited
  → Order: numbered references should appear in citation order

Step 4: Report
  → List all inconsistencies with locations

Feature C: Footnote/Endnote Management

Add Footnotes

→ add_footnote_to_document(file_path, paragraph, text)

Validate Footnotes

→ validate_document_footnotes(file_path)
→ Report any broken or orphaned footnotes

Delete Footnotes

→ delete_footnote_from_document(file_path, footnote_id)

Batch Operations

For adding multiple footnotes, execute sequentially to avoid position conflicts.

Feature D: Style Conversion

Convert the entire reference list from one citation style to another:

1. Parse existing references to extract metadata
2. Load target CSL style
3. Re-format all entries with citeproc-py
4. Replace reference list in document
5. Update in-text citations if format changes (e.g., [1] → (Author, Year))

---

Post-Execution

After any reference operation:

1. MANDATORY: Font Normalization — Run python3 scripts/normalize_fonts.py "{file_path}" --unify before returning the document. See ../../references/font_normalization.md.
2. Report changes made
3. Suggest running word-checker to verify citation consistency
4. If reference format changed, remind to check in-text citation format matches

Shared Resources

• ../../references/academic_formatting.md — Citation style overview
• ../../references/format_spec_parser.md — Reference formatting in Format Spec
• ../../references/tool_routing.md — Tool selection priority