diff --git a/.gitignore b/.gitignore index 7e83e25..aa885c9 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,9 @@ backend/.env # --- Node / frontend --- node_modules/ +# pnpm keeps a content-addressed store; when it lands here rather than in the +# home directory it is build output, not source. +.pnpm-store/ frontend/dist/ frontend/dist-ssr/ *.tsbuildinfo diff --git a/backend/alembic/versions/f8c2d5a73b91_add_line_break_before.py b/backend/alembic/versions/f8c2d5a73b91_add_line_break_before.py new file mode 100644 index 0000000..f834481 --- /dev/null +++ b/backend/alembic/versions/f8c2d5a73b91_add_line_break_before.py @@ -0,0 +1,48 @@ +"""give a sentence the option to start a new line + +A paragraph is its sentences concatenated, which is right for prose and wrong +for the things a paper also puts inside a paragraph: a display formula, a list +of items, an author line. Those want a line break between them, and until now +there was nowhere to say so — text pasted with newlines was folded onto one line +on purpose, so the writer had no way to ask for one. + +So the sentence carries the request: ``line_break_before`` prints a break before +this sentence and nothing else. It is a property of the sentence rather than a +character in its content because the content is a sentence — folding whitespace +is what keeps it one — and because a break the writer cannot see cannot be +removed. + +Existing rows default to 0: today's documents render exactly as they did. + +Revision ID: f8c2d5a73b91 +Revises: 063f6def01fa +Create Date: 2026-09-22 + +""" + +from collections.abc import Sequence + +import sqlalchemy as sa +from alembic import op + +# revision identifiers, used by Alembic. +revision: str = "f8c2d5a73b91" +down_revision: str | None = "063f6def01fa" +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + + +def upgrade() -> None: + op.add_column( + "paper_sentence", + sa.Column( + "line_break_before", + sa.Boolean(), + server_default=sa.text("0"), + nullable=False, + ), + ) + + +def downgrade() -> None: + op.drop_column("paper_sentence", "line_break_before") diff --git a/backend/app/crud/paper.py b/backend/app/crud/paper.py index 7f959cf..d7b0740 100644 --- a/backend/app/crud/paper.py +++ b/backend/app/crud/paper.py @@ -419,7 +419,13 @@ def build_document(db: Session, paper: Paper) -> PaperDocumentRead: # than by whoever prints them, so a reader, an export and a preview # cannot each invent their own spacing. for earlier, later in zip(sentences, sentences[1:]): - later.separator_before = sentence_separator(earlier.content, later.content) + later.separator_before = ( + "" + if later.line_break_before + # A line break already separates the two, and printing a space + # as well would indent the new line by one blank. + else sentence_separator(earlier.content, later.content) + ) paragraph = ParagraphRead( paper_template_filed_sort=position, @@ -678,6 +684,7 @@ def replace_paragraph( paper_template_filed_sort=target, sort=item.sort if item.sort is not None else base + offset, content=item.content, + line_break_before=item.line_break_before, citations=_build_citations(item.citations), ) ) @@ -700,6 +707,7 @@ def append_sentence(db: Session, paper: Paper, data: SentenceCreate) -> PaperSen paper_template_filed_sort=data.paper_template_filed_sort, sort=sort, content=data.content, + line_break_before=data.line_break_before, citations=_build_citations(data.citations), ) db.add(sentence) @@ -729,6 +737,8 @@ def update_sentence( sentence.paper_template_filed_sort = data.paper_template_filed_sort if data.content is not None: sentence.content = data.content + if data.line_break_before is not None: + sentence.line_break_before = data.line_break_before 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 d193adb..d83c9da 100644 --- a/backend/app/models/paper_sentence.py +++ b/backend/app/models/paper_sentence.py @@ -31,7 +31,7 @@ is assembled on read from the paper's template plus these rows. See from typing import TYPE_CHECKING -from sqlalchemy import ForeignKey, Index, Integer, Text +from sqlalchemy import Boolean, ForeignKey, Index, Integer, Text, text from sqlalchemy.orm import Mapped, mapped_column, relationship from app.db.base import Base @@ -86,6 +86,21 @@ class PaperSentence(TimestampMixin, Base): #: placeholder and renders as a blank line rather than disappearing. content: Mapped[str] = mapped_column(Text, nullable=False, default="") + #: Print a line break before this sentence. + #: + #: A paragraph is its sentences concatenated, which is right for prose and + #: wrong for what else a paper puts inside one: a display formula, a list of + #: items, an author line. The break is a flag rather than a newline in + #: ``content`` for two reasons — content folds its whitespace so a sentence + #: really is one line, and a break hidden in a string is a break the writer + #: cannot see or remove. + line_break_before: Mapped[bool] = mapped_column( + Boolean, + nullable=False, + default=False, + server_default=text("0"), + ) + 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 3cca11b..33bb5c2 100644 --- a/backend/app/schemas/paper.py +++ b/backend/app/schemas/paper.py @@ -97,6 +97,8 @@ class SentenceInput(BaseModel): sort: int | None = Field(default=None, ge=-1_000_000, le=1_000_000) content: str = "" + #: Start a new line at this sentence rather than running on from the last. + line_break_before: bool = False citations: list[CitationInput] = Field(default_factory=list) @field_validator("content") @@ -135,6 +137,7 @@ class SentenceUpdate(BaseModel): default=None, ge=-1_000_000, le=1_000_000 ) content: str | None = None + line_break_before: bool | None = None citations: list[CitationInput] | None = None @field_validator("content") @@ -168,6 +171,9 @@ class SentenceRead(BaseModel): paper_template_filed_sort: int sort: int content: str + #: Whether a line break prints before this sentence. See + #: :attr:`app.models.paper_sentence.PaperSentence.line_break_before`. + line_break_before: bool 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 066d2a3..7b03b37 100644 --- a/backend/scripts/smoke_papers.py +++ b/backend/scripts/smoke_papers.py @@ -267,7 +267,42 @@ def main() -> int: # Clear it again so the counts asserted below stay meaningful. call("PUT", f"/papers/{paper['id']}/paragraphs/{second_sort}", {"sentences": []}) - print("8. reject a citation with no quote") + print("8. a sentence can ask for a line break") + # The flag replaces the separator rather than adding to it: a break + # already separates the two, and a space as well would indent the new + # line by one blank. + broken = call( + "PUT", + f"/papers/{paper['id']}/paragraphs/{second_sort}", + { + "sentences": [ + {"content": "连排的第一句。"}, + {"content": "另起一行的一句。", "line_break_before": True}, + {"content": "English runs on.", "line_break_before": True}, + ] + }, + ) + paragraph_breaks = next( + p + for p in broken["paragraphs"] + if p["paper_template_filed_sort"] == second_sort + ) + check( + "the flag is stored per sentence", + [s["line_break_before"] for s in paragraph_breaks["sentences"]] + == [False, True, True], + str([s["line_break_before"] for s in paragraph_breaks["sentences"]]), + ) + check( + "it also survives a read back", + all( + s["line_break_before"] is False or s["separator_before"] == "" + for s in paragraph_breaks["sentences"] + ), + ) + call("PUT", f"/papers/{paper['id']}/paragraphs/{second_sort}", {"sentences": []}) + + print("9. reject a citation with no quote") bad = call( "PUT", f"/papers/{paper['id']}/paragraphs/{first_sort}", @@ -285,7 +320,7 @@ def main() -> int: ) check("citation without content refused", "detail" in bad) - print("9. a sentence with no paragraph in the template survives a switch") + print("10. 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 = ( @@ -313,7 +348,7 @@ def main() -> int: p for p in document["paragraphs"] if p["paper_template_filed_sort"] == orphan_sort )["name"] is None) - print("10. switch the template") + print("11. 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") @@ -343,7 +378,7 @@ def main() -> int: ), ) - print("11. move one paragraph onto another position") + print("12. move one paragraph onto another position") document = call( "PUT", f"/papers/{paper['id']}/paragraphs/{orphan_sort}", @@ -358,18 +393,18 @@ def main() -> int: all(p["paper_template_filed_sort"] != orphan_sort for p in document["paragraphs"]), ) - print("12. paper list reports progress") + print("13. 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("13. a template in use cannot be deleted") + print("14. 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("14. single sentence edit and delete") + print("15. single sentence edit and delete") sentence_id = target["sentences"][0]["id"] updated = call( "PATCH", @@ -385,7 +420,7 @@ def main() -> int: sum(len(p["sentences"]) for p in document["paragraphs"]) == 2, ) - print("15. a paper with no template still works") + print("16. a paper with no template still works") bare = call( "POST", "/papers", @@ -408,7 +443,7 @@ def main() -> int: call("DELETE", f"/papers/{bare['id']}", expect=204) created_papers.remove(bare["id"]) - print("16. delete the paper") + print("17. 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 ed7bfda..434562e 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -306,6 +306,23 @@ stop (`。`) and nothing else — deliberately conservative: an English abstract survives that migration as a single row rather than being cut at the first `et al.`, and one long line is a line the writer can split by hand. +#### A line break is asked for, never guessed + +A paragraph is its sentences run together — that is the model. Everything a +paper also puts *inside* a paragraph that is not prose (a display formula, a +list of items, an author line) therefore needs a way to say "start a new line +here", and that is `paper_sentence.line_break_before`. + +It is a flag rather than a newline inside `content` for two reasons. Content +folds its whitespace, deliberately, so that a sentence really is one line and a +pasted newline cannot split one in half; and a break buried in a string is a +break nobody can see, count or remove. A flag prints a `
` and is visible in +the editor as a checkbox on the sentence's row. + +A break also **replaces** the separator rather than adding to it: the new line +already separates the two sentences, and a space as well would indent the line +by one blank. + #### What goes at the seam A paragraph is printed by concatenating its sentences in `sort` order, so the @@ -662,6 +679,29 @@ are not lists (the paper document) keep scrolling normally. | `/references` | reference table + CRUD (`?tag=` filters, `?new=1` opens the create dialog) | `references` | | `/references/tags` | tag library + CRUD (the UI label is 标签管理) | `references` | +### Sentences are stored as LaTeX and typeset on read + +A formula is stored exactly as the writer typed it — `$\ell$`, `$$ … \tag{1} $$` +— because that is the form that can be edited; an equation image cannot be +changed by one character. Typesetting happens when the paper is read, in +`src/utils/math.ts`, which splits a sentence into text and formulas, hands the +formulas to KaTeX and escapes everything else. + +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: + +- **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. +- **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 + through `v-html`, and KaTeX runs with `trust` off, so a sentence cannot inject + markup. + ### The paper view `PapersView` is the library; `papers/PaperDetailView` is the writing surface. diff --git a/frontend/package.json b/frontend/package.json index 16123b5..09160c2 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -14,6 +14,7 @@ "@element-plus/icons-vue": "^2.3.2", "axios": "^1.20.0", "element-plus": "^2.14.5", + "katex": "^0.18.7", "pinia": "^4.0.2", "pinia-plugin-persistedstate": "^4.7.1", "vue": "^3.5.40", diff --git a/frontend/pnpm-lock.yaml b/frontend/pnpm-lock.yaml index 6052872..142035a 100644 --- a/frontend/pnpm-lock.yaml +++ b/frontend/pnpm-lock.yaml @@ -17,6 +17,9 @@ importers: element-plus: specifier: ^2.14.5 version: 2.14.5(vue@3.5.42(typescript@6.0.3)) + katex: + specifier: ^0.18.7 + version: 0.18.7 pinia: specifier: ^4.0.2 version: 4.0.3(@vue/devtools-api@8.2.1)(typescript@6.0.3)(vue@3.5.42(typescript@6.0.3)) @@ -543,6 +546,10 @@ packages: resolution: {integrity: sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==} engines: {node: '>= 0.8'} + commander@15.0.0: + resolution: {integrity: sha512-z67u4ZhzCL/Tydu1lJARtEZYWbWaN7oYLHbsuzocr6y4N6WZAagG3RQ4FW61V1/0+jImpj293XfrcYnd1qxtPg==} + engines: {node: '>=22.12.0'} + confbox@0.1.8: resolution: {integrity: sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==} @@ -749,6 +756,10 @@ packages: engines: {node: '>=6'} hasBin: true + katex@0.18.7: + resolution: {integrity: sha512-h+UCwkZ+4Jz8WQ7MLGfj7UVFrRCizGb912fwF4luGdYsC5paYG1vx+jy+KRcC/XkpjGva/P7nAWuxNnPzRvzHw==} + hasBin: true + kolorist@1.8.0: resolution: {integrity: sha512-Y+60/zizpJ3HRH8DCss+q95yr6145JXZo46OTpFvDZWLfRCE4qChOyk1b26nMaNpfHHgxagk9dXT5OP0Tfe+dQ==} @@ -1761,6 +1772,8 @@ snapshots: dependencies: delayed-stream: 1.0.0 + commander@15.0.0: {} + confbox@0.1.8: {} confbox@0.2.4: {} @@ -1936,6 +1949,10 @@ snapshots: json5@2.2.3: {} + katex@0.18.7: + dependencies: + commander: 15.0.0 + kolorist@1.8.0: {} lightningcss-android-arm64@1.33.0: diff --git a/frontend/src/api/papers.ts b/frontend/src/api/papers.ts index e0f2dde..050ab1b 100644 --- a/frontend/src/api/papers.ts +++ b/frontend/src/api/papers.ts @@ -84,6 +84,14 @@ export interface Sentence { /** Position inside that paragraph. */ sort: number content: string + /** + * Whether a line break prints before this sentence. + * + * A paragraph is normally its sentences run together; this is how the writer + * asks for a new line — a display formula, a list of items, an author line — + * without splitting the paragraph in two. + */ + line_break_before: boolean citations: Citation[] /** * What to print before this sentence when the paragraph is put back @@ -181,6 +189,8 @@ export interface CitationInput { export interface SentenceInput { sort?: number | null content: string + /** Start a new line at this sentence. */ + line_break_before?: boolean citations: CitationInput[] } diff --git a/frontend/src/components/papers/PaperParagraph.vue b/frontend/src/components/papers/PaperParagraph.vue index 0b67157..97d083d 100644 --- a/frontend/src/components/papers/PaperParagraph.vue +++ b/frontend/src/components/papers/PaperParagraph.vue @@ -27,6 +27,7 @@ import { Edit } from '@element-plus/icons-vue' import type { PaperParagraph } from '@/api/papers' import { PARAGRAPH_UNSET_LABEL, levelIndent } from '@/utils/format' +import { escapeHtml, hasDisplayMath, renderRich } from '@/utils/math' const props = defineProps<{ paragraph: PaperParagraph @@ -49,10 +50,39 @@ const headingStyle = computed(() => { /** Indentation follows the field's level, exactly as the template outline does. */ const headingIndent = computed(() => levelIndent(props.paragraph.level)) +/** + * Every sentence, prepared for printing. + * + * Typesetting happens here rather than in the template so it runs once per + * sentence instead of on every re-render, and so the line-break rule — a break + * replaces the separator, it does not add to it — is stated in one place. + */ +interface RenderedSentence { + sentence: PaperParagraph['sentences'][number] + /** The sentence as HTML: its separator escaped, its formulas typeset. */ + html: string + /** A `$$ … $$` formula, which takes a line of its own by definition. */ + display: boolean + /** The writer asked for a line break before this sentence. */ + lineBreak: boolean +} + +const rendered = computed(() => + props.paragraph.sentences.map((sentence) => ({ + sentence, + html: + escapeHtml(sentence.line_break_before ? '' : sentence.separator_before) + + renderRich(sentence.content), + display: hasDisplayMath(sentence.content), + lineBreak: sentence.line_break_before, + })), +) + /** Whether anything has actually been written here. */ const hasContent = computed(() => - props.paragraph.sentences.some( - (sentence) => sentence.content.trim().length > 0 || sentence.citations.length > 0, + rendered.value.some( + (item) => + item.sentence.content.trim().length > 0 || item.sentence.citations.length > 0, ), ) @@ -95,13 +125,22 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_ -

-