backend: print the 参考文献 list as a bibliography, one entry per work
The list was printing each citation's quote under a `引用 #53` tag: no authors, no year, no pages, no DOI — the quoted passage where the entry should be — and it numbered *citations*, so a paper with 86 citations to 65 works listed 21 of them two or three times under different numbers. The same article was `[5]` in one paragraph and `[17]` in another. Two rules were wrong, so two are stated here: **A work is numbered where the reader first meets it.** A citation is a place in the text; an entry is a work. `citations` still has one row per place, and each row now carries the number of its *work*, so the marker in the text, the tooltip on it and the entry in the list are the same number. The document grew a `references` list — the entries, in order — and `reference_style`, which names the style that wrote them. **How a reference prints is a property of a style, not of a citation.** The new `app/citation_styles` package holds one module per style; `springer.py` implements Springer's basic style, whose shape is `Names: Title. <where it sits> (year). <identifier>` with a branch per document type — a journal with its volume(issue) and pages, a book with publisher and place, a chapter inside somebody else's book, a patent with its number, a page whose URL is its source. Three of its rules are decisions rather than transcription, and each is documented where it applies: up to six contributors are named and more become three plus `et al.`; a journal prints under its 刊名缩写 when the writer stored one, because no algorithm abbreviates an arbitrary title correctly; and a CJK name keeps its printed form even with halves filled in, because dotting 「三」 into an initial is wrong in Chinese and insufficient in English. Nothing is invented to fill a gap. An entry says what it knows and reports the rest as `missing` (「缺 责任者、出版年」), and the document warns about the incomplete ones by number: an entry that is short because fields are empty looks like a fact about the document rather than a library that needs attention. `document_text` had the same bug in the MCP surface and now prints the entries, with in-text markers taken from the document's numbering rather than from each sentence's local position — which is what made the text an agent reads disagree with the list under it. `scripts/check_citation_styles.py` checks the formatter with no server and no database: one reference of every type, and the exact entry the style calls for.
This commit is contained in:
@@ -0,0 +1,87 @@
|
||||
"""Citation styles: a stored reference written out as a bibliography entry.
|
||||
|
||||
A reference is stored as fields — 题名, 刊名, 卷, 期, 页码, DOI, 责任者 — and a
|
||||
*paper* prints those fields in the order and with the punctuation one particular
|
||||
style asks for. The two are deliberately separate: the library holds the facts
|
||||
once, and a style decides how to write them down, so adding a style adds a module
|
||||
rather than a column.
|
||||
|
||||
The module is one style per file, registered in :data:`STYLES`, and this package
|
||||
is the only thing the rest of the application imports:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from app.citation_styles import DEFAULT_STYLE, format_reference
|
||||
|
||||
text = format_reference(reference) # the default style
|
||||
gaps = missing_fields(reference) # 「缺 责任者、出版年」
|
||||
|
||||
``DEFAULT_STYLE`` is what a document is assembled with, and the document reports
|
||||
it back as ``reference_style`` so a client can name the format it is showing
|
||||
without hard-coding the choice.
|
||||
"""
|
||||
|
||||
from typing import Protocol
|
||||
|
||||
from app.citation_styles import springer
|
||||
from app.models import Reference
|
||||
|
||||
|
||||
class Style(Protocol):
|
||||
"""What a style module provides.
|
||||
|
||||
Structural rather than a base class: a style is a module of two functions,
|
||||
and inheriting from something would only add an import to every one of them.
|
||||
"""
|
||||
|
||||
def format_reference(self, reference: Reference) -> str:
|
||||
"""Write one reference out as a bibliography entry."""
|
||||
|
||||
def missing_fields(self, reference: Reference) -> list[str]:
|
||||
"""Which parts a complete entry is missing, in Chinese."""
|
||||
|
||||
|
||||
#: The styles this build can print, by the token a document reports.
|
||||
STYLES: dict[str, Style] = {"springer": springer}
|
||||
|
||||
#: The style a document is assembled with when nothing says otherwise.
|
||||
#:
|
||||
#: Springer's basic style: bracketed numerals in the text, a numbered list at the
|
||||
#: end, and entries of the shape ``Names: Title. <where> (year). <identifier>``.
|
||||
DEFAULT_STYLE = "springer"
|
||||
|
||||
|
||||
def _style(name: str):
|
||||
"""Look a style up, or say which ones exist."""
|
||||
try:
|
||||
return STYLES[name]
|
||||
except KeyError:
|
||||
known = "、".join(sorted(STYLES))
|
||||
raise ValueError(f"未知的参考文献格式:{name}(可用:{known})") from None
|
||||
|
||||
|
||||
def format_reference(reference: Reference | None, style: str = DEFAULT_STYLE) -> str:
|
||||
"""Write one reference out as a bibliography entry.
|
||||
|
||||
``None`` — a citation whose row the library no longer has — yields the empty
|
||||
string rather than a fabricated entry: the caller decides how to say
|
||||
"unlinked", and this module never guesses.
|
||||
"""
|
||||
if reference is None:
|
||||
return ""
|
||||
return _style(style).format_reference(reference)
|
||||
|
||||
|
||||
def missing_fields(reference: Reference | None, style: str = DEFAULT_STYLE) -> list[str]:
|
||||
"""Which parts a complete entry is missing, in the style's own terms."""
|
||||
if reference is None:
|
||||
return []
|
||||
return _style(style).missing_fields(reference)
|
||||
|
||||
|
||||
__all__ = [
|
||||
"DEFAULT_STYLE",
|
||||
"STYLES",
|
||||
"format_reference",
|
||||
"missing_fields",
|
||||
]
|
||||
Reference in New Issue
Block a user