Compare commits
4 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| b97aab6f30 | |||
| 340e0777ce | |||
| 54292eb231 | |||
| 76708ce767 |
@@ -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",
|
||||
]
|
||||
@@ -0,0 +1,564 @@
|
||||
"""Springer basic style: one stored reference, written out as a bibliography entry.
|
||||
|
||||
Springer's **basic** style is the numbered one — bracketed numerals in the text
|
||||
and a numbered list at the end — which is the shape this project already has.
|
||||
What it adds is the layout of the entry itself, taken from Springer's own
|
||||
examples:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
Van der Geer, J., Hanraads, J.A.J., Lupton, R.A.: The art of writing a
|
||||
scientific article. J. Sci. Commun. 163(2), 51–59 (2010).
|
||||
https://doi.org/10.1016/j.Sc.2010.00372
|
||||
|
||||
Strunk Jr., W., White, E.B.: The Elements of Style, 4th edn. Longman,
|
||||
New York (2000)
|
||||
|
||||
Mettam, G.R., Adams, L.B.: How to prepare an electronic version of your
|
||||
article. In: Jones, B.S., Smith, R.Z. (eds.) Introduction to the Electronic
|
||||
Age, pp. 281–304. E-Publishing Inc., New York (2009)
|
||||
|
||||
So an entry is ``Names: Title. <where the entry sits> (year). <identifier>``,
|
||||
and *where it sits* is the only part that changes with the document type: a
|
||||
journal with its volume and pages, a book with its publisher, a chapter inside
|
||||
somebody else's book, a patent with its number.
|
||||
|
||||
Three rules here are decisions rather than transcription, and each is stated
|
||||
where it is applied:
|
||||
|
||||
* **Up to six contributors are named; more become the first three and
|
||||
``et al.``** — Springer's rule for this style.
|
||||
* **A journal prints under its 刊名缩写 when the writer stored one**, because
|
||||
Springer abbreviates journal titles and no algorithm abbreviates an arbitrary
|
||||
title correctly: the library has a column for the abbreviation precisely so a
|
||||
human decides it. Without one, the full 刊名 is printed rather than an
|
||||
invention.
|
||||
* **A CJK name is printed as stored**, halves or no halves: dotting 「三」 into
|
||||
an initial is wrong in Chinese and insufficient in English (see
|
||||
:func:`_name`).
|
||||
* **Nothing is invented to fill a gap.** A missing year prints no parentheses, a
|
||||
missing publisher no publisher; the field simply does not appear. What a
|
||||
complete entry would need is reported separately by :func:`missing_fields`, so
|
||||
the writer is told what is absent instead of being shown a plausible-looking
|
||||
fabrication.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from datetime import date
|
||||
from typing import Callable
|
||||
|
||||
from app.models import Reference, ReferenceAuthor
|
||||
|
||||
#: How many contributors are named before the list is cut short, and how many
|
||||
#: survive the cut. Springer's basic style names up to six, then the first three
|
||||
#: followed by ``et al.``
|
||||
_AUTHOR_LIMIT = 6
|
||||
_AUTHOR_KEEP = 3
|
||||
|
||||
#: ``122-141`` → ``122–141``. Springer prints ranges with an en dash, and the
|
||||
#: stored value is whatever the writer pasted — often a plain hyphen.
|
||||
_PAGE_RANGE = re.compile(r"(\d+)\s*[-–—]\s*(\d+)")
|
||||
|
||||
#: CJK ideographs and kana. A name containing one is printed as stored rather
|
||||
#: than inverted and initialised; see :func:`_name`.
|
||||
_CJK = re.compile(r"[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]")
|
||||
|
||||
_MONTHS = (
|
||||
"January",
|
||||
"February",
|
||||
"March",
|
||||
"April",
|
||||
"May",
|
||||
"June",
|
||||
"July",
|
||||
"August",
|
||||
"September",
|
||||
"October",
|
||||
"November",
|
||||
"December",
|
||||
)
|
||||
|
||||
#: For a web page the URL *is* the source, so it is printed where a journal
|
||||
#: would be rather than at the end as an identifier. Every other type keeps the
|
||||
#: URL for the trailing ``https://doi.org/…`` slot.
|
||||
_URL_IS_THE_SOURCE = frozenset({"web-page"})
|
||||
|
||||
|
||||
def format_reference(reference: Reference) -> str:
|
||||
"""Write one reference out as a Springer bibliography entry.
|
||||
|
||||
The clauses are assembled and joined by ``". "``, which is the style's own
|
||||
punctuation: the colon after the names, the period between the title and
|
||||
where the entry sits, and the period before the DOI all fall out of it.
|
||||
"""
|
||||
clauses = [
|
||||
clause
|
||||
for clause in (
|
||||
_head(reference),
|
||||
*_where(reference),
|
||||
_identifier(reference),
|
||||
_accessed(reference),
|
||||
)
|
||||
if clause
|
||||
]
|
||||
|
||||
# A clause that is nothing but a year is not a sentence, so it attaches to
|
||||
# what precedes it rather than following a full stop. This is the shape a
|
||||
# reference with a title and a year and nothing else takes: "…: Six (2021)",
|
||||
# not "…: Six. (2021)". Doing it here rather than in each of the fourteen
|
||||
# builders is one rule instead of fourteen chances to forget it.
|
||||
parts: list[str] = []
|
||||
for clause in clauses:
|
||||
if parts and clause.startswith("(") and clause.endswith(")"):
|
||||
parts[-1] = f"{parts[-1]} {clause}"
|
||||
else:
|
||||
parts.append(clause)
|
||||
return ". ".join(parts)
|
||||
|
||||
|
||||
# --- the two halves every entry has ------------------------------------------
|
||||
|
||||
|
||||
def _head(reference: Reference) -> str:
|
||||
"""``Names: Title`` — what the entry is, and who wrote it."""
|
||||
names = _head_names(reference)
|
||||
title = _title(reference)
|
||||
return f"{names}: {title}" if names else title
|
||||
|
||||
|
||||
def _title(reference: Reference) -> str:
|
||||
"""The title, with its subtitle after a colon.
|
||||
|
||||
The library stores 副题名 as its own column because a citation style is
|
||||
allowed to drop it; this one prints it, so the two are joined back into the
|
||||
title the reader saw.
|
||||
"""
|
||||
title = _clean(reference.title)
|
||||
subtitle = _clean(reference.subtitle)
|
||||
if subtitle and not title.endswith((":", ":")):
|
||||
title = f"{title}: {subtitle}"
|
||||
elif subtitle:
|
||||
title = f"{title} {subtitle}"
|
||||
|
||||
# For a whole book the edition belongs to the title ("The Elements of
|
||||
# Style, 4th edn"); for a chapter it belongs to the book it sits in, which
|
||||
# is where :func:`_where_chapter` puts it.
|
||||
if reference.type == "book" and _clean(reference.edition):
|
||||
title = f"{title}, {_clean(reference.edition)}"
|
||||
return title
|
||||
|
||||
|
||||
def _head_names(reference: Reference) -> str:
|
||||
"""The contributors that lead the entry.
|
||||
|
||||
Authors first. A book whose contributors are all marked 编者 is written by
|
||||
its editors — ``Jones, B.S. (ed.)`` — and a 汇编 / 译者 with no author at all
|
||||
still has to appear somewhere, so the last resort is the stored list in
|
||||
print order.
|
||||
"""
|
||||
authors = [author for author in reference.authors if author.role == "author"]
|
||||
if authors:
|
||||
return _name_list(authors)
|
||||
|
||||
editors = [author for author in reference.authors if author.role == "editor"]
|
||||
if editors:
|
||||
return _name_list(editors) + (" (ed.)" if len(editors) == 1 else " (eds.)")
|
||||
|
||||
return _name_list(list(reference.authors))
|
||||
|
||||
|
||||
def _editor_names(reference: Reference) -> str:
|
||||
"""The 编者 of a chapter's containing book, marked ``(ed.)`` / ``(eds.)``.
|
||||
|
||||
The library keeps one contributor list per entry, so these are the
|
||||
contributors the writer marked 编者. When there are none the container is
|
||||
printed without a mark rather than guessing whose book it is.
|
||||
"""
|
||||
editors = [author for author in reference.authors if author.role == "editor"]
|
||||
if not editors:
|
||||
return ""
|
||||
mark = " (ed.)" if len(editors) == 1 else " (eds.)"
|
||||
return _name_list(editors) + mark
|
||||
|
||||
|
||||
def _name_list(people: list[ReferenceAuthor]) -> str:
|
||||
"""The contributor list, cut to Springer's limit."""
|
||||
names = [_name(person) for person in people if person.name.strip()]
|
||||
if len(names) > _AUTHOR_LIMIT:
|
||||
return ", ".join(names[:_AUTHOR_KEEP]) + ", et al."
|
||||
return ", ".join(names)
|
||||
|
||||
|
||||
def _name(person: ReferenceAuthor) -> str:
|
||||
"""One contributor as ``Family, I.N.``
|
||||
|
||||
The halves are the authority for rewriting a name and the whole ``name`` is
|
||||
the authority for printing it, as the model says. So a row with Latin halves
|
||||
is inverted and initialised — some of them arrive already abbreviated
|
||||
(``Lai KK`` → ``Lai, K.K.``) — while a row without them is printed exactly as
|
||||
stored, which is the only correct thing to do for an institutional author
|
||||
(「世界卫生组织」, "World Health Organization") and for a CJK name whose
|
||||
romanisation the library was never told.
|
||||
|
||||
A CJK name keeps its printed form even *with* halves filled in. ``张`` +
|
||||
``三`` inverted and dotted gives 「张, 三.」, which is neither Chinese nor
|
||||
English: an initial is a Latin-script idea, and 「三」 is not the initial of
|
||||
a given name, it is the whole of it. Springer's own ``Zhang, S.`` needs a
|
||||
romanisation this library does not hold, so the stored 「张三」 is printed
|
||||
rather than turned into something that is wrong in both languages.
|
||||
"""
|
||||
family = _clean(person.family_name)
|
||||
given = _clean(person.given_name)
|
||||
if not family or _CJK.search(family) or _CJK.search(given):
|
||||
return _clean(person.name)
|
||||
initials = _initials(given)
|
||||
return f"{family}, {initials}" if initials else family
|
||||
|
||||
|
||||
def _initials(given: str) -> str:
|
||||
"""``Yong Ming`` → ``Y.M.``, ``AL`` → ``A.L.``, ``Jean-Luc`` → ``J.-L.``"""
|
||||
if not given:
|
||||
return ""
|
||||
|
||||
initials: list[str] = []
|
||||
for token in given.split():
|
||||
parts = [part for part in re.split(r"[-–]", token) if part]
|
||||
if len(parts) > 1:
|
||||
initials.append("-".join(_initial(part) for part in parts))
|
||||
else:
|
||||
initials.append(_initial(token))
|
||||
return "".join(part for part in initials if part)
|
||||
|
||||
|
||||
def _initial(token: str) -> str:
|
||||
"""One given-name token as initials.
|
||||
|
||||
A token that is already a block of initials is expanded letter by letter —
|
||||
``KK`` is two names, not one — and a token that is a name contributes its
|
||||
first letter.
|
||||
"""
|
||||
letters = [character for character in token if character.isalpha()]
|
||||
if not letters:
|
||||
return ""
|
||||
if len(letters) > 1 and token.isupper():
|
||||
return "".join(f"{character.upper()}." for character in letters)
|
||||
return f"{letters[0].upper()}."
|
||||
|
||||
|
||||
# --- where the entry sits ----------------------------------------------------
|
||||
|
||||
|
||||
def _where(reference: Reference) -> list[str]:
|
||||
"""The clauses between the title and the identifier, by document type."""
|
||||
builder: Callable[[Reference], list[str]] = _WHERE.get(
|
||||
reference.type, _where_generic
|
||||
)
|
||||
return builder(reference)
|
||||
|
||||
|
||||
def _where_journal(reference: Reference) -> list[str]:
|
||||
"""``J. Sci. Commun. 163(2), 51–59 (2010)``"""
|
||||
source = _join_space(_container(reference), _volume_issue(reference))
|
||||
source = _join_comma(source, _pages(reference))
|
||||
return [_with_year(source, reference)]
|
||||
|
||||
|
||||
def _where_newspaper(reference: Reference) -> list[str]:
|
||||
"""``The Times, p. 12 (2020)`` — a newspaper has a date, not a volume."""
|
||||
source = _join_comma(_container(reference), _pages(reference))
|
||||
return [_with_year(source, reference)]
|
||||
|
||||
|
||||
def _where_book(reference: Reference) -> list[str]:
|
||||
"""``Longman, New York (2000)``, with the series ahead of it."""
|
||||
clauses = []
|
||||
series = _join_comma(_clean(reference.series_title), _clean(reference.series_number))
|
||||
if series:
|
||||
clauses.append(series)
|
||||
place = _join_comma(_clean(reference.publisher), _clean(reference.publisher_place))
|
||||
clauses.append(_with_year(place, reference))
|
||||
return [clause for clause in clauses if clause]
|
||||
|
||||
|
||||
def _where_chapter(reference: Reference) -> list[str]:
|
||||
"""``In: Jones, B.S. (ed.) Book title, pp. 281–304. E-Publishing Inc., New York (2009)``"""
|
||||
inside = _container(reference)
|
||||
if inside and _clean(reference.edition):
|
||||
inside = f"{inside}, {_clean(reference.edition)}"
|
||||
pages = _pages(reference)
|
||||
if pages:
|
||||
inside = _join_comma(inside, f"pp. {pages}")
|
||||
|
||||
editors = _editor_names(reference)
|
||||
inside = _join_space(editors, inside) if editors else inside
|
||||
opening = f"In: {inside}" if inside else ""
|
||||
|
||||
place = _with_year(
|
||||
_join_comma(_clean(reference.publisher), _clean(reference.publisher_place)),
|
||||
reference,
|
||||
)
|
||||
return [clause for clause in (opening, place) if clause]
|
||||
|
||||
|
||||
def _where_conference(reference: Reference) -> list[str]:
|
||||
"""``In: Proceedings of …, pp. 10–20. Springer, Cham (2022)``"""
|
||||
inside = _container(reference) or _clean(reference.event_title)
|
||||
pages = _pages(reference)
|
||||
if pages:
|
||||
inside = _join_comma(inside, f"pp. {pages}")
|
||||
opening = f"In: {inside}" if inside else ""
|
||||
|
||||
place = _with_year(
|
||||
_join_comma(
|
||||
_clean(reference.publisher),
|
||||
_clean(reference.publisher_place) or _clean(reference.event_place),
|
||||
),
|
||||
reference,
|
||||
)
|
||||
return [clause for clause in (opening, place) if clause]
|
||||
|
||||
|
||||
def _where_thesis(reference: Reference) -> list[str]:
|
||||
"""``Thesis, 清华大学 (2020)``
|
||||
|
||||
The degree (PhD, 硕士) is not a field of this library, so the entry says
|
||||
what it knows rather than inventing a doctorate.
|
||||
"""
|
||||
return [_with_year(_join_comma("Thesis", _clean(reference.publisher)), reference)]
|
||||
|
||||
|
||||
def _where_patent(reference: Reference) -> list[str]:
|
||||
"""``中国 Patent CN114000000A (2023)`` — the country and number inside the mark."""
|
||||
mark = _join_space(_clean(reference.patent_country), "Patent")
|
||||
marked = _join_space(mark, _clean(reference.patent_number))
|
||||
return [_with_year(marked, reference)]
|
||||
|
||||
|
||||
def _where_standard(reference: Reference) -> list[str]:
|
||||
"""``GB/T 7714-2015. 中国标准出版社, 北京 (2015)``
|
||||
|
||||
The number follows the title rather than leading the entry: the title is
|
||||
what the writer searched by and what the reader recognises.
|
||||
"""
|
||||
number = _clean(reference.standard_number)
|
||||
place = _with_year(
|
||||
_join_comma(_clean(reference.publisher), _clean(reference.publisher_place)),
|
||||
reference,
|
||||
)
|
||||
return [clause for clause in (number, place) if clause]
|
||||
|
||||
|
||||
def _where_report(reference: Reference) -> list[str]:
|
||||
"""``NREL/TP-5000-12345, NREL, Golden (2012)``"""
|
||||
clause = _join_comma(
|
||||
_clean(reference.report_number),
|
||||
_clean(reference.publisher),
|
||||
_clean(reference.publisher_place),
|
||||
)
|
||||
return [_with_year(clause, reference)]
|
||||
|
||||
|
||||
def _where_web(reference: Reference) -> list[str]:
|
||||
"""``https://… (2021)`` — for a page the URL is where the entry sits."""
|
||||
return [_with_year(_clean(reference.url), reference)]
|
||||
|
||||
|
||||
def _where_dataset(reference: Reference) -> list[str]:
|
||||
"""``Dataset (2024)`` — the type stands where a journal name would."""
|
||||
return [_with_year("Dataset", reference)]
|
||||
|
||||
|
||||
def _where_software(reference: Reference) -> list[str]:
|
||||
"""``Software (2024)``"""
|
||||
return [_with_year("Software", reference)]
|
||||
|
||||
|
||||
def _where_preprint(reference: Reference) -> list[str]:
|
||||
"""``Preprint arXiv:2405.12345 (2024)`` — how a paper is cited before a DOI."""
|
||||
return [_with_year(_join_space("Preprint", _clean(reference.arxiv_id)), reference)]
|
||||
|
||||
|
||||
def _where_generic(reference: Reference) -> list[str]:
|
||||
"""Anything typed ``other``: the container, then the publisher.
|
||||
|
||||
The year closes whichever of the two is the last thing printed, so it never
|
||||
dangles on its own in the middle of an entry.
|
||||
"""
|
||||
source = _join_comma(_container(reference), _pages(reference))
|
||||
place = _join_comma(_clean(reference.publisher), _clean(reference.publisher_place))
|
||||
if place:
|
||||
return [clause for clause in (source, _with_year(place, reference)) if clause]
|
||||
return [_with_year(source, reference)]
|
||||
|
||||
|
||||
_WHERE: dict[str, Callable[[Reference], list[str]]] = {
|
||||
"journal-article": _where_journal,
|
||||
"newspaper-article": _where_newspaper,
|
||||
"book": _where_book,
|
||||
"book-chapter": _where_chapter,
|
||||
"conference-paper": _where_conference,
|
||||
"thesis": _where_thesis,
|
||||
"patent": _where_patent,
|
||||
"standard": _where_standard,
|
||||
"report": _where_report,
|
||||
"web-page": _where_web,
|
||||
"dataset": _where_dataset,
|
||||
"software": _where_software,
|
||||
"preprint": _where_preprint,
|
||||
}
|
||||
|
||||
|
||||
# --- the identifier, and the day it was read ---------------------------------
|
||||
|
||||
|
||||
def _identifier(reference: Reference) -> str:
|
||||
"""``https://doi.org/10.1016/j.Sc.2010.00372``, or the URL, or nothing.
|
||||
|
||||
A DOI is printed as the resolvable link, which is how Springer prints it —
|
||||
the column stores it bare so the two spellings cannot drift.
|
||||
"""
|
||||
doi = _clean(reference.doi)
|
||||
if doi:
|
||||
return f"https://doi.org/{doi}"
|
||||
if reference.type in _URL_IS_THE_SOURCE:
|
||||
return ""
|
||||
return _clean(reference.url)
|
||||
|
||||
|
||||
def _accessed(reference: Reference) -> str:
|
||||
"""``Accessed 12 May 2021`` — the day an online resource was read."""
|
||||
if reference.accessed_date is None:
|
||||
return ""
|
||||
return f"Accessed {_long_date(reference.accessed_date)}"
|
||||
|
||||
|
||||
def _long_date(value: date) -> str:
|
||||
return f"{value.day} {_MONTHS[value.month - 1]} {value.year}"
|
||||
|
||||
|
||||
# --- what a complete entry is still missing ----------------------------------
|
||||
|
||||
|
||||
#: The fields a complete entry needs, per type. ``None`` means "this type has no
|
||||
#: such field", so the list is not padded with requirements that do not apply.
|
||||
_REQUIRED: dict[str, tuple[str, ...]] = {
|
||||
"journal-article": ("责任者", "刊名", "卷期页码", "出版年"),
|
||||
"newspaper-article": ("责任者", "报纸名", "页码", "出版年"),
|
||||
"book": ("责任者", "出版者", "出版年"),
|
||||
"book-chapter": ("责任者", "书名", "页码", "出版者", "出版年"),
|
||||
"conference-paper": ("责任者", "会议名", "出版年"),
|
||||
"thesis": ("责任者", "培养单位", "出版年"),
|
||||
"patent": ("责任者", "专利号", "出版年"),
|
||||
"standard": ("标准编号", "出版年"),
|
||||
"report": ("责任者", "报告编号", "出版年"),
|
||||
"web-page": ("URL", "引用日期"),
|
||||
"dataset": ("URL", "出版年"),
|
||||
"software": ("URL", "出版年"),
|
||||
"preprint": ("责任者", "出版年"),
|
||||
"other": ("责任者", "出版年"),
|
||||
}
|
||||
|
||||
|
||||
def missing_fields(reference: Reference) -> list[str]:
|
||||
"""Which parts of a complete entry this reference still lacks, in Chinese.
|
||||
|
||||
The point is that a gap should be *reported* rather than quietly rendered as
|
||||
a shorter entry: an entry with no author and no year looks like a fact about
|
||||
the document instead of a field nobody filled in.
|
||||
"""
|
||||
missing: list[str] = []
|
||||
for field in _REQUIRED.get(reference.type, _REQUIRED["other"]):
|
||||
if not _has(reference, field):
|
||||
missing.append(field)
|
||||
return missing
|
||||
|
||||
|
||||
def _has(reference: Reference, field: str) -> bool:
|
||||
"""Whether the field this label names is filled in."""
|
||||
if field == "责任者":
|
||||
return bool(reference.authors)
|
||||
if field == "刊名" or field == "报纸名" or field == "会议名" or field == "书名":
|
||||
# A chapter's 书名 and a paper's 论文集名 are both the container; a
|
||||
# conference may carry its meeting name instead.
|
||||
return bool(
|
||||
_clean(reference.container_title)
|
||||
or (field == "会议名" and _clean(reference.event_title))
|
||||
)
|
||||
if field == "卷期页码":
|
||||
return bool(
|
||||
_clean(reference.volume)
|
||||
or _clean(reference.issue)
|
||||
or _clean(reference.pages)
|
||||
or _clean(reference.article_number)
|
||||
)
|
||||
if field == "页码":
|
||||
return bool(_clean(reference.pages) or _clean(reference.article_number))
|
||||
if field == "出版者" or field == "培养单位":
|
||||
return bool(_clean(reference.publisher))
|
||||
if field == "标准编号":
|
||||
return bool(_clean(reference.standard_number))
|
||||
if field == "报告编号":
|
||||
return bool(_clean(reference.report_number) or _clean(reference.publisher))
|
||||
if field == "专利号":
|
||||
return bool(_clean(reference.patent_number))
|
||||
if field == "URL":
|
||||
return bool(_clean(reference.url) or _clean(reference.doi))
|
||||
if field == "引用日期":
|
||||
return reference.accessed_date is not None
|
||||
if field == "出版年":
|
||||
return reference.publication_year is not None
|
||||
return True
|
||||
|
||||
|
||||
# --- small helpers -----------------------------------------------------------
|
||||
|
||||
|
||||
def _clean(value: str | None) -> str:
|
||||
"""Whitespace folded, or ``""`` — so a blank field is simply absent."""
|
||||
if value is None:
|
||||
return ""
|
||||
return " ".join(value.split())
|
||||
|
||||
|
||||
def _container(reference: Reference) -> str:
|
||||
"""The journal or book the entry sits in.
|
||||
|
||||
The abbreviation wins when the writer stored one: Springer abbreviates
|
||||
journal titles, and an algorithm cannot abbreviate an arbitrary title
|
||||
correctly, so the 刊名缩写 column is where a human decides it.
|
||||
"""
|
||||
return _clean(reference.container_title_short) or _clean(reference.container_title)
|
||||
|
||||
|
||||
def _volume_issue(reference: Reference) -> str:
|
||||
"""``163(2)``, ``163``, ``(2)`` or nothing."""
|
||||
volume = _clean(reference.volume)
|
||||
issue = _clean(reference.issue)
|
||||
if volume and issue:
|
||||
return f"{volume}({issue})"
|
||||
return volume or (f"({issue})" if issue else "")
|
||||
|
||||
|
||||
def _pages(reference: Reference) -> str:
|
||||
"""``51–59`` with an en dash, or the article number when there is no page."""
|
||||
pages = _clean(reference.pages)
|
||||
if pages:
|
||||
return _PAGE_RANGE.sub(lambda match: f"{match.group(1)}–{match.group(2)}", pages)
|
||||
return _clean(reference.article_number)
|
||||
|
||||
|
||||
def _with_year(clause: str, reference: Reference) -> str:
|
||||
"""``Journal 163(2), 51–59 (2010)`` — the year closes the clause it follows."""
|
||||
if reference.publication_year is None:
|
||||
return clause
|
||||
return f"{clause} ({reference.publication_year})" if clause else f"({reference.publication_year})"
|
||||
|
||||
|
||||
def _join_comma(*parts: str) -> str:
|
||||
return ", ".join(part for part in parts if part)
|
||||
|
||||
|
||||
def _join_space(*parts: str) -> str:
|
||||
return " ".join(part for part in parts if part)
|
||||
+98
-15
@@ -21,6 +21,12 @@ all three behaviours the feature needs:
|
||||
Deleting is done in Python rather than with ``ON DELETE CASCADE`` because TiDB
|
||||
parses foreign keys and then ignores them; the ORM's cascades are the only
|
||||
thing that actually removes dependent rows.
|
||||
|
||||
The 参考文献 list is assembled in the same pass, and by the same rule: a work is
|
||||
numbered where the reader first meets it, however many times it is cited
|
||||
afterwards. The entries themselves are written by :mod:`app.citation_styles`,
|
||||
because how a reference prints is a property of a style rather than of a
|
||||
citation.
|
||||
"""
|
||||
|
||||
from collections import defaultdict
|
||||
@@ -31,6 +37,7 @@ from sqlalchemy import func, or_, select
|
||||
from sqlalchemy import update as sa_update
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.citation_styles import DEFAULT_STYLE, format_reference, missing_fields
|
||||
from app.crud import reference as reference_crud
|
||||
from app.crud.filters import LIKE_ESCAPE, like_pattern
|
||||
from app.models import (
|
||||
@@ -47,6 +54,7 @@ from app.schemas.paper import (
|
||||
PaperDocumentRead,
|
||||
PaperListItem,
|
||||
PaperRead,
|
||||
PaperReferenceRead,
|
||||
ParagraphRead,
|
||||
ParagraphUpdate,
|
||||
SentenceCreate,
|
||||
@@ -329,9 +337,71 @@ def build_document(db: Session, paper: Paper) -> PaperDocumentRead:
|
||||
# --- 3. the union, in ascending position order --------------------------
|
||||
positions = sorted(set(placement_by_sort) | set(sentences_by_sort))
|
||||
|
||||
# --- 4. the literature the document cites, in one query -----------------
|
||||
#
|
||||
# The 参考文献 list is assembled here rather than by the client, for the same
|
||||
# reason the paragraph order is: "which work is number 7" is a rule, and two
|
||||
# implementations of a rule eventually disagree. Formatting needs the rows
|
||||
# themselves — authors, container, pages, DOI — so they are loaded up front,
|
||||
# once, with their contributors.
|
||||
cited_ids = {
|
||||
citation.reference_id
|
||||
for sentence in paper.sentences
|
||||
for citation in sentence.citations
|
||||
if citation.reference_id is not None
|
||||
}
|
||||
cited_references = {
|
||||
row.id: row for row in reference_crud.get_many(db, sorted(cited_ids))
|
||||
}
|
||||
if len(cited_references) != len(cited_ids):
|
||||
# Only reachable if a citation points at a row the library no longer has,
|
||||
# which the foreign key is there to prevent — so it is a warning rather
|
||||
# than a crash, and the entries below print as unlinked.
|
||||
warnings.append(
|
||||
f"有 {len(cited_ids) - len(cited_references)} 条引用指向的文献已不在库中,"
|
||||
"参考文献表中只保留了引用位置。"
|
||||
)
|
||||
|
||||
paragraphs: list[ParagraphRead] = []
|
||||
citations: list[PaperCitationRead] = []
|
||||
citation_index = 0
|
||||
references: list[PaperReferenceRead] = []
|
||||
|
||||
#: Work → its entry in the list above. Keyed by reference id, because that is
|
||||
#: what "the same work" means; a citation with no id at all is its own work
|
||||
#: and is keyed by its citation id so it still gets one entry and one number.
|
||||
entry_by_work: dict[object, PaperReferenceRead] = {}
|
||||
|
||||
def entry_for(citation: PaperSentenceReference) -> PaperReferenceRead:
|
||||
"""The entry this citation belongs to, numbering it on first sight.
|
||||
|
||||
Numbering on first *sight* rather than on first citation is the whole
|
||||
rule: the entries come out in the order the reader meets the works, and a
|
||||
work met again keeps the number it already had.
|
||||
"""
|
||||
key: object = (
|
||||
("reference", citation.reference_id)
|
||||
if citation.reference_id is not None
|
||||
else ("citation", citation.id)
|
||||
)
|
||||
existing = entry_by_work.get(key)
|
||||
if existing is not None:
|
||||
return existing
|
||||
|
||||
reference = (
|
||||
cited_references.get(citation.reference_id)
|
||||
if citation.reference_id is not None
|
||||
else None
|
||||
)
|
||||
entry = PaperReferenceRead(
|
||||
index=len(references) + 1,
|
||||
reference_id=citation.reference_id,
|
||||
text=format_reference(reference),
|
||||
missing=missing_fields(reference),
|
||||
citations=[],
|
||||
)
|
||||
entry_by_work[key] = entry
|
||||
references.append(entry)
|
||||
return entry
|
||||
|
||||
for position in positions:
|
||||
placement = placement_by_sort.get(position)
|
||||
@@ -363,30 +433,43 @@ def build_document(db: Session, paper: Paper) -> PaperDocumentRead:
|
||||
sentences=sentences,
|
||||
)
|
||||
|
||||
# Citations are numbered in reading order, so a marker in the text and
|
||||
# its entry in the 参考文献 list cannot disagree.
|
||||
# Citations are numbered in reading order and by work, so a marker in the
|
||||
# text and its entry in the 参考文献 list cannot disagree.
|
||||
for sentence in sentences:
|
||||
for citation in sentence.citations:
|
||||
citation_index += 1
|
||||
citations.append(
|
||||
PaperCitationRead(
|
||||
index=citation_index,
|
||||
id=citation.id,
|
||||
reference_id=citation.reference_id,
|
||||
quote=citation.quote,
|
||||
sentence_id=sentence.id,
|
||||
sentence_content=sentence.content,
|
||||
paper_template_filed_sort=position,
|
||||
paragraph_name=paragraph.name,
|
||||
)
|
||||
entry = entry_for(citation)
|
||||
row = PaperCitationRead(
|
||||
index=entry.index,
|
||||
id=citation.id,
|
||||
reference_id=citation.reference_id,
|
||||
quote=citation.quote,
|
||||
sentence_id=sentence.id,
|
||||
sentence_content=sentence.content,
|
||||
paper_template_filed_sort=position,
|
||||
paragraph_name=paragraph.name,
|
||||
)
|
||||
citations.append(row)
|
||||
entry.citations.append(row)
|
||||
|
||||
paragraphs.append(paragraph)
|
||||
|
||||
unlinked = sum(1 for entry in references if entry.reference_id is None)
|
||||
if unlinked:
|
||||
warnings.append(
|
||||
f"有 {unlinked} 处引用还没有关联文献库条目,参考文献表中缺少它们的条目。"
|
||||
)
|
||||
|
||||
incomplete = [entry for entry in references if entry.missing]
|
||||
if incomplete:
|
||||
numbers = "、".join(f"[{entry.index}]" for entry in incomplete)
|
||||
warnings.append(f"参考文献 {numbers} 的字段不完整,条目里会缺少相应信息。")
|
||||
|
||||
return PaperDocumentRead(
|
||||
paper=read(paper),
|
||||
paragraphs=paragraphs,
|
||||
citations=citations,
|
||||
references=references,
|
||||
reference_style=DEFAULT_STYLE,
|
||||
warnings=warnings,
|
||||
)
|
||||
|
||||
|
||||
+38
-11
@@ -34,7 +34,7 @@ from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
from collections.abc import Iterator, Sequence
|
||||
from collections.abc import Iterator, Mapping, Sequence
|
||||
from contextlib import contextmanager
|
||||
from datetime import date, datetime
|
||||
from decimal import Decimal
|
||||
@@ -277,19 +277,37 @@ def paragraph_row(paragraph: ParagraphRead, *, preview: int = 80) -> dict:
|
||||
}
|
||||
|
||||
|
||||
def paragraph_text(paragraph: ParagraphRead, *, citations: bool = False) -> str:
|
||||
def paragraph_text(
|
||||
paragraph: ParagraphRead,
|
||||
*,
|
||||
citations: bool = False,
|
||||
index_by_citation: Mapping[int, int] | None = None,
|
||||
) -> str:
|
||||
"""Print one paragraph exactly as the document renders it.
|
||||
|
||||
``separator_before`` is added, not invented: the server decided what
|
||||
belongs at each seam, so a tool result and the paper view agree on where
|
||||
the spaces go. Nothing here adds spacing of its own.
|
||||
|
||||
A marker's number comes from ``index_by_citation`` — the citation's *work*
|
||||
number as the whole document assigned it, not its position in this sentence —
|
||||
so what is printed in the text matches the 参考文献 list it points at. Read
|
||||
without that map there is no document to number against, and the marker
|
||||
falls back to the citation's place in the sentence.
|
||||
"""
|
||||
parts: list[str] = []
|
||||
for sentence in paragraph.sentences:
|
||||
parts.append(sentence.separator_before + sentence.content)
|
||||
if citations and sentence.citations:
|
||||
markers = ",".join(str(index) for index in range(1, len(sentence.citations) + 1))
|
||||
parts.append(f"[{markers}]")
|
||||
numbers = [
|
||||
str(
|
||||
index_by_citation.get(citation.id, position)
|
||||
if index_by_citation is not None
|
||||
else position
|
||||
)
|
||||
for position, citation in enumerate(sentence.citations, start=1)
|
||||
]
|
||||
parts.append(f"[{','.join(numbers)}]")
|
||||
return "".join(parts)
|
||||
|
||||
|
||||
@@ -306,22 +324,31 @@ def document_text(
|
||||
three rules the paper view renders by, applied here so a single tool call
|
||||
can hand a model the finished manuscript.
|
||||
"""
|
||||
# Citation id → the number of the work it cites, so the markers printed in
|
||||
# the text are the numbers the list below uses.
|
||||
index_by_citation = {row.id: row.index for row in document.citations}
|
||||
|
||||
lines: list[str] = []
|
||||
for paragraph in document.paragraphs:
|
||||
body = paragraph_text(paragraph, citations=citations)
|
||||
body = paragraph_text(
|
||||
paragraph, citations=citations, index_by_citation=index_by_citation
|
||||
)
|
||||
if not body and not include_empty:
|
||||
continue
|
||||
lines.append(paragraph.name if paragraph.matched and paragraph.name else "未设定")
|
||||
lines.append(body)
|
||||
lines.append("")
|
||||
|
||||
if citations and document.citations:
|
||||
if citations and document.references:
|
||||
# The entries, not the quotes: a 参考文献 list is a bibliography, and the
|
||||
# one assembled above already carries each work once, numbered as the
|
||||
# text numbers it. A work whose library row is missing prints the gap
|
||||
# rather than a fabricated entry.
|
||||
lines.append("参考文献")
|
||||
for citation in document.citations:
|
||||
reference = (
|
||||
f"[{citation.reference_id}]" if citation.reference_id else ""
|
||||
)
|
||||
lines.append(f"[{citation.index}]{reference} {citation.quote}")
|
||||
for entry in document.references:
|
||||
text = entry.text or "(未关联文献库条目)"
|
||||
note = f"(缺 {'、'.join(entry.missing)})" if entry.missing else ""
|
||||
lines.append(f"[{entry.index}] {text}{note}")
|
||||
lines.append("")
|
||||
|
||||
text = "\n".join(lines).rstrip("\n")
|
||||
|
||||
@@ -14,6 +14,7 @@ from app.schemas.paper import (
|
||||
PaperDocumentRead,
|
||||
PaperListItem,
|
||||
PaperRead,
|
||||
PaperReferenceRead,
|
||||
PaperStatus,
|
||||
PaperUpdate,
|
||||
ParagraphListRead,
|
||||
@@ -75,6 +76,7 @@ __all__ = [
|
||||
"PaperDocumentRead",
|
||||
"PaperListItem",
|
||||
"PaperRead",
|
||||
"PaperReferenceRead",
|
||||
"PaperStatus",
|
||||
"PaperUpdate",
|
||||
"ParagraphListRead",
|
||||
|
||||
@@ -8,8 +8,8 @@ Three shapes of payload live here:
|
||||
reading every sentence of it and writing the whole set back, so the update
|
||||
schema is a full replacement;
|
||||
* the **document** — what the reader sees: the template's paragraphs in order,
|
||||
each carrying the sentences stored at its position, plus the flat citation
|
||||
list for the 参考文献 block.
|
||||
each carrying the sentences stored at its position, plus the 参考文献 list,
|
||||
already formatted in one citation style.
|
||||
|
||||
Text normalisation is deliberately strict, because the two sides of the wire
|
||||
have to agree on what counts as empty:
|
||||
@@ -27,6 +27,8 @@ from typing import Literal
|
||||
|
||||
from pydantic import BaseModel, ConfigDict, Field, field_validator
|
||||
|
||||
from app.citation_styles import DEFAULT_STYLE as DEFAULT_REFERENCE_STYLE
|
||||
|
||||
#: Writing states, mirroring :data:`app.models.paper.PAPER_STATUSES`. Kept as a
|
||||
#: literal so the generated OpenAPI document describes the enum for clients.
|
||||
PaperStatus = Literal["draft", "writing", "done"]
|
||||
@@ -200,11 +202,13 @@ class ParagraphRead(BaseModel):
|
||||
|
||||
|
||||
class PaperCitationRead(BaseModel):
|
||||
"""One citation as it appears in the paper's 参考文献 list.
|
||||
"""One citation — one place in the text where one work is cited.
|
||||
|
||||
``index`` is the number shown in the text as ``[index]``; it counts
|
||||
citations in reading order across the whole document, so the list and the
|
||||
markers cannot disagree.
|
||||
A citation is not a row of the 参考文献 list, and this is the difference that
|
||||
matters: a paper that cites the same article in three sentences has three
|
||||
citations and **one** entry, so ``index`` is the number of the *work* and is
|
||||
shared by all three. The in-text markers and the list therefore cannot
|
||||
disagree about what ``[7]`` means.
|
||||
"""
|
||||
|
||||
index: int
|
||||
@@ -217,6 +221,30 @@ class PaperCitationRead(BaseModel):
|
||||
paragraph_name: str | None = None
|
||||
|
||||
|
||||
class PaperReferenceRead(BaseModel):
|
||||
"""One entry of the 参考文献 list: one work, however often it is cited.
|
||||
|
||||
``text`` is the entry as it prints — the whole point of the list — and it is
|
||||
assembled by :mod:`app.citation_styles` rather than by a client, so the paper
|
||||
view, an export and an agent all print the same bibliography.
|
||||
"""
|
||||
|
||||
#: The number the text shows as ``[index]``, assigned in order of first
|
||||
#: appearance so the list reads in the order the reader meets the works.
|
||||
index: int
|
||||
#: The library row it came from, or ``None`` for a citation written before
|
||||
#: the literature was entered.
|
||||
reference_id: int | None
|
||||
#: The formatted entry, or ``""`` when there is no library row to print.
|
||||
text: str
|
||||
#: Which parts a complete entry still lacks, in Chinese — 责任者、出版年、DOI…
|
||||
#: Empty for a complete entry, and empty for an unlinked one, where the
|
||||
#: question is not what is missing but what this is.
|
||||
missing: list[str] = Field(default_factory=list)
|
||||
#: Every place it is cited, in reading order.
|
||||
citations: list[PaperCitationRead] = Field(default_factory=list)
|
||||
|
||||
|
||||
class PaperBase(BaseModel):
|
||||
"""Shared body of the paper create payload."""
|
||||
|
||||
@@ -342,8 +370,18 @@ class PaperDocumentRead(BaseModel):
|
||||
#: template or a sentence mentions appears exactly once, so an empty
|
||||
#: paragraph is still a paragraph — the structure survives with no content.
|
||||
paragraphs: list[ParagraphRead]
|
||||
#: Citations in reading order, numbered to match the in-text markers.
|
||||
#: Citations in reading order, each carrying the number of the work it cites.
|
||||
#: One row per place in the text, not per work: this is what renders the
|
||||
#: in-text markers.
|
||||
citations: list[PaperCitationRead]
|
||||
#: The 参考文献 list: one entry per work, numbered in order of first
|
||||
#: appearance, already formatted. A client prints these and does not group,
|
||||
#: sort or assemble them — two implementations of the same rules would
|
||||
#: eventually print two different bibliographies.
|
||||
references: list[PaperReferenceRead] = Field(default_factory=list)
|
||||
#: The citation style the entries were written in, so a client can name it
|
||||
#: without hard-coding the choice (see ``app.citation_styles``).
|
||||
reference_style: str = DEFAULT_REFERENCE_STYLE
|
||||
#: Anything the reader should be told about the document as a whole, e.g.
|
||||
#: a template that places two fields at the same position.
|
||||
warnings: list[str] = Field(default_factory=list)
|
||||
|
||||
@@ -0,0 +1,435 @@
|
||||
"""Check the citation formatter against one reference of every type.
|
||||
|
||||
Run it with no server and no database::
|
||||
|
||||
.venv/bin/python scripts/check_citation_styles.py
|
||||
|
||||
The formatter is pure — a reference in, a printed entry out — so unlike the
|
||||
``smoke_*`` scripts this one needs nothing running. It builds a reference of each
|
||||
document type in memory, asserts the exact entry Springer's basic style calls
|
||||
for, and exits non-zero on the first entry that does not match.
|
||||
|
||||
Why it exists: the style has one branch per document type, and a branch that is
|
||||
wrong prints something that *looks* like a bibliography entry rather than
|
||||
failing loudly. A paper citing a patent would show a plausible-looking,
|
||||
incorrect line. Nineteen assertions is a cheap way to keep that from happening.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import sys
|
||||
from datetime import date
|
||||
from pathlib import Path
|
||||
|
||||
# Running this as a plain script puts scripts/ on sys.path, not backend/, so
|
||||
# `import app` would fail. Anchor to the backend directory instead.
|
||||
BACKEND_DIR = Path(__file__).resolve().parents[1]
|
||||
if str(BACKEND_DIR) not in sys.path:
|
||||
sys.path.insert(0, str(BACKEND_DIR))
|
||||
|
||||
from app.citation_styles import ( # noqa: E402
|
||||
DEFAULT_STYLE,
|
||||
STYLES,
|
||||
format_reference,
|
||||
missing_fields,
|
||||
)
|
||||
from app.models import Reference, ReferenceAuthor # noqa: E402
|
||||
|
||||
_checks = 0
|
||||
|
||||
|
||||
def check(label: str, actual: str, expected: str) -> None:
|
||||
"""Assert one printed entry, showing both sides when it differs."""
|
||||
global _checks
|
||||
_checks += 1
|
||||
if actual != expected:
|
||||
raise AssertionError(
|
||||
f"{label}\n expected: {expected}\n actual: {actual}"
|
||||
)
|
||||
print(f" ok {label}")
|
||||
|
||||
|
||||
def author(name: str, family: str | None = None, given: str | None = None,
|
||||
role: str = "author") -> ReferenceAuthor:
|
||||
"""One contributor, built in memory — no session, no flush."""
|
||||
return ReferenceAuthor(
|
||||
name=name, family_name=family, given_name=given, role=role, sort=0
|
||||
)
|
||||
|
||||
|
||||
def reference(**fields) -> Reference:
|
||||
"""A reference with sensible filled-in defaults, overridden per case."""
|
||||
base: dict = {
|
||||
"type": "journal-article",
|
||||
"title": "题名",
|
||||
"authors": [author("Smith J", "Smith", "J")],
|
||||
}
|
||||
base.update(fields)
|
||||
authors = base.pop("authors")
|
||||
row = Reference(**base)
|
||||
row.authors = authors
|
||||
return row
|
||||
|
||||
|
||||
def main() -> int:
|
||||
print(f"style: {DEFAULT_STYLE}(可用:{'、'.join(sorted(STYLES))})")
|
||||
|
||||
print("\n1. a journal article: names, title, journal, volume(issue), pages, year, DOI")
|
||||
check(
|
||||
"journal article",
|
||||
format_reference(
|
||||
reference(
|
||||
title="The art of writing a scientific article",
|
||||
container_title="Journal of Science Communication",
|
||||
container_title_short="J. Sci. Commun.",
|
||||
volume="163",
|
||||
issue="2",
|
||||
pages="51-59",
|
||||
publication_year=2010,
|
||||
doi="10.1016/j.Sc.2010.00372",
|
||||
authors=[
|
||||
author("Van der Geer J", "Van der Geer", "J"),
|
||||
author("Hanraads JAJ", "Hanraads", "JAJ"),
|
||||
author("Lupton RA", "Lupton", "RA"),
|
||||
],
|
||||
)
|
||||
),
|
||||
"Van der Geer, J., Hanraads, J.A.J., Lupton, R.A.: The art of writing a "
|
||||
"scientific article. J. Sci. Commun. 163(2), 51–59 (2010). "
|
||||
"https://doi.org/10.1016/j.Sc.2010.00372",
|
||||
)
|
||||
|
||||
print("\n2. the abbreviation wins when the writer stored one, and a range gets an en dash")
|
||||
entry = format_reference(
|
||||
reference(
|
||||
title="A paper",
|
||||
container_title="Full Journal Name",
|
||||
container_title_short=None,
|
||||
volume="9",
|
||||
pages="1000-1010",
|
||||
publication_year=2020,
|
||||
)
|
||||
)
|
||||
check(
|
||||
"full 刊名 when there is no 缩写",
|
||||
entry,
|
||||
"Smith, J.: A paper. Full Journal Name 9, 1000–1010 (2020)",
|
||||
)
|
||||
|
||||
print("\n3. more than six contributors become three and et al.")
|
||||
check(
|
||||
"seven authors",
|
||||
format_reference(
|
||||
reference(
|
||||
title="A crowded paper",
|
||||
volume="1",
|
||||
pages="1-2",
|
||||
publication_year=2021,
|
||||
authors=[
|
||||
author(f"Family{index} A", f"Family{index}", "A")
|
||||
for index in range(1, 8)
|
||||
],
|
||||
)
|
||||
),
|
||||
"Family1, A., Family2, A., Family3, A., et al.: A crowded paper. "
|
||||
"1, 1–2 (2021)",
|
||||
)
|
||||
check(
|
||||
"six authors are all named",
|
||||
format_reference(
|
||||
reference(
|
||||
title="Six",
|
||||
publication_year=2021,
|
||||
authors=[
|
||||
author(f"Family{index} A", f"Family{index}", "A")
|
||||
for index in range(1, 7)
|
||||
],
|
||||
)
|
||||
),
|
||||
"Family1, A., Family2, A., Family3, A., Family4, A., Family5, A., "
|
||||
"Family6, A.: Six (2021)",
|
||||
)
|
||||
|
||||
print("\n4. names: initials, blocks of initials, hyphens, and no halves at all")
|
||||
check(
|
||||
"given names become initials",
|
||||
format_reference(reference(title="T", authors=[author("Yong Ming Li", "Li", "Yong Ming")], publication_year=2020)),
|
||||
"Li, Y.M.: T (2020)",
|
||||
)
|
||||
check(
|
||||
"a block of initials is expanded letter by letter",
|
||||
format_reference(reference(title="T", authors=[author("Lai KK", "Lai", "KK")], publication_year=2020)),
|
||||
"Lai, K.K.: T (2020)",
|
||||
)
|
||||
check(
|
||||
"a hyphenated given name keeps its hyphen",
|
||||
format_reference(reference(title="T", authors=[author("Dupont JL", "Dupont", "Jean-Luc")], publication_year=2020)),
|
||||
"Dupont, J.-L.: T (2020)",
|
||||
)
|
||||
check(
|
||||
"an institutional author is printed as stored",
|
||||
format_reference(reference(title="T", authors=[author("世界卫生组织")], publication_year=2020)),
|
||||
"世界卫生组织: T (2020)",
|
||||
)
|
||||
check(
|
||||
"a CJK name with no halves is not romanised by guesswork",
|
||||
format_reference(reference(title="T", authors=[author("张三")], publication_year=2020)),
|
||||
"张三: T (2020)",
|
||||
)
|
||||
check(
|
||||
"a CJK name keeps its printed form even with halves filled in",
|
||||
format_reference(
|
||||
reference(
|
||||
title="T",
|
||||
authors=[author("张三", "张", "三")],
|
||||
publication_year=2020,
|
||||
)
|
||||
),
|
||||
"张三: T (2020)",
|
||||
)
|
||||
check(
|
||||
"editors of a book are marked (ed.)",
|
||||
format_reference(
|
||||
reference(
|
||||
type="book",
|
||||
title="Edited volume",
|
||||
publisher="Springer",
|
||||
publisher_place="Cham",
|
||||
publication_year=2021,
|
||||
authors=[author("Jones BS", "Jones", "BS", role="editor")],
|
||||
)
|
||||
),
|
||||
"Jones, B.S. (ed.): Edited volume. Springer, Cham (2021)",
|
||||
)
|
||||
|
||||
print("\n5. every other document type")
|
||||
check(
|
||||
"book with an edition and a series",
|
||||
format_reference(
|
||||
reference(
|
||||
type="book",
|
||||
title="The Elements of Style",
|
||||
edition="4th edn",
|
||||
series_title="Style Guides",
|
||||
series_number="7",
|
||||
publisher="Longman",
|
||||
publisher_place="New York",
|
||||
publication_year=2000,
|
||||
authors=[author("Strunk W", "Strunk", "W")],
|
||||
)
|
||||
),
|
||||
"Strunk, W.: The Elements of Style, 4th edn. Style Guides, 7. "
|
||||
"Longman, New York (2000)",
|
||||
)
|
||||
check(
|
||||
"book chapter, with the book's editors marked",
|
||||
format_reference(
|
||||
reference(
|
||||
type="book-chapter",
|
||||
title="How to prepare an electronic version of your article",
|
||||
container_title="Introduction to the Electronic Age",
|
||||
pages="281-304",
|
||||
publisher="E-Publishing Inc.",
|
||||
publisher_place="New York",
|
||||
publication_year=2009,
|
||||
authors=[
|
||||
author("Mettam GR", "Mettam", "GR"),
|
||||
author("Adams LB", "Adams", "LB"),
|
||||
author("Jones BS", "Jones", "BS", role="editor"),
|
||||
],
|
||||
)
|
||||
),
|
||||
"Mettam, G.R., Adams, L.B.: How to prepare an electronic version of your "
|
||||
"article. In: Jones, B.S. (ed.) Introduction to the Electronic Age, "
|
||||
"pp. 281–304. E-Publishing Inc., New York (2009)",
|
||||
)
|
||||
check(
|
||||
"conference paper",
|
||||
format_reference(
|
||||
reference(
|
||||
type="conference-paper",
|
||||
title="Crowdsourcing in the tourism industry",
|
||||
container_title="Proceedings of the 3rd International Conference on Tourism",
|
||||
pages="1-10",
|
||||
publisher="Springer",
|
||||
publisher_place="Cham",
|
||||
publication_year=2019,
|
||||
authors=[author("Garrigos-Simon FJ", "Garrigos-Simon", "FJ")],
|
||||
)
|
||||
),
|
||||
"Garrigos-Simon, F.J.: Crowdsourcing in the tourism industry. In: "
|
||||
"Proceedings of the 3rd International Conference on Tourism, pp. 1–10. "
|
||||
"Springer, Cham (2019)",
|
||||
)
|
||||
check(
|
||||
"conference paper that only knows its meeting",
|
||||
format_reference(
|
||||
reference(
|
||||
type="conference-paper",
|
||||
title="A meeting paper",
|
||||
event_title="第 20 届管理学年会",
|
||||
event_place="北京",
|
||||
publication_year=2022,
|
||||
)
|
||||
),
|
||||
"Smith, J.: A meeting paper. In: 第 20 届管理学年会. 北京 (2022)",
|
||||
)
|
||||
check(
|
||||
"thesis",
|
||||
format_reference(
|
||||
reference(
|
||||
type="thesis",
|
||||
title="A dissertation",
|
||||
publisher="清华大学",
|
||||
publisher_place="北京",
|
||||
publication_year=2020,
|
||||
)
|
||||
),
|
||||
"Smith, J.: A dissertation. Thesis, 清华大学 (2020)",
|
||||
)
|
||||
check(
|
||||
"patent",
|
||||
format_reference(
|
||||
reference(
|
||||
type="patent",
|
||||
title="一种基于多层聚类的技术识别方法",
|
||||
patent_country="中国",
|
||||
patent_number="CN114000000A",
|
||||
publication_year=2023,
|
||||
)
|
||||
),
|
||||
"Smith, J.: 一种基于多层聚类的技术识别方法. 中国 Patent CN114000000A (2023)",
|
||||
)
|
||||
check(
|
||||
"standard",
|
||||
format_reference(
|
||||
reference(
|
||||
type="standard",
|
||||
title="信息与文献 参考文献著录规则",
|
||||
standard_number="GB/T 7714-2015",
|
||||
publisher="中国标准出版社",
|
||||
publisher_place="北京",
|
||||
publication_year=2015,
|
||||
authors=[],
|
||||
)
|
||||
),
|
||||
"信息与文献 参考文献著录规则. GB/T 7714-2015. 中国标准出版社, 北京 (2015)",
|
||||
)
|
||||
check(
|
||||
"report",
|
||||
format_reference(
|
||||
reference(
|
||||
type="report",
|
||||
title="Annual technology review",
|
||||
report_number="NREL/TP-5000-12345",
|
||||
publisher="NREL",
|
||||
publisher_place="Golden",
|
||||
publication_year=2012,
|
||||
)
|
||||
),
|
||||
"Smith, J.: Annual technology review. NREL/TP-5000-12345, NREL, Golden (2012)",
|
||||
)
|
||||
check(
|
||||
"web page, with the day it was read",
|
||||
format_reference(
|
||||
reference(
|
||||
type="web-page",
|
||||
title="Cancer statistics for the UK",
|
||||
url="https://www.cancerresearchuk.org/health-professional/cancer-statistics",
|
||||
publication_year=2021,
|
||||
accessed_date=date(2021, 5, 12),
|
||||
authors=[author("Cancer Research UK")],
|
||||
)
|
||||
),
|
||||
"Cancer Research UK: Cancer statistics for the UK. "
|
||||
"https://www.cancerresearchuk.org/health-professional/cancer-statistics "
|
||||
"(2021). Accessed 12 May 2021",
|
||||
)
|
||||
check(
|
||||
"dataset",
|
||||
format_reference(
|
||||
reference(
|
||||
type="dataset",
|
||||
title="Patent citation network",
|
||||
url="https://doi.org/10.6084/m9.figshare.1234567",
|
||||
publication_year=2024,
|
||||
)
|
||||
),
|
||||
"Smith, J.: Patent citation network. Dataset (2024). "
|
||||
"https://doi.org/10.6084/m9.figshare.1234567",
|
||||
)
|
||||
check(
|
||||
"preprint, which has no DOI yet",
|
||||
format_reference(
|
||||
reference(
|
||||
type="preprint",
|
||||
title="A preprint",
|
||||
arxiv_id="arXiv:2405.12345",
|
||||
publication_year=2024,
|
||||
)
|
||||
),
|
||||
"Smith, J.: A preprint. Preprint arXiv:2405.12345 (2024)",
|
||||
)
|
||||
check(
|
||||
"newspaper article",
|
||||
format_reference(
|
||||
reference(
|
||||
type="newspaper-article",
|
||||
title="A news story",
|
||||
container_title="The Times",
|
||||
pages="12",
|
||||
publication_year=2020,
|
||||
)
|
||||
),
|
||||
"Smith, J.: A news story. The Times, 12 (2020)",
|
||||
)
|
||||
check(
|
||||
"a subtitle rejoins its title",
|
||||
format_reference(
|
||||
reference(
|
||||
title="技术惯性与冲量的耦合机制",
|
||||
subtitle="基于科学与技术融合网络的实证分析",
|
||||
volume="198",
|
||||
pages="122-141",
|
||||
publication_year=2024,
|
||||
)
|
||||
),
|
||||
"Smith, J.: 技术惯性与冲量的耦合机制: 基于科学与技术融合网络的实证分析. "
|
||||
"198, 122–141 (2024)",
|
||||
)
|
||||
|
||||
print("\n6. a gap is reported, not papered over")
|
||||
check(
|
||||
"an entry with no year prints no invented year",
|
||||
format_reference(reference(title="No year", volume="1", pages="1-2")),
|
||||
"Smith, J.: No year. 1, 1–2",
|
||||
)
|
||||
missing = missing_fields(
|
||||
reference(title="No year", volume=None, pages=None, container_title=None)
|
||||
)
|
||||
check("the missing fields are named in Chinese", "、".join(missing), "刊名、卷期页码、出版年")
|
||||
check(
|
||||
"a complete entry reports nothing missing",
|
||||
"、".join(missing_fields(reference(
|
||||
title="Complete",
|
||||
container_title="A Journal",
|
||||
volume="1",
|
||||
pages="1-2",
|
||||
publication_year=2020,
|
||||
))),
|
||||
"",
|
||||
)
|
||||
check(
|
||||
"a web page without a URL is told so, in the style's own terms",
|
||||
"、".join(missing_fields(reference(
|
||||
type="web-page", title="No address", url=None, doi=None, accessed_date=None
|
||||
))),
|
||||
"URL、引用日期",
|
||||
)
|
||||
|
||||
print(f"\nall {_checks} checks passed")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -165,13 +165,36 @@ def main() -> int:
|
||||
check("citations numbered", [c["sort"] for c in paragraph["sentences"][1]["citations"]] == [1, 2])
|
||||
check("three citations in the paper", len(document["citations"]) == 3)
|
||||
check(
|
||||
"citation index is reading order",
|
||||
[c["index"] for c in document["citations"]] == [1, 2, 3],
|
||||
"a citation carries the number of its work, not of itself",
|
||||
[c["index"] for c in document["citations"]] == [1, 1, 2],
|
||||
str([c["index"] for c in document["citations"]]),
|
||||
)
|
||||
|
||||
print("5. the 参考文献 list: one entry per work, in Springer's basic style")
|
||||
check(
|
||||
"two works — the article cited twice, and the unlinked quote",
|
||||
len(document["references"]) == 2,
|
||||
str(len(document["references"])),
|
||||
)
|
||||
first, second = document["references"]
|
||||
check("both places that cite the article share its entry", len(first["citations"]) == 2)
|
||||
check(
|
||||
"the entry is a bibliography line, not the quote",
|
||||
first["text"]
|
||||
== "测试作者: 用于验证引用链路的文献. 测试期刊 (2024)",
|
||||
first["text"],
|
||||
)
|
||||
check(
|
||||
"what a complete entry still lacks is named",
|
||||
first["missing"] == ["卷期页码"],
|
||||
str(first["missing"]),
|
||||
)
|
||||
check("the unlinked quote is its own entry", second["reference_id"] is None)
|
||||
check("and prints no fabricated entry", second["text"] == "", second["text"])
|
||||
check("the style is reported", document["reference_style"] == "springer", document["reference_style"])
|
||||
check("sentence template stamped", paragraph["sentences"][0]["template_id"] == wide["id"])
|
||||
|
||||
print("5. explicit sorts decide the order, not the order they were sent")
|
||||
print("6. explicit sorts decide the order, not the order they were sent")
|
||||
second_sort = document["paragraphs"][1]["paper_template_filed_sort"]
|
||||
reordered = call(
|
||||
"PUT",
|
||||
@@ -202,7 +225,7 @@ def main() -> int:
|
||||
{"sentences": []},
|
||||
)
|
||||
|
||||
print("6. the seam between sentences depends on the language")
|
||||
print("7. the seam between sentences depends on the language")
|
||||
# Chinese needs nothing after 。; English needs a space, or two
|
||||
# sentences print as `First.Second.`
|
||||
mixed = call(
|
||||
@@ -244,7 +267,7 @@ def main() -> int:
|
||||
# Clear it again so the counts asserted below stay meaningful.
|
||||
call("PUT", f"/papers/{paper['id']}/paragraphs/{second_sort}", {"sentences": []})
|
||||
|
||||
print("7. reject a citation with no quote")
|
||||
print("8. reject a citation with no quote")
|
||||
bad = call(
|
||||
"PUT",
|
||||
f"/papers/{paper['id']}/paragraphs/{first_sort}",
|
||||
@@ -262,7 +285,7 @@ def main() -> int:
|
||||
)
|
||||
check("citation without content refused", "detail" in bad)
|
||||
|
||||
print("8. a sentence with no paragraph in the template survives a switch")
|
||||
print("9. a sentence with no paragraph in the template survives a switch")
|
||||
# A position neither template defines, so the check means the same
|
||||
# thing before and after the switch below.
|
||||
orphan_sort = (
|
||||
@@ -290,7 +313,7 @@ def main() -> int:
|
||||
p for p in document["paragraphs"] if p["paper_template_filed_sort"] == orphan_sort
|
||||
)["name"] is None)
|
||||
|
||||
print("9. switch the template")
|
||||
print("10. switch the template")
|
||||
switched = call("PATCH", f"/papers/{paper['id']}", {"template_id": narrow["id"]})
|
||||
check("template changed", switched["template_id"] == narrow["id"])
|
||||
document = call("GET", f"/papers/{paper['id']}/document")
|
||||
@@ -320,7 +343,7 @@ def main() -> int:
|
||||
),
|
||||
)
|
||||
|
||||
print("10. move one paragraph onto another position")
|
||||
print("11. move one paragraph onto another position")
|
||||
document = call(
|
||||
"PUT",
|
||||
f"/papers/{paper['id']}/paragraphs/{orphan_sort}",
|
||||
@@ -335,18 +358,18 @@ def main() -> int:
|
||||
all(p["paper_template_filed_sort"] != orphan_sort for p in document["paragraphs"]),
|
||||
)
|
||||
|
||||
print("11. paper list reports progress")
|
||||
print("12. paper list reports progress")
|
||||
listing = call("GET", f"/papers?keyword=冒烟&status=writing")
|
||||
check("found by keyword and status", listing["total"] == 1, str(listing["total"]))
|
||||
row = listing["items"][0]
|
||||
check("paragraph count", row["paragraph_count"] == 1, str(row["paragraph_count"]))
|
||||
check("sentence count", row["sentence_count"] == 3, str(row["sentence_count"]))
|
||||
|
||||
print("12. a template in use cannot be deleted")
|
||||
print("13. a template in use cannot be deleted")
|
||||
conflict = call("DELETE", f"/templates/{narrow['id']}", expect=409)
|
||||
check("template delete refused", "正被论文使用" in conflict["detail"], conflict["detail"])
|
||||
|
||||
print("13. single sentence edit and delete")
|
||||
print("14. single sentence edit and delete")
|
||||
sentence_id = target["sentences"][0]["id"]
|
||||
updated = call(
|
||||
"PATCH",
|
||||
@@ -362,7 +385,7 @@ def main() -> int:
|
||||
sum(len(p["sentences"]) for p in document["paragraphs"]) == 2,
|
||||
)
|
||||
|
||||
print("14. a paper with no template still works")
|
||||
print("15. a paper with no template still works")
|
||||
bare = call(
|
||||
"POST",
|
||||
"/papers",
|
||||
@@ -385,7 +408,7 @@ def main() -> int:
|
||||
call("DELETE", f"/papers/{bare['id']}", expect=204)
|
||||
created_papers.remove(bare["id"])
|
||||
|
||||
print("15. delete the paper")
|
||||
print("16. delete the paper")
|
||||
call("DELETE", f"/papers/{paper['id']}", expect=204)
|
||||
created_papers.clear()
|
||||
for reference_id in created_references:
|
||||
|
||||
@@ -15,6 +15,12 @@ The order of the first two steps is the point of the tag library rather than an
|
||||
accident of the script: **tags are made first and applied second**. A reference
|
||||
is created *with* tag ids, never with tag names, so a typo cannot invent a label
|
||||
— which is what step 4 checks.
|
||||
|
||||
**Every entry this script creates carries a token in its title, its author and
|
||||
its tag names.** The library it runs against is a real one and may hold hundreds
|
||||
of entries, so "the search found one row" is only a meaningful assertion about
|
||||
rows this run made. The token is what makes each count below a statement about
|
||||
this run rather than about the library's size.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -24,10 +30,21 @@ import sys
|
||||
import urllib.error
|
||||
import urllib.parse
|
||||
import urllib.request
|
||||
import uuid
|
||||
from typing import Any
|
||||
|
||||
BASE = "http://127.0.0.1:8000/api"
|
||||
|
||||
#: Stamped into every entry this run creates, so each search below can be scoped
|
||||
#: to this run instead of to an empty database. Short and uppercase: it travels
|
||||
#: in titles, in an author name and in tag names, and shows up in failure output.
|
||||
TOKEN = uuid.uuid4().hex[:6].upper()
|
||||
|
||||
#: A second token, carried by one contributor's *name* only. Titles and tag names
|
||||
#: carry ``TOKEN``, so searching for it finds every row this run made; finding a
|
||||
#: single row by author needs a string that is in exactly one place.
|
||||
AUTHOR_TOKEN = f"AU{TOKEN}"
|
||||
|
||||
_checks = 0
|
||||
|
||||
|
||||
@@ -73,11 +90,19 @@ def main() -> int:
|
||||
survey = call(
|
||||
"POST",
|
||||
"/reference-tags",
|
||||
{"name": " 综述 ", "color": "rgb(64, 158, 255)", "note": "综述性文献"},
|
||||
{
|
||||
"name": f" 综述-{TOKEN} ",
|
||||
"color": "rgb(64, 158, 255)",
|
||||
"note": "综述性文献",
|
||||
},
|
||||
expect=201,
|
||||
)
|
||||
created_tags.append(survey["id"])
|
||||
check("a name is trimmed to one spelling", survey["name"] == "综述", survey["name"])
|
||||
check(
|
||||
"a name is trimmed to one spelling",
|
||||
survey["name"] == f"综述-{TOKEN}",
|
||||
survey["name"],
|
||||
)
|
||||
check(
|
||||
"a colour is canonicalised",
|
||||
survey["color"] == "#409EFF",
|
||||
@@ -88,18 +113,27 @@ def main() -> int:
|
||||
must_read = call(
|
||||
"POST",
|
||||
"/reference-tags",
|
||||
{"name": "必读", "color": "#f56c6c"},
|
||||
{"name": f"必读-{TOKEN}", "color": "#f56c6c"},
|
||||
expect=201,
|
||||
)
|
||||
created_tags.append(must_read["id"])
|
||||
check("the second tag is stored", must_read["name"] == "必读")
|
||||
check("the second tag is stored", must_read["name"] == f"必读-{TOKEN}")
|
||||
|
||||
print("2. a tag name is unique, and only a real colour is accepted")
|
||||
duplicate = call(
|
||||
"POST", "/reference-tags", {"name": "综述"}, expect=409
|
||||
"POST", "/reference-tags", {"name": f"综述-{TOKEN}"}, expect=409
|
||||
)
|
||||
check(
|
||||
"the refusal names the label",
|
||||
TOKEN in duplicate["detail"],
|
||||
duplicate["detail"],
|
||||
)
|
||||
call(
|
||||
"POST",
|
||||
"/reference-tags",
|
||||
{"name": f"怪颜色-{TOKEN}", "color": "blue"},
|
||||
expect=422,
|
||||
)
|
||||
check("the refusal names the label", "综述" in duplicate["detail"], duplicate["detail"])
|
||||
call("POST", "/reference-tags", {"name": "怪颜色", "color": "blue"}, expect=422)
|
||||
call("POST", "/reference-tags", {"name": " "}, expect=422)
|
||||
check("a blank name and a non-colour are refused", True)
|
||||
|
||||
@@ -109,7 +143,7 @@ def main() -> int:
|
||||
"/references",
|
||||
{
|
||||
"type": "journal-article",
|
||||
"title": "技术惯性与冲量的耦合机制",
|
||||
"title": f"技术惯性与冲量的耦合机制({TOKEN})",
|
||||
"subtitle": "基于科学与技术融合网络的实证分析",
|
||||
"title_translated": "Coupling inertia and impulse in technology evolution",
|
||||
"container_title": "Technological Forecasting and Social Change",
|
||||
@@ -126,7 +160,11 @@ def main() -> int:
|
||||
"authors": [
|
||||
{"name": "张三", "family_name": "张", "given_name": "三"},
|
||||
{"name": "李四"},
|
||||
{"name": "Wang Wu", "family_name": "Wang", "given_name": "Wu"},
|
||||
{
|
||||
"name": f"Wang Wu {AUTHOR_TOKEN}",
|
||||
"family_name": "Wang",
|
||||
"given_name": "Wu",
|
||||
},
|
||||
{"name": "世界卫生组织", "role": "compiler"},
|
||||
],
|
||||
},
|
||||
@@ -137,7 +175,8 @@ def main() -> int:
|
||||
check("four contributors stored", len(article["authors"]) == 4)
|
||||
check(
|
||||
"they keep the order they were sent in",
|
||||
[a["name"] for a in article["authors"]] == ["张三", "李四", "Wang Wu", "世界卫生组织"],
|
||||
[a["name"] for a in article["authors"]]
|
||||
== ["张三", "李四", f"Wang Wu {AUTHOR_TOKEN}", "世界卫生组织"],
|
||||
str([a["name"] for a in article["authors"]]),
|
||||
)
|
||||
check(
|
||||
@@ -151,7 +190,8 @@ def main() -> int:
|
||||
check("not cited yet", article["citation_count"] == 0)
|
||||
check(
|
||||
"both tags are on the row",
|
||||
sorted(tag["name"] for tag in article["tags"]) == ["必读", "综述"],
|
||||
sorted(tag["name"] for tag in article["tags"])
|
||||
== [f"必读-{TOKEN}", f"综述-{TOKEN}"],
|
||||
str(article["tags"]),
|
||||
)
|
||||
|
||||
@@ -159,11 +199,15 @@ def main() -> int:
|
||||
missing_tag = call(
|
||||
"POST",
|
||||
"/references",
|
||||
{"title": "引用了不存在的标签", "type": "book", "tag_ids": [999999]},
|
||||
{
|
||||
"title": f"引用了不存在的标签{TOKEN}",
|
||||
"type": "book",
|
||||
"tag_ids": [999999],
|
||||
},
|
||||
expect=400,
|
||||
)
|
||||
check("the refusal names the id", "999999" in missing_tag["detail"], missing_tag["detail"])
|
||||
orphan = call("GET", "/references?keyword=引用了不存在的标签")
|
||||
orphan = call("GET", f"/references?keyword=引用了不存在的标签{TOKEN}")
|
||||
check("nothing was stored half-labelled", orphan["total"] == 0, str(orphan["total"]))
|
||||
|
||||
print("5. add a patent, which needs a country and a number")
|
||||
@@ -172,7 +216,7 @@ def main() -> int:
|
||||
"/references",
|
||||
{
|
||||
"type": "patent",
|
||||
"title": "一种基于多层聚类的人工智能技术识别方法",
|
||||
"title": f"一种基于多层聚类的人工智能技术识别方法({TOKEN})",
|
||||
"patent_country": "中国",
|
||||
"patent_number": "CN114000000A",
|
||||
"publication_year": 2023,
|
||||
@@ -185,7 +229,7 @@ def main() -> int:
|
||||
check("patent stored", patent["type"] == "patent" and patent["patent_number"] == "CN114000000A")
|
||||
check(
|
||||
"tagging works on create for more than one entry",
|
||||
[tag["name"] for tag in patent["tags"]] == ["必读"],
|
||||
[tag["name"] for tag in patent["tags"]] == [f"必读-{TOKEN}"],
|
||||
str(patent["tags"]),
|
||||
)
|
||||
|
||||
@@ -204,28 +248,40 @@ def main() -> int:
|
||||
call(
|
||||
"POST",
|
||||
"/references",
|
||||
{"title": "没有标签的书", "authors": [{"name": "甲"}], "type": "book"},
|
||||
{
|
||||
"title": f"没有标签的书{TOKEN}",
|
||||
"authors": [{"name": "甲"}],
|
||||
"type": "book",
|
||||
},
|
||||
expect=201,
|
||||
)
|
||||
probe = call("GET", "/references?keyword=没有标签的书")
|
||||
probe = call("GET", f"/references?keyword=没有标签的书{TOKEN}")
|
||||
created_references.append(probe["items"][0]["id"])
|
||||
check("a book needs nothing else", probe["total"] == 1)
|
||||
check("and may carry no tags at all", probe["items"][0]["tags"] == [])
|
||||
|
||||
print("8. find it again: by author, by type, by year, by tag")
|
||||
by_author = call("GET", "/references?keyword=Wang")
|
||||
check("search matches an author name", by_author["total"] == 1, str(by_author["total"]))
|
||||
by_author = call("GET", f"/references?keyword={AUTHOR_TOKEN}")
|
||||
check(
|
||||
"search matches an author name",
|
||||
by_author["total"] == 1,
|
||||
f'{by_author["total"]} (the token is on one author name)',
|
||||
)
|
||||
check(
|
||||
"the row prints an author line",
|
||||
by_author["items"][0]["authors_line"].startswith("张三, 李四, Wang Wu"),
|
||||
by_author["items"][0]["authors_line"],
|
||||
)
|
||||
by_type = call("GET", "/references?type=patent")
|
||||
by_type = call("GET", f"/references?type=patent&keyword={TOKEN}")
|
||||
check("filter by type", by_type["total"] == 1, str(by_type["total"]))
|
||||
by_year = call("GET", "/references?year=2024")
|
||||
by_year = call("GET", f"/references?year=2024&keyword={TOKEN}")
|
||||
check("filter by year", by_year["total"] == 1, str(by_year["total"]))
|
||||
uncited = call("GET", "/references?cited=false")
|
||||
check("filter by not-yet-cited", uncited["total"] == len(created_references))
|
||||
uncited = call("GET", f"/references?cited=false&keyword={TOKEN}")
|
||||
check(
|
||||
"filter by not-yet-cited",
|
||||
uncited["total"] == len(created_references),
|
||||
f'{uncited["total"]} of {len(created_references)}',
|
||||
)
|
||||
|
||||
by_tag = call("GET", f"/references?tag={must_read['id']}")
|
||||
check("filter by tag", by_tag["total"] == 2, str(by_tag["total"]))
|
||||
@@ -240,31 +296,43 @@ def main() -> int:
|
||||
)
|
||||
|
||||
print("9. the tag table counts what carries each label")
|
||||
tags = call("GET", "/reference-tags")
|
||||
tags = call("GET", f"/reference-tags?keyword={TOKEN}")
|
||||
counts = {tag["name"]: tag["reference_count"] for tag in tags["items"]}
|
||||
check("two labels in the library", tags["total"] == 2, str(tags["total"]))
|
||||
check("the shared label counts two rows", counts["必读"] == 2, str(counts))
|
||||
check("the other counts one", counts["综述"] == 1, str(counts))
|
||||
found = call("GET", "/reference-tags?keyword=综述")
|
||||
check("two labels carry this run's token", tags["total"] == 2, str(tags["total"]))
|
||||
check(
|
||||
"the shared label counts two rows",
|
||||
counts[f"必读-{TOKEN}"] == 2,
|
||||
str(counts),
|
||||
)
|
||||
check("the other counts one", counts[f"综述-{TOKEN}"] == 1, str(counts))
|
||||
found = call("GET", f"/reference-tags?keyword=综述-{TOKEN}")
|
||||
check("tags are searchable by name", found["total"] == 1, str(found["total"]))
|
||||
|
||||
print("10. renaming a label follows it everywhere it is used")
|
||||
renamed = call(
|
||||
"PATCH",
|
||||
f"/reference-tags/{survey['id']}",
|
||||
{"name": "综述文章", "note": "综述与述评"},
|
||||
{"name": f"综述文章-{TOKEN}", "note": "综述与述评"},
|
||||
)
|
||||
check("the label is renamed", renamed["name"] == "综述文章")
|
||||
check("the label is renamed", renamed["name"] == f"综述文章-{TOKEN}")
|
||||
after = call("GET", f"/references/{article['id']}")
|
||||
check(
|
||||
"the reference prints the new name",
|
||||
sorted(tag["name"] for tag in after["tags"]) == ["必读", "综述文章"],
|
||||
sorted(tag["name"] for tag in after["tags"])
|
||||
== [f"必读-{TOKEN}", f"综述文章-{TOKEN}"],
|
||||
str(after["tags"]),
|
||||
)
|
||||
taken = call(
|
||||
"PATCH", f"/reference-tags/{survey['id']}", {"name": "必读"}, expect=409
|
||||
"PATCH",
|
||||
f"/reference-tags/{survey['id']}",
|
||||
{"name": f"必读-{TOKEN}"},
|
||||
expect=409,
|
||||
)
|
||||
check(
|
||||
"renaming onto a taken name is refused",
|
||||
TOKEN in taken["detail"],
|
||||
taken["detail"],
|
||||
)
|
||||
check("renaming onto a taken name is refused", "必读" in taken["detail"], taken["detail"])
|
||||
|
||||
print("11. edit it: replace the contributor list, a field and its tags")
|
||||
updated = call(
|
||||
@@ -283,7 +351,7 @@ def main() -> int:
|
||||
check("author list replaced wholesale", len(updated["authors"]) == 2)
|
||||
check(
|
||||
"tag list replaced wholesale too",
|
||||
[tag["name"] for tag in updated["tags"]] == ["必读"],
|
||||
[tag["name"] for tag in updated["tags"]] == [f"必读-{TOKEN}"],
|
||||
str(updated["tags"]),
|
||||
)
|
||||
check("untouched fields kept", updated["container_title"] == "Technological Forecasting and Social Change")
|
||||
@@ -291,7 +359,7 @@ def main() -> int:
|
||||
cleared = call("PATCH", f"/references/{patent['id']}", {"tag_ids": None})
|
||||
check(
|
||||
"omitting tags leaves them alone",
|
||||
[tag["name"] for tag in cleared["tags"]] == ["必读"],
|
||||
[tag["name"] for tag in cleared["tags"]] == [f"必读-{TOKEN}"],
|
||||
str(cleared["tags"]),
|
||||
)
|
||||
|
||||
@@ -300,7 +368,10 @@ def main() -> int:
|
||||
paper = call(
|
||||
"POST",
|
||||
"/papers",
|
||||
{"title": "参考文献冒烟测试论文", "template_id": templates[0]["id"]},
|
||||
{
|
||||
"title": f"参考文献冒烟测试论文{TOKEN}",
|
||||
"template_id": templates[0]["id"],
|
||||
},
|
||||
expect=201,
|
||||
)
|
||||
created_papers.append(paper["id"])
|
||||
@@ -338,7 +409,7 @@ def main() -> int:
|
||||
check("and the paper", citations[0]["paper_id"] == paper["id"])
|
||||
check("and the paragraph heading", citations[0]["paragraph_name"] is not None, str(citations[0]))
|
||||
|
||||
cited = call("GET", "/references?cited=true")
|
||||
cited = call("GET", f"/references?cited=true&keyword={TOKEN}")
|
||||
check("the cited filter now finds it", cited["total"] == 1, str(cited["total"]))
|
||||
|
||||
print("14. a cited reference cannot be deleted; an uncited one can")
|
||||
@@ -361,7 +432,25 @@ def main() -> int:
|
||||
str(left["total"]),
|
||||
)
|
||||
|
||||
print("16. clean up")
|
||||
print("16. the 参考文献 list prints one entry per work, in Springer style")
|
||||
document = call("GET", f"/papers/{paper['id']}/document")
|
||||
check("the style is named in the response", document["reference_style"] == "springer")
|
||||
check(
|
||||
"one entry for the one work cited",
|
||||
len(document["references"]) == 1,
|
||||
str(len(document["references"])),
|
||||
)
|
||||
entry = document["references"][0]
|
||||
check("the entry is a bibliography line", entry["text"].startswith("张三, 李四"), entry["text"])
|
||||
check("and carries the year and the DOI", "(2024)" in entry["text"] and "https://doi.org/10.1016/j.techfore.2024.123456" in entry["text"], entry["text"])
|
||||
check("it names the places it is cited", len(entry["citations"]) == 1, str(len(entry["citations"])))
|
||||
check(
|
||||
"and the in-text marker is that entry's number",
|
||||
entry["citations"][0]["index"] == entry["index"],
|
||||
f'{entry["citations"][0]["index"]} vs {entry["index"]}',
|
||||
)
|
||||
|
||||
print("17. clean up")
|
||||
call("DELETE", f"/papers/{paper['id']}", expect=204)
|
||||
created_papers.clear()
|
||||
for reference_id in created_references:
|
||||
@@ -370,13 +459,13 @@ def main() -> int:
|
||||
for tag_id in created_tags:
|
||||
call("DELETE", f"/reference-tags/{tag_id}", expect=204)
|
||||
created_tags.clear()
|
||||
remaining = call("GET", "/references")
|
||||
# Scoped by the token rather than by "the library is empty": the library
|
||||
# this runs against holds real literature, and what must be true is that
|
||||
# none of *this run's* rows survive.
|
||||
remaining = call("GET", f"/references?keyword={TOKEN}")
|
||||
check("nothing of ours is left", remaining["total"] == 0, str(remaining["total"]))
|
||||
check(
|
||||
"and no labels either",
|
||||
call("GET", "/reference-tags")["total"] == 0,
|
||||
str(call("GET", "/reference-tags")["total"]),
|
||||
)
|
||||
tags_left = call("GET", f"/reference-tags?keyword={TOKEN}")
|
||||
check("and no labels either", tags_left["total"] == 0, str(tags_left["total"]))
|
||||
|
||||
print(f"\nall {_checks} checks passed")
|
||||
return 0
|
||||
|
||||
+6
-1
@@ -249,7 +249,7 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
|
||||
| `paper_update` | 改元信息 / 换模板 | `paper_id`、`title?` `template_id?` `clear_template?` `author?` `status?` `keywords?` `target_journal?` |
|
||||
| `paper_delete` | 删论文(连句子引用) | `paper_ids`(int 或数组)、`confirm=true` 必填 |
|
||||
| `paper_outline` | **写之前先看**:每段 position/标题/已写句数 | `paper_id` |
|
||||
| `paper_document` | 读全文 | `paper_id`、`format?`(`text`/`json`/`both`)`include_empty?` `citations?` |
|
||||
| `paper_document` | 读全文(`format=text` 时末尾附 Springer 格式的参考文献表) | `paper_id`、`format?`(`text`/`json`/`both`)`include_empty?` `citations?` |
|
||||
| `paper_write` | **批量写段落**(按标题或位置) | `paper_id`、`paragraphs`、`mode?`(`replace`/`append`) |
|
||||
| `paper_write_text` | **整篇一次写入**(Markdown 标题分段) | `paper_id`、`text`、`split?` `mode?` `strict?` |
|
||||
|
||||
@@ -258,6 +258,11 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
|
||||
|
||||
`paper_delete` 必须先被拒一次(告诉你删掉什么、不可恢复),确认后才带 `confirm=true` 重调。
|
||||
|
||||
`paper_document` 的 `text` 里,正文的上标编号与末尾参考文献表的序号是**同一个号**:同一篇文献被引多次只占一个号、只列一条。
|
||||
`json` 里对应的是 `references`(每条一个文献,`text` 就是排好版的条目)与 `reference_style`(当前是 `springer`),
|
||||
以及 `citations`(每处引用一行,带自己的 `index`)。条目里缺哪些字段,看那条的 `missing`(如 `["卷期页码"]`),
|
||||
不要自己去猜或补一个看起来合理的年份。
|
||||
|
||||
### 3.2 段落 paragraphs(5 个)
|
||||
|
||||
段落 = 位置。它由模板定义,或者由内容占据;**没有 `paragraph_create`**——往空位置写内容就是创建它。
|
||||
|
||||
+77
-9
@@ -370,6 +370,42 @@ The ORM cascades stay as well. `Template.items`, `Paper.sentences` and
|
||||
removes its dependents whether or not the database would have done it too —
|
||||
which keeps behaviour identical on a cluster with foreign keys switched off.
|
||||
|
||||
### The 参考文献 list is one entry per work, written by a style
|
||||
|
||||
A citation and a bibliography entry are two different counts, and confusing them
|
||||
is the mistake this design is shaped around. `paper_sentence_reference` holds one
|
||||
row per *place in the text* that quotes something: a paper of 86 citations to 65
|
||||
works has 86 rows. The 参考文献 list has 65 entries, each numbered where the
|
||||
reader first meets it, and every citation of that work carries the same number.
|
||||
So `[7]` means one article everywhere — in the text, in the tooltip on the
|
||||
marker, and in the list — and a work cannot appear twice under two numbers.
|
||||
|
||||
The entries themselves are written by :mod:`app.citation_styles`, which is a
|
||||
package of one module per style:
|
||||
|
||||
```
|
||||
app/citation_styles/
|
||||
├── __init__.py the registry, DEFAULT_STYLE, format_reference/missing_fields
|
||||
└── springer.py Springer's basic style — the numbered one
|
||||
```
|
||||
|
||||
`GET /papers/{id}/document` returns `references` (the entries, in order) and
|
||||
`reference_style` (which style wrote them). Three consequences are deliberate:
|
||||
|
||||
- **The client prints `text` verbatim.** Formatting a bibliography from fields
|
||||
is a rule, and a second implementation of a rule prints a second bibliography
|
||||
eventually. The paper view, the MCP text renderer and a future export all read
|
||||
the same assembled entries.
|
||||
- **A citation with no library row keeps its number and gets no entry.** It is
|
||||
listed as its own entry with empty text and a warning, rather than dropped —
|
||||
dropping it would leave a `[12]` in the text pointing at nothing.
|
||||
- **A gap is reported, not filled in.** Each entry carries `missing` — the parts
|
||||
a complete entry needs and does not have, in Chinese (「缺 责任者、出版年」) —
|
||||
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; saying so
|
||||
is the difference between a library that needs attention and a bibliography
|
||||
that lies.
|
||||
|
||||
## API
|
||||
|
||||
All routes are mounted under `/api`. Interactive docs at `/docs`.
|
||||
@@ -398,7 +434,7 @@ All routes are mounted under `/api`. Interactive docs at `/docs`.
|
||||
| `POST` | `/reference-tags` | name is unique — a duplicate is `409` naming it |
|
||||
| `GET` `PATCH` `DELETE` | `/reference-tags/{id}` | renaming follows every reference carrying it |
|
||||
| `POST` | `/reference-tags/batch-delete` | body `{ "ids": [...] }`; unlabels, never deletes literature |
|
||||
| `GET` | `/papers/{id}/document` | the whole paper: paragraphs in order, citations, warnings |
|
||||
| `GET` | `/papers/{id}/document` | the whole paper: paragraphs in order, citations, the formatted `references`, warnings |
|
||||
| `GET` | `/papers/{id}/paragraphs/{sort}` | one paragraph, assembled as the document renders it |
|
||||
| `PUT` | `/papers/{id}/paragraphs/{sort}` | full replacement; optional `target_sort` moves it |
|
||||
| `POST` | `/papers/{id}/sentences` | append one sentence |
|
||||
@@ -416,9 +452,14 @@ Conventions worth knowing:
|
||||
`/template-titles` for `template_title`, `/papers` for
|
||||
`paper`.
|
||||
- A paper document returns its `paragraphs` in ascending position order,
|
||||
already carrying their sentences and citation numbering. The client sorts
|
||||
nothing and merges nothing: two implementations of the same ordering rule
|
||||
would eventually disagree.
|
||||
already carrying their sentences and citation numbering, and its `references`
|
||||
as formatted entries. The client sorts nothing, merges nothing and formats
|
||||
nothing: two implementations of the same rule would eventually disagree.
|
||||
- A citation's `index` is the number of its **work**, so 86 citations to 65
|
||||
works produce 65 entries and repeated numbers in `citations` — see 「The
|
||||
参考文献 list is one entry per work」 above.
|
||||
- A document's `reference_style` names the style the entries were written in
|
||||
(`springer`), so a client can label the block without hard-coding the choice.
|
||||
- Sentence `content` is folded to a single line (leading, trailing and inner
|
||||
whitespace runs collapse to one space), so an all-whitespace sentence becomes
|
||||
the empty string — legal, and rendered as a blank line. A citation with a
|
||||
@@ -630,8 +671,12 @@ alone knows how to do:
|
||||
- **an edit button beside every paragraph**, written or not — content only ever
|
||||
enters a paper through the paragraph editor, so it may never be the thing that
|
||||
is missing;
|
||||
- **numbered citation markers** in the text, matching the 参考文献 list, which
|
||||
is numbered in reading order rather than per paragraph;
|
||||
- **numbered citation markers** in the text, whose number is the number of the
|
||||
*work* in the 参考文献 list below — a paper that cites one article in three
|
||||
sentences prints the same number three times;
|
||||
- **the 参考文献 block, printed from the server's entries and not reassembled** —
|
||||
each entry is one work with its bibliography line, and the paragraphs that
|
||||
cite it hang underneath it, with the quoted passages in the tooltip;
|
||||
- **a 切换模板 dialog that previews the impact** — how much content lands under
|
||||
a new heading, how much keeps its place under 未设定, and how many empty
|
||||
paragraphs the new template adds — because a switch re-shapes the whole
|
||||
@@ -676,6 +721,8 @@ paper-doc/
|
||||
│ ├── app/
|
||||
│ │ ├── api/routes/ # route handlers (health, papers, references,
|
||||
│ │ │ # reference_tags, templates, template_title)
|
||||
│ │ ├── citation_styles/ # how a reference prints: springer.py, and the
|
||||
│ │ │ # registry that names the styles
|
||||
│ │ ├── core/ # settings and configuration
|
||||
│ │ ├── crud/ # data-access helpers
|
||||
│ │ ├── db/ # engine, session, declarative base
|
||||
@@ -687,6 +734,8 @@ paper-doc/
|
||||
│ ├── scripts/smoke_papers.py # end-to-end check of the writing loop
|
||||
│ ├── scripts/smoke_references.py # end-to-end check of the reference library
|
||||
│ │ # and its tags
|
||||
│ ├── scripts/check_citation_styles.py # the formatter, one entry per type
|
||||
│ │ # (no server, no database)
|
||||
│ ├── scripts/mcp_server.py # MCP entry point (stdio / http)
|
||||
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
|
||||
│ ├── alembic.ini
|
||||
@@ -774,15 +823,34 @@ cd backend
|
||||
`scripts/smoke_references.py` makes the labels first, adds literature and tags
|
||||
it, finds it again by author, type, year and tag, edits it, cites it from a
|
||||
sentence, looks the citation up from the reference side, checks that a cited
|
||||
entry cannot be deleted while a tag can, and checks that a tag id the library
|
||||
does not have is refused by name rather than invented. It cleans up after
|
||||
itself:
|
||||
entry cannot be deleted while a tag can, that a tag id the library does not have
|
||||
is refused by name rather than invented, and that the paper's 参考文献 list
|
||||
prints one formatted entry per work. It cleans up after itself:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
.venv/bin/python scripts/smoke_references.py
|
||||
```
|
||||
|
||||
Every row it creates carries a per-run token in its title, in one author's name
|
||||
and in its label names, and it asserts against searches for that token. The
|
||||
library it runs against is a real one, so "the search found one row" is only a
|
||||
statement about this run if the run can name its own rows.
|
||||
|
||||
**Checking the citation formatter**
|
||||
|
||||
`scripts/check_citation_styles.py` needs nothing running: it builds a reference
|
||||
of every document type in memory and asserts the exact entry Springer's basic
|
||||
style calls for — authors and initials, the six-author limit, the en-dashed page
|
||||
range, the DOI, and what is reported missing. A wrong branch here prints
|
||||
something that *looks* like a bibliography entry, which is exactly the kind of
|
||||
bug that survives a smoke test:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
.venv/bin/python scripts/check_citation_styles.py
|
||||
```
|
||||
|
||||
**Checking the paper feature end to end**
|
||||
|
||||
`scripts/smoke_papers.py` walks the whole writing loop against a running API —
|
||||
|
||||
@@ -116,7 +116,14 @@ export interface PaperParagraph {
|
||||
|
||||
/** One citation as it appears in the 参考文献 list. */
|
||||
export interface PaperCitation extends Citation {
|
||||
/** The number shown in the text as `[index]`, in reading order. */
|
||||
/**
|
||||
* The number shown in the text as `[index]`, in reading order.
|
||||
*
|
||||
* It is the number of the **work**, not of the citation: a paper that cites
|
||||
* the same article in three sentences prints `[7]` three times and lists the
|
||||
* article once. Everything that numbers citations reads it from here, so the
|
||||
* markers and the list cannot disagree.
|
||||
*/
|
||||
index: number
|
||||
sentence_id: number
|
||||
sentence_content: string
|
||||
@@ -124,11 +131,35 @@ export interface PaperCitation extends Citation {
|
||||
paragraph_name: string | null
|
||||
}
|
||||
|
||||
/**
|
||||
* One entry of the 参考文献 list: one work, however often it is cited.
|
||||
*
|
||||
* `text` is the whole entry as it prints, already formatted by the server in
|
||||
* `reference_style`. A client prints it verbatim — assembling a bibliography
|
||||
* from fields is a second implementation of a rule, and the two would drift.
|
||||
*/
|
||||
export interface PaperReference {
|
||||
/** The number the text shows as `[index]`. */
|
||||
index: number
|
||||
/** The library row it came from, or `null` for a citation written before the
|
||||
* literature was entered — `text` is empty in that case, and nothing is
|
||||
* invented to fill it. */
|
||||
reference_id: number | null
|
||||
text: string
|
||||
/** What a complete entry still lacks, in Chinese — 责任者、出版年、DOI… */
|
||||
missing: string[]
|
||||
/** Every place in the text that cites it, in reading order. */
|
||||
citations: PaperCitation[]
|
||||
}
|
||||
|
||||
/** The whole paper as it reads. */
|
||||
export interface PaperDocument {
|
||||
paper: PaperDetail
|
||||
paragraphs: PaperParagraph[]
|
||||
citations: PaperCitation[]
|
||||
references: PaperReference[]
|
||||
/** The citation style the entries were written in, e.g. `springer`. */
|
||||
reference_style: string
|
||||
warnings: string[]
|
||||
}
|
||||
|
||||
@@ -218,6 +249,16 @@ export async function getPaperDocument(id: number): Promise<PaperDocument> {
|
||||
return data
|
||||
}
|
||||
|
||||
/** Display names for the citation styles the server can print. */
|
||||
export const REFERENCE_STYLE_LABELS: Record<string, string> = {
|
||||
springer: 'Springer 基本格式',
|
||||
}
|
||||
|
||||
/** The label for a style token, falling back to the token itself. */
|
||||
export function referenceStyleLabel(style: string): string {
|
||||
return REFERENCE_STYLE_LABELS[style] ?? style
|
||||
}
|
||||
|
||||
export async function createPaper(payload: PaperPayload): Promise<PaperDetail> {
|
||||
const { data } = await http.post<PaperDetail>('/papers', payload)
|
||||
return data
|
||||
|
||||
@@ -32,6 +32,8 @@ const props = defineProps<{
|
||||
paragraph: PaperParagraph
|
||||
/** Citation id -> the number shown in the text, assigned by reading order. */
|
||||
citationIndex: Record<number, number>
|
||||
/** Reference id -> its formatted entry, so a marker can say what it points at. */
|
||||
referenceText: Record<number, string>
|
||||
}>()
|
||||
|
||||
defineEmits<{ edit: [paragraph: PaperParagraph] }>()
|
||||
@@ -106,12 +108,19 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
|
||||
>
|
||||
<template #content>
|
||||
<div class="cite-tip">
|
||||
<div class="cite-tip-head">
|
||||
[{{ citationIndex[citation.id] ?? '?' }}]
|
||||
<span v-if="citation.reference_id">引用 #{{ citation.reference_id }}</span>
|
||||
<span v-else class="cite-tip-unlinked">未关联引用 id</span>
|
||||
<div class="cite-tip-head">[{{ citationIndex[citation.id] ?? '?' }}]</div>
|
||||
<!-- What the number means: the entry as the bibliography prints
|
||||
it, not its database id. -->
|
||||
<div
|
||||
v-if="citation.reference_id != null && referenceText[citation.reference_id]"
|
||||
class="cite-tip-entry"
|
||||
>
|
||||
{{ referenceText[citation.reference_id] }}
|
||||
</div>
|
||||
<div class="cite-tip-quote">{{ citation.quote }}</div>
|
||||
<div v-else class="cite-tip-unlinked">
|
||||
这处引用还没有关联文献库条目
|
||||
</div>
|
||||
<div class="cite-tip-quote">「{{ citation.quote }}」</div>
|
||||
</div>
|
||||
</template>
|
||||
<sup class="cite-mark">{{ citationIndex[citation.id] ?? '?' }}</sup>
|
||||
@@ -222,7 +231,7 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
|
||||
}
|
||||
|
||||
.cite-tip {
|
||||
max-width: 320px;
|
||||
max-width: 380px;
|
||||
}
|
||||
|
||||
.cite-tip-head {
|
||||
@@ -232,7 +241,15 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
/* The bibliography entry: the whole point of the tooltip. It is set as a
|
||||
paragraph of running text because that is how it prints in the list. */
|
||||
.cite-tip-entry {
|
||||
margin-top: 4px;
|
||||
line-height: 1.7;
|
||||
}
|
||||
|
||||
.cite-tip-unlinked {
|
||||
margin-top: 4px;
|
||||
font-weight: 400;
|
||||
opacity: 0.7;
|
||||
}
|
||||
|
||||
@@ -29,7 +29,6 @@ import {
|
||||
Delete,
|
||||
Edit,
|
||||
Refresh,
|
||||
Right,
|
||||
Switch,
|
||||
Warning,
|
||||
} from '@element-plus/icons-vue'
|
||||
@@ -41,8 +40,10 @@ import {
|
||||
getPaperDocument,
|
||||
PAPER_STATUS_LABELS,
|
||||
PAPER_STATUS_TAG,
|
||||
referenceStyleLabel,
|
||||
type PaperDocument,
|
||||
type PaperParagraph,
|
||||
type PaperReference,
|
||||
} from '@/api/papers'
|
||||
import PaperFormDialog from '@/components/papers/PaperFormDialog.vue'
|
||||
import ParagraphEditDialog from '@/components/papers/ParagraphEditDialog.vue'
|
||||
@@ -77,6 +78,52 @@ const citationIndex = computed<Record<number, number>>(() => {
|
||||
return map
|
||||
})
|
||||
|
||||
/**
|
||||
* Reference id -> the formatted entry, for the marker tooltips.
|
||||
*
|
||||
* The tooltip on a `[7]` in the text should say what `[7]` *is*, and the entry
|
||||
* is assembled once by the server — this is a lookup of that same string, not a
|
||||
* second attempt at formatting it.
|
||||
*/
|
||||
const referenceText = computed<Record<number, string>>(() => {
|
||||
const map: Record<number, string> = {}
|
||||
for (const entry of paperDoc.value?.references ?? []) {
|
||||
if (entry.reference_id != null && entry.text) {
|
||||
map[entry.reference_id] = entry.text
|
||||
}
|
||||
}
|
||||
return map
|
||||
})
|
||||
|
||||
/** How the entries are printed, named rather than hard-coded in the view. */
|
||||
const styleLabel = computed(() =>
|
||||
referenceStyleLabel(paperDoc.value?.reference_style ?? 'springer'),
|
||||
)
|
||||
|
||||
/**
|
||||
* Where an entry is cited, one row per paragraph.
|
||||
*
|
||||
* The same work cited twice in one paragraph is one place with a count, not two
|
||||
* identical links: what the reader needs from the list is where to look, and
|
||||
* the quotes for that paragraph travel in the tooltip.
|
||||
*/
|
||||
function places(entry: PaperReference): { sort: number; name: string; quotes: string[] }[] {
|
||||
const byParagraph = new Map<number, { sort: number; name: string; quotes: string[] }>()
|
||||
for (const citation of entry.citations) {
|
||||
const found = byParagraph.get(citation.paper_template_filed_sort)
|
||||
if (found) {
|
||||
found.quotes.push(citation.quote)
|
||||
continue
|
||||
}
|
||||
byParagraph.set(citation.paper_template_filed_sort, {
|
||||
sort: citation.paper_template_filed_sort,
|
||||
name: citation.paragraph_name ?? PARAGRAPH_UNSET_LABEL,
|
||||
quotes: [citation.quote],
|
||||
})
|
||||
}
|
||||
return [...byParagraph.values()]
|
||||
}
|
||||
|
||||
/** How much of the structure has been written, for the header read-out. */
|
||||
const progress = computed(() => {
|
||||
if (!paperDoc.value) return { written: 0, total: 0, unmatched: 0 }
|
||||
@@ -268,33 +315,69 @@ onMounted(load)
|
||||
:key="paragraph.paper_template_filed_sort"
|
||||
:paragraph="paragraph"
|
||||
:citation-index="citationIndex"
|
||||
:reference-text="referenceText"
|
||||
@edit="openParagraph"
|
||||
/>
|
||||
</div>
|
||||
</el-card>
|
||||
|
||||
<el-card v-if="paperDoc?.citations.length" shadow="never">
|
||||
<el-card v-if="paperDoc?.references.length" shadow="never">
|
||||
<template #header>
|
||||
<div class="paper-head">
|
||||
<span class="paper-title">参考文献引用</span>
|
||||
<span class="paper-hint">按正文出现顺序编号,正文中的上标与这里的序号一一对应</span>
|
||||
<span class="paper-title">参考文献</span>
|
||||
<span class="paper-hint">
|
||||
按正文首次出现顺序编号,同一篇文献在多处引用共用同一个序号;条目按 {{ styleLabel }} 排版
|
||||
</span>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<ol class="references">
|
||||
<li v-for="citation in paperDoc.citations" :key="citation.id" class="reference">
|
||||
<span class="reference-index">[{{ citation.index }}]</span>
|
||||
<li v-for="entry in paperDoc.references" :key="entry.index" class="reference">
|
||||
<span class="reference-index">[{{ entry.index }}]</span>
|
||||
<div class="reference-body">
|
||||
<div class="reference-quote">{{ citation.quote }}</div>
|
||||
<!-- The entry as it prints. Whatever the library is missing shows
|
||||
up as a shorter entry, so the gap is named underneath rather
|
||||
than quietly filled in. -->
|
||||
<p v-if="entry.text" class="reference-text">{{ entry.text }}</p>
|
||||
<p v-else class="reference-text reference-text--unlinked">
|
||||
这处引用还没有关联文献库条目,只有引用内容。
|
||||
</p>
|
||||
|
||||
<div class="reference-meta">
|
||||
<el-tag v-if="citation.reference_id" size="small" effect="plain">
|
||||
引用 #{{ citation.reference_id }}
|
||||
<el-tag
|
||||
v-if="entry.missing.length"
|
||||
type="warning"
|
||||
size="small"
|
||||
effect="plain"
|
||||
>
|
||||
缺 {{ entry.missing.join('、') }}
|
||||
</el-tag>
|
||||
<el-tag v-else size="small" type="warning" effect="plain">未关联引用 id</el-tag>
|
||||
<el-button link type="primary" @click="scrollToParagraph(citation.paper_template_filed_sort)">
|
||||
{{ citation.paragraph_name ?? PARAGRAPH_UNSET_LABEL }}
|
||||
<el-icon><Right /></el-icon>
|
||||
</el-button>
|
||||
<el-tag v-if="!entry.reference_id" type="warning" size="small" effect="plain">
|
||||
未关联文献
|
||||
</el-tag>
|
||||
<span class="reference-places">
|
||||
<span class="reference-places-label">引用位置</span>
|
||||
<el-tooltip
|
||||
v-for="place in places(entry)"
|
||||
:key="place.sort"
|
||||
placement="top"
|
||||
:show-after="200"
|
||||
>
|
||||
<template #content>
|
||||
<div class="place-tip">
|
||||
<div v-for="(quote, index) in place.quotes" :key="index">
|
||||
「{{ quote }}」
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
<el-button link type="primary" @click="scrollToParagraph(place.sort)">
|
||||
{{ place.name }}
|
||||
<span v-if="place.quotes.length > 1" class="place-count">
|
||||
×{{ place.quotes.length }}
|
||||
</span>
|
||||
</el-button>
|
||||
</el-tooltip>
|
||||
</span>
|
||||
</div>
|
||||
</div>
|
||||
</li>
|
||||
@@ -446,19 +529,56 @@ onMounted(load)
|
||||
|
||||
.reference-body {
|
||||
min-width: 0;
|
||||
flex: 1 1 auto;
|
||||
}
|
||||
|
||||
.reference-quote {
|
||||
/* The entry, printed as the style wrote it: one line of running text, hanging
|
||||
under its number like a bibliography. */
|
||||
.reference-text {
|
||||
margin: 0;
|
||||
font-size: 13px;
|
||||
line-height: 1.8;
|
||||
color: var(--el-text-color-regular);
|
||||
overflow-wrap: anywhere;
|
||||
}
|
||||
|
||||
.reference-text--unlinked {
|
||||
color: var(--el-color-warning);
|
||||
}
|
||||
|
||||
.reference-meta {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
margin-top: 4px;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.reference-places {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 2px;
|
||||
flex-wrap: wrap;
|
||||
font-size: 12px;
|
||||
color: var(--el-text-color-secondary);
|
||||
}
|
||||
|
||||
.reference-places-label {
|
||||
margin-right: 2px;
|
||||
color: var(--el-text-color-placeholder);
|
||||
}
|
||||
|
||||
.place-count {
|
||||
margin-left: 2px;
|
||||
color: var(--el-text-color-placeholder);
|
||||
font-variant-numeric: tabular-nums;
|
||||
}
|
||||
|
||||
.place-tip {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 4px;
|
||||
max-width: 420px;
|
||||
line-height: 1.7;
|
||||
}
|
||||
</style>
|
||||
|
||||
Reference in New Issue
Block a user