Skip to content

Commit 2dc0491

Browse files
committed
docs(protocol): emit the spec PDF as 1.4 so older e-readers can open it
The PDF failed to open on some e-book readers, which reported the file as damaged. The cause is structural, not corruption: xdvipdfmx defaults to PDF 1.5, which stores objects in object streams (/ObjStm) and replaces the classic cross-reference table with a cross-reference stream (/XRef). The old file had 8 object streams, 1 xref stream and no `trailer` keyword at all. A parser that only implements PDF 1.4 looks for `trailer`, does not find it, cannot follow `startxref` into a compressed stream object, and reports the file as corrupt. Plenty of e-ink firmware and e-book apps ship exactly such a parser. `compile_pdf()` now passes `-output-driver="xdvipdfmx -V 4 -q"`, so the output is PDF 1.4 with a classic xref table and a real trailer dictionary: 0 /ObjStm, 0 /XRef, 1 trailer. The cost is size — 476 KB to 660 KB (+38%), since the object and xref structure is no longer compressed. Everything else is byte-for-byte equivalent: 90 pages, same 295,910 characters of text, all 10 figures, 787 link annotations and the outline intact, zero LaTeX errors, zero missing glyphs, both drift guards pass. The tradeoff is recorded in README.md next to the PDF entry so the flag is not mistaken for an accident and reverted for the size win. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q4FAzXMZFjdfqBPY3wSYJ7
1 parent 6f729f6 commit 2dc0491

3 files changed

Lines changed: 7 additions & 2 deletions

File tree

packages/protocol/docs/preconfirmation-v2/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
| [`lookahead-model.py`](lookahead-model.py) | **排班表可执行参考实现**(零依赖 Python,§3.2 代码化):窗口对齐/唯一快照/种子/加权抽样的完整计算 + 6 项性质断言;抽样算子为 §12-18(b) 定形候选。 |
2323
| [`settlement-window-RESULTS.md`](settlement-window-RESULTS.md) | 模型验证结果(P1–P12 共 21 项全过)与覆盖对照。 |
2424
| [`settlement-window-implementation-review.md`](settlement-window-implementation-review.md) | **实现前复核(§12 第 18 项后半,r44)**:模型未覆盖项闭合对照、Solidity 级 `acceptCandidate` 存储布局(固定 4 词复用)与 gas 分析(边际 O(1),≈20–25k/候选)、Inbox 对接路径、仍开放项清单。非规范性;最终判定 = 所有者 + 人类安全评审。 |
25-
| [`slot-chain-spec.pdf`](slot-chain-spec.pdf) | **主规范的 PDF 版**(英文、A4 单栏、学术论文式排版,90 页):标题页 + 摘要 + 目录,正文与公式统一用 Palatino(`mathpazo`),10 幅 TikZ 灰阶图,§/附录交叉引用可点击,评审出处注记集中在附录 E。由 `build-pdf.py``slot-chain-spec.en.md` 生成。 |
25+
| [`slot-chain-spec.pdf`](slot-chain-spec.pdf) | **主规范的 PDF 版**(英文、A4 单栏、学术论文式排版,90 页):标题页 + 摘要 + 目录,正文与公式统一用 Palatino(`mathpazo`),10 幅 TikZ 灰阶图,§/附录交叉引用可点击,评审出处注记集中在附录 E。由 `build-pdf.py``slot-chain-spec.en.md` 生成**刻意输出为 PDF 1.4**(经典 xref 表 + `trailer`,不用对象流/交叉引用流)——PDF 1.5 结构小约 28%,但只实现 1.4 的老解析器(不少电子书阅读器、电纸书固件)会误报"文件已损坏"|
2626
| [`build-pdf.py`](build-pdf.py) | PDF 生成器(`slot-chain-spec.en.md` → LaTeX → PDF)。改 md 后运行 `python3 build-pdf.py` 重新生成并提交;`python3 build-pdf.py --check` 跑两道漂移防护——英文版是否落后于中文规范源(比对头部 sha256)、`tex/main.tex` 是否落后于英文版。需要 `texlive-xetex texlive-latex-extra texlive-pictures`(v1.49 起不再依赖 `texlive-lang-chinese`;生成器调 `xelatex``pdflatex` 也能直接编译 `tex/main.tex`)。 |
2727
| [`tex/main.tex`](tex/main.tex) / [`tex/figures.tex`](tex/figures.tex) | 论文的 LaTeX 源:`main.tex` 由生成器从 markdown 产出(一并入库,便于不装生成器也能直接编译审阅),`figures.tex` 是手写的 10 幅 TikZ 灰阶图源。编译中间件(aux/log/toc/out)不入库。 |
2828
| [`legacy-summary.md`](legacy-summary.md) | 既往工作摘要(非规范性):v15 线一段话、保留的关键结论(v15 活性事实、强制包含不可删的论证、拆分评估的坑与 v2 解法对照、在线核实过的外部先例)、原始文档的 git 历史索引。 |

packages/protocol/docs/preconfirmation-v2/build-pdf.py

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -640,9 +640,14 @@ def check_translation_sync():
640640

641641

642642
def compile_pdf():
643+
# -V 4 让 xdvipdfmx 输出 PDF 1.4:经典 xref 表 + trailer 字典,不用对象流
644+
# (/ObjStm) 和交叉引用流 (/XRef)。后者是 PDF 1.5 的默认结构,体积小约 28%,
645+
# 但只实现 PDF 1.4 的老解析器(不少电子书阅读器、电纸书固件属于此类)找不到
646+
# `trailer` 关键字就报"文件已损坏"。这里用体积换可打开性。
643647
for run in range(3):
644648
r = subprocess.run(["xelatex", "-interaction=nonstopmode",
645-
"-halt-on-error", "main.tex"],
649+
"-halt-on-error",
650+
"-output-driver=xdvipdfmx -V 4 -q", "main.tex"],
646651
cwd=TEXDIR, capture_output=True, text=True)
647652
if r.returncode != 0:
648653
log = os.path.join(TEXDIR, "main.log")
179 KB
Binary file not shown.

0 commit comments

Comments
 (0)