From e8e129221cafe9c32283dd1399a84536346f8eaf Mon Sep 17 00:00:00 2001 From: govin Date: Wed, 23 Sep 2026 13:14:52 +0800 Subject: [PATCH] frontend: centre the display formula, and let one be set left or right MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Display formulas were sitting against the left margin with only their number at the right, and the cause was a rule I had written myself: the paragraph's stylesheet set `text-align: left` on `.katex`, which is the very element KaTeX centres a display formula in. A well-meant attempt to keep a formula from being justified apart had quietly overridden the centring, and it applied to every formula in every paper — measured on a paragraph of known width, the formula's midpoint sat 607px left of centre. The override is gone; the rule carries only a font size now, and a comment says why nothing about alignment belongs there. `paper_sentence.formula_align` then adds the choice the writer asked for: a display formula can be `center` (the default, and what a paper wants almost always), `left` or `right`. It is per sentence rather than a template-field setting — one paragraph legitimately mixes a centred equation with a right-aligned continuation, and a field describes a heading, not a formula — and the paragraph editor offers it only on rows that contain display maths, since only those have a line of their own. The equation number is untouched: `\tag{1}` prints against the right margin in all three cases, as every numbered style does. Measured in the browser on a 1276px paragraph: centred puts the formula 596px from each edge, left puts it at 0, right puts it at 1225, and the tag is at the right in every case. 56 paper checks (2 new: the round trip and the refusal of an alignment the renderer does not know), 61 reference checks, 99 MCP checks, `vue-tsc` and the build all pass. --- .../a1d47c6f2e58_add_formula_align.py | 57 +++++++++++++++++++ backend/app/crud/paper.py | 4 ++ backend/app/models/paper_sentence.py | 17 +++++- backend/app/schemas/paper.py | 24 ++++++++ backend/scripts/smoke_papers.py | 50 +++++++++++++--- docs/OVERVIEW.md | 17 +++++- frontend/src/api/papers.ts | 20 +++++++ .../src/components/papers/PaperParagraph.vue | 26 +++++++-- .../components/papers/ParagraphEditDialog.vue | 31 +++++++++- 9 files changed, 228 insertions(+), 18 deletions(-) create mode 100644 backend/alembic/versions/a1d47c6f2e58_add_formula_align.py diff --git a/backend/alembic/versions/a1d47c6f2e58_add_formula_align.py b/backend/alembic/versions/a1d47c6f2e58_add_formula_align.py new file mode 100644 index 0000000..102a191 --- /dev/null +++ b/backend/alembic/versions/a1d47c6f2e58_add_formula_align.py @@ -0,0 +1,57 @@ +"""let a formula say how it is set on its line + +Display maths is centred by default, and that is what a paper wants almost +every time — but not always. A derivation that continues a previous line, or a +formula the writer wants against the right margin, is a layout decision about +*that formula*, and there was nowhere to record it: the renderer centred +everything. + +So the sentence carries it: ``formula_align`` is ``center`` (the default), +``left`` or ``right``, and it only means anything for a sentence that contains +display maths (``$$ … $$``). The equation number is unaffected — ``\\tag{1}`` +is always at the right margin, which is the convention in every style that +numbers equations. + +Why the sentence rather than the template field +----------------------------------------------- +A field (``template_title``) describes a *heading*: its text, level and +typography. Alignment belongs to one formula, and one paragraph legitimately +mixes them — a centred equation followed by a right-aligned continuation. A +field-level setting would force every formula under that heading to look the +same, and the writer would have no way to make an exception. + +Existing rows default to ``center``: today's documents render exactly as they +do now. + +Revision ID: a1d47c6f2e58 +Revises: f8c2d5a73b91 +Create Date: 2026-09-23 + +""" + +from collections.abc import Sequence + +import sqlalchemy as sa +from alembic import op + +# revision identifiers, used by Alembic. +revision: str = "a1d47c6f2e58" +down_revision: str | None = "f8c2d5a73b91" +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + + +def upgrade() -> None: + op.add_column( + "paper_sentence", + sa.Column( + "formula_align", + sa.String(length=8), + server_default=sa.text("'center'"), + nullable=False, + ), + ) + + +def downgrade() -> None: + op.drop_column("paper_sentence", "formula_align") diff --git a/backend/app/crud/paper.py b/backend/app/crud/paper.py index d7b0740..5ed415c 100644 --- a/backend/app/crud/paper.py +++ b/backend/app/crud/paper.py @@ -685,6 +685,7 @@ def replace_paragraph( sort=item.sort if item.sort is not None else base + offset, content=item.content, line_break_before=item.line_break_before, + formula_align=item.formula_align, citations=_build_citations(item.citations), ) ) @@ -708,6 +709,7 @@ def append_sentence(db: Session, paper: Paper, data: SentenceCreate) -> PaperSen sort=sort, content=data.content, line_break_before=data.line_break_before, + formula_align=data.formula_align, citations=_build_citations(data.citations), ) db.add(sentence) @@ -739,6 +741,8 @@ def update_sentence( sentence.content = data.content if data.line_break_before is not None: sentence.line_break_before = data.line_break_before + if data.formula_align is not None: + sentence.formula_align = data.formula_align if data.citations is not None: sentence.citations.clear() db.flush() diff --git a/backend/app/models/paper_sentence.py b/backend/app/models/paper_sentence.py index d83c9da..0f994ae 100644 --- a/backend/app/models/paper_sentence.py +++ b/backend/app/models/paper_sentence.py @@ -31,12 +31,16 @@ is assembled on read from the paper's template plus these rows. See from typing import TYPE_CHECKING -from sqlalchemy import Boolean, ForeignKey, Index, Integer, Text, text +from sqlalchemy import Boolean, ForeignKey, Index, Integer, String, Text, text from sqlalchemy.orm import Mapped, mapped_column, relationship from app.db.base import Base from app.models.mixins import TimestampMixin +#: How a display formula may be set on its line. ``center`` is what a paper +#: wants almost always, and the default for every existing row. +FORMULA_ALIGNMENTS: tuple[str, ...] = ("left", "center", "right") + if TYPE_CHECKING: # pragma: no cover - typing only from app.models.paper import Paper from app.models.paper_sentence_reference import PaperSentenceReference @@ -101,6 +105,17 @@ class PaperSentence(TimestampMixin, Base): server_default=text("0"), ) + #: How a display formula in this sentence sits on its line: one of + #: :data:`FORMULA_ALIGNMENTS`. Meaningless for a sentence with no display + #: maths, and it never moves the equation number — ``\tag{1}`` is at the + #: right margin whatever this says, as every numbered style prints it. + formula_align: Mapped[str] = mapped_column( + String(8), + nullable=False, + default="center", + server_default=text("'center'"), + ) + paper: Mapped["Paper"] = relationship(back_populates="sentences") #: References quoted by this sentence, in citation order. Eager-loaded diff --git a/backend/app/schemas/paper.py b/backend/app/schemas/paper.py index 33bb5c2..0dba339 100644 --- a/backend/app/schemas/paper.py +++ b/backend/app/schemas/paper.py @@ -28,6 +28,7 @@ from typing import Literal from pydantic import BaseModel, ConfigDict, Field, field_validator from app.citation_styles import DEFAULT_STYLE as DEFAULT_REFERENCE_STYLE +from app.models.paper_sentence import FORMULA_ALIGNMENTS #: Writing states, mirroring :data:`app.models.paper.PAPER_STATUSES`. Kept as a #: literal so the generated OpenAPI document describes the enum for clients. @@ -99,6 +100,8 @@ class SentenceInput(BaseModel): content: str = "" #: Start a new line at this sentence rather than running on from the last. line_break_before: bool = False + #: How a display formula in this sentence is set: left, center or right. + formula_align: str = "center" citations: list[CitationInput] = Field(default_factory=list) @field_validator("content") @@ -106,6 +109,18 @@ class SentenceInput(BaseModel): def _normalise_content(cls, value: str) -> str: return fold_whitespace(value) + @field_validator("formula_align") + @classmethod + def _check_align(cls, value: str) -> str: + return _check_formula_align(value) + + +def _check_formula_align(value: str) -> str: + """Accept only the three alignments the renderer knows how to apply.""" + if value not in FORMULA_ALIGNMENTS: + raise ValueError("公式对齐只能是:" + "、".join(FORMULA_ALIGNMENTS)) + return value + class ParagraphUpdate(BaseModel): """Payload for ``PUT /papers/{id}/paragraphs/{sort}``. @@ -138,6 +153,7 @@ class SentenceUpdate(BaseModel): ) content: str | None = None line_break_before: bool | None = None + formula_align: str | None = None citations: list[CitationInput] | None = None @field_validator("content") @@ -145,6 +161,11 @@ class SentenceUpdate(BaseModel): def _normalise_content(cls, value: str | None) -> str | None: return None if value is None else fold_whitespace(value) + @field_validator("formula_align") + @classmethod + def _check_align(cls, value: str | None) -> str | None: + return None if value is None else _check_formula_align(value) + # --- reads ------------------------------------------------------------------ @@ -174,6 +195,9 @@ class SentenceRead(BaseModel): #: Whether a line break prints before this sentence. See #: :attr:`app.models.paper_sentence.PaperSentence.line_break_before`. line_break_before: bool + #: How a display formula in this sentence is set. See + #: :attr:`app.models.paper_sentence.PaperSentence.formula_align`. + formula_align: str citations: list[CitationRead] #: Text to print before this sentence when the paragraph is put back #: together — ``""`` or a single space, never anything else. Derived on diff --git a/backend/scripts/smoke_papers.py b/backend/scripts/smoke_papers.py index 7b03b37..7f1231d 100644 --- a/backend/scripts/smoke_papers.py +++ b/backend/scripts/smoke_papers.py @@ -302,7 +302,39 @@ def main() -> int: ) call("PUT", f"/papers/{paper['id']}/paragraphs/{second_sort}", {"sentences": []}) - print("9. reject a citation with no quote") + print("9. a formula says how it is set on its line") + aligned = call( + "PUT", + f"/papers/{paper['id']}/paragraphs/{second_sort}", + { + "sentences": [ + {"content": "$$ E = mc^2 $$", "formula_align": "right"}, + {"content": "$$ F = ma $$", "formula_align": "left"}, + {"content": "$$ p = mv $$"}, + ] + }, + ) + paragraph_aligned = next( + p + for p in aligned["paragraphs"] + if p["paper_template_filed_sort"] == second_sort + ) + check( + "alignment is stored per sentence, defaulting to centre", + [s["formula_align"] for s in paragraph_aligned["sentences"]] + == ["right", "left", "center"], + str([s["formula_align"] for s in paragraph_aligned["sentences"]]), + ) + call( + "PUT", + f"/papers/{paper['id']}/paragraphs/{second_sort}", + {"sentences": [{"content": "$$ x $$", "formula_align": "middle"}]}, + expect=422, + ) + check("an alignment the renderer does not know is refused", True) + call("PUT", f"/papers/{paper['id']}/paragraphs/{second_sort}", {"sentences": []}) + + print("10. reject a citation with no quote") bad = call( "PUT", f"/papers/{paper['id']}/paragraphs/{first_sort}", @@ -320,7 +352,7 @@ def main() -> int: ) check("citation without content refused", "detail" in bad) - print("10. a sentence with no paragraph in the template survives a switch") + print("11. 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 = ( @@ -348,7 +380,7 @@ def main() -> int: p for p in document["paragraphs"] if p["paper_template_filed_sort"] == orphan_sort )["name"] is None) - print("11. switch the template") + print("12. 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") @@ -378,7 +410,7 @@ def main() -> int: ), ) - print("12. move one paragraph onto another position") + print("13. move one paragraph onto another position") document = call( "PUT", f"/papers/{paper['id']}/paragraphs/{orphan_sort}", @@ -393,18 +425,18 @@ def main() -> int: all(p["paper_template_filed_sort"] != orphan_sort for p in document["paragraphs"]), ) - print("13. paper list reports progress") + print("14. 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("14. a template in use cannot be deleted") + print("15. 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("15. single sentence edit and delete") + print("16. single sentence edit and delete") sentence_id = target["sentences"][0]["id"] updated = call( "PATCH", @@ -420,7 +452,7 @@ def main() -> int: sum(len(p["sentences"]) for p in document["paragraphs"]) == 2, ) - print("16. a paper with no template still works") + print("17. a paper with no template still works") bare = call( "POST", "/papers", @@ -443,7 +475,7 @@ def main() -> int: call("DELETE", f"/papers/{bare['id']}", expect=204) created_papers.remove(bare["id"]) - print("17. delete the paper") + print("18. delete the paper") call("DELETE", f"/papers/{paper['id']}", expect=204) created_papers.clear() for reference_id in created_references: diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index 682b9a2..d8a4951 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -701,11 +701,22 @@ Four delimiters are recognised, because a writer's habit decides which they use: `$$…$$` and `\[…\]` for display, `$…$` and `\(…\)` for inline. An unmatched `$` is left alone rather than swallowing the rest of the paragraph. -Two rules are worth knowing when reading the renderer: +Three rules are worth knowing when reading the renderer: - **A display formula is a block.** It takes its own line whether or not the - sentence asked for a break, because that is what "display" means — so the - formulas in a paper sit centred on their own lines with no extra flagging. + sentence asked for a break, because that is what "display" means. +- **It is centred, and its number is at the right margin.** `\tag{1}` prints the + number against the right edge of the block while the formula stays centred — + the layout every numbered style uses. `paper_sentence.formula_align` moves the + *formula* (`left` / `center` / `right`), never the number, and it is a + per-sentence field rather than a template-field setting: one paragraph + legitimately mixes a centred equation with a right-aligned continuation, and a + field describes a heading, not a formula. +- **A `text-align` on `.katex` is a trap.** KaTeX centres a display formula in + that very element, so a well-meant `text-align: left` in the paragraph's + stylesheet overrides it and every formula in the paper sits against the left + margin with only its number at the right. That is exactly what happened here; + the rule now carries only a font size. - **KaTeX never throws.** `throwOnError: false` renders a formula it cannot read as its own source in red, so one typo shows itself instead of blanking the paragraph the writer is looking at. Text segments are escaped before they go diff --git a/frontend/src/api/papers.ts b/frontend/src/api/papers.ts index 050ab1b..e1b3a68 100644 --- a/frontend/src/api/papers.ts +++ b/frontend/src/api/papers.ts @@ -14,6 +14,16 @@ import type { BatchDeleteResult, PageQuery, PageResult } from './types' /** 草稿 / 撰写中 / 已完成. Mirrors `app.models.paper.PAPER_STATUSES`. */ export type PaperStatus = 'draft' | 'writing' | 'done' +/** How a display formula is set on its line. Mirrors `FORMULA_ALIGNMENTS`. */ +export type FormulaAlign = 'left' | 'center' | 'right' + +/** What the editor offers, in the order it offers them. */ +export const FORMULA_ALIGN_OPTIONS: { value: FormulaAlign; label: string }[] = [ + { value: 'center', label: '公式居中' }, + { value: 'left', label: '公式居左' }, + { value: 'right', label: '公式居右' }, +] + /** Display labels and tag colours for the three states, in one place. */ export const PAPER_STATUS_LABELS: Record = { draft: '草稿', @@ -84,6 +94,14 @@ export interface Sentence { /** Position inside that paragraph. */ sort: number content: string + /** + * How a display formula in this sentence sits on its line. + * + * `center` (the default) is what a paper wants almost always. The equation + * number is not affected: `\tag{1}` is always at the right margin, as every + * numbered style prints it. + */ + formula_align: FormulaAlign /** * Whether a line break prints before this sentence. * @@ -191,6 +209,8 @@ export interface SentenceInput { content: string /** Start a new line at this sentence. */ line_break_before?: boolean + /** How a display formula in this sentence is set. */ + formula_align?: FormulaAlign citations: CitationInput[] } diff --git a/frontend/src/components/papers/PaperParagraph.vue b/frontend/src/components/papers/PaperParagraph.vue index 7a0d02f..369c1c5 100644 --- a/frontend/src/components/papers/PaperParagraph.vue +++ b/frontend/src/components/papers/PaperParagraph.vue @@ -179,10 +179,12 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_ >