docs: describe the citation styles and the per-work numbering
Records the decisions the 参考文献 list now rests on: a citation is a place in the text and an entry is a work, so a paper with 86 citations to 65 works lists 65 entries; the entries are written by `app/citation_styles` and a client prints them verbatim; a gap is reported through `missing` rather than quietly rendered as a shorter entry. Also documents `scripts/check_citation_styles.py` — the formatter is checked with no server and no database, because a wrong branch prints something that looks like a bibliography entry instead of failing loudly — and why the reference smoke test now stamps a token into everything it creates.
This commit is contained in:
+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 —
|
||||
|
||||
Reference in New Issue
Block a user