Skip to content

feat: add taskbook/proposal/midterm documents via doctype option - #128

Open
RizhongLin wants to merge 9 commits into
devfrom
feat/doctype-forms
Open

feat: add taskbook/proposal/midterm documents via doctype option#128
RizhongLin wants to merge 9 commits into
devfrom
feat/doctype-forms

Conversation

@RizhongLin

@RizhongLin RizhongLin commented Jul 22, 2026

Copy link
Copy Markdown
Member

概要 | Summary

请简要描述本 PR 所做的工作 | Brief description of the changes:

  • 新增 doctype 类选项(thesis(默认)/ taskbook / proposal / midterm),与既有 degree / field / algo 选项模式一致。默认值不变,main.tex 的论文正文流程不受影响;未知取值回退到 thesis 并给出 \ClassWarning。同时新增 \iftongjithesis@form 条件,表示“doctype 为 3 份表格之一”,供三者行为一致处使用。
    New doctype class option (thesis (default) / taskbook / proposal / midterm), following the existing degree / field / algo pattern. The default is unchanged, so main.tex's thesis flow is unaffected; an unrecognized value falls back to thesis with a \ClassWarning. Also adds an \iftongjithesis@form conditional meaning "doctype is one of the three forms", for the many places where all three behave alike.

  • 新增 3 个可独立编译的行政文档入口:taskbook.tex(任务书)、proposal.tex(开题报告)、midterm.tex(中期报告)。三者与正文共用 chapters/metadata.tex 的学院/专业/学生/课题信息(指导教师在 3 份表格中均为手写签字位,不预填),结构一致:\input{chapters/metadata}\MakeDocument(按 doctype 分派到 \MakeTaskBook / \MakeProposal / \MakeMidterm)→ \input{chapters/{taskbook,proposal,midterm}_body},无 frontmatter/mainmatter/参考文献阶段。正文段落内容采用与 chapters/appendix.tex 一致的“编辑替换示例文字”模式。
    Three new standalone entry points — taskbook.tex, proposal.tex, midterm.tex — sharing the school/major/student/topic fields from chapters/metadata.tex (the advisor is a handwritten signature slot on all three forms and is never prefilled). All three have the same shape: \input{chapters/metadata}\MakeDocument (dispatching to \MakeTaskBook / \MakeProposal / \MakeMidterm by doctype) → \input{chapters/{taskbook,proposal,midterm}_body}, with no frontmatter/mainmatter/bibliography stages. Body content follows the same edit-the-sample-text pattern as chapters/appendix.tex.

  • 新增 .cls 排版原语,使 chapters/*_body.tex 只写内容、不手动设置字体字号:\tjformtable(无边框信息表,仅靠下划线呈现填空位置)、\tjformsection / \tjformsubsection(一/二级分节标题)、\tjformnotice + tjformnoticebody(说明页标题与条目)、\tjformlabel(审核意见框字段标签)、\tjformsignature(签字行)、\tjreviewbox(审核意见方框)、\tjdateblank\tjnumline,以及 \tjformnote / \tjformhint 两级灰度批注——前者为成稿时应删除的说明文字,后者为保留在表格中的内容提示。
    New .cls primitives so chapters/*_body.tex carries content only, never manual font/size switches: \tjformtable (borderless info table, fill-in positions shown by underlines alone), \tjformsection / \tjformsubsection (level-1/2 headings), \tjformnotice + tjformnoticebody, \tjformlabel (review-box field labels), \tjformsignature (signature lines), \tjreviewbox, \tjdateblank, \tjnumline, and two semantically distinct gray annotations — \tjformnote for text to delete before finalizing, \tjformhint for guidance that stays on the form.

  • 三份表格的字体字号按撰写规范设定:封面大标题小初号黑体,课题信息表四号宋体;一级分节标题四号黑体,开题报告二级标题小四号黑体;审核意见框内的字段标签与签字行(含年/月/日)为小四号黑体,同框内的灰色提示与“同意/不同意”复选框行保持宋体;任务书正文末尾签字行为四号黑体;中期报告“填写说明”标题小二号黑体加粗、条目四号,封面填表日期三号。\tjformtable 显式声明 \songti,不依赖文档默认字族。
    Typography follows the writing spec throughout: cover titles 小初黑体 and subject tables 四号宋体; level-1 headings 四号黑体 and the proposal's level-2 headings 小四黑体; review-box field labels and signature lines (including 年/月/日) 小四黑体, while the gray hints and the 同意/不同意 checkbox line inside the same box stay 宋体; the task book's trailing signature line 四号黑体; the mid-term report's 填写说明 heading 小二黑体加粗 with 四号 items, and its cover date 三号. \tjformtable declares \songti explicitly rather than inheriting the document default.

  • \taskbookperiod{起始年}{月}{日}{截止年}{月}{日}(在 chapters/metadata.tex 中设置)经 pgfcalendar 由起讫日期自动换算任务书周数(向上取整),无需手动填写;起讫日期越序时报 \ClassError。未调用时各字段保持空白下划线。
    \taskbookperiod{...} (set in chapters/metadata.tex) derives the task book's week count from the date range via pgfcalendar (ceiling-rounded), so it is never entered by hand; an inverted range raises a \ClassError. If never called, the fields render as blank underlines.

  • 复选框字形改由 \tj@checkboxglyph 统一生成:amssymb 的 $\square$ 明显小于周围汉字,故按当前字号缩放至与汉字等高,勾号限高后居中叠印在方框内,下沉量作用于整组;\mbox 包裹使复选框在段首也能正确渲染。新增通用的 \tjcheckboxeq{当前值}{目标值}\midtermdecision{agree|disagree},供中期报告“专业审核意见”按需勾选(默认留空,供打印后手写)。本项亦改变论文信息说明页“成果类型”复选框的呈现。
    Checkbox glyphs are now produced by a single \tj@checkboxglyph: amssymb's $\square$ is noticeably smaller than surrounding CJK, so the box is scaled to match, the mark is height-limited and overprinted centered inside it, and the vertical shift applies to the whole group. An \mbox wrapper keeps the glyph correct at paragraph start. Adds generic \tjcheckboxeq{current}{target} and \midtermdecision{agree|disagree} for the mid-term report's 专业审核意见 box (blank by default, for handwriting after printing). This also changes how the thesis info page's 成果类型 checkbox renders.

  • 三份表格使用独立页边距(A4,上 2.3cm/下 1.0cm/左右各 3.17cm),与论文正文的装订页边距不同;且全程不显示装订线——三者是单独打印/提交的行政表格,与 \MakeCover / \MakeInfoPage(仅在封面页关闭、其后随正文恢复)形成对比。
    The three forms use their own page geometry (A4, top 2.3cm / bottom 1.0cm / left and right 3.17cm), distinct from the thesis's binding margins, and never draw the binding line — they are separately printed and submitted, unlike \MakeCover / \MakeInfoPage, which disable it for the cover page only and restore it for the body that follows.

  • Makefile / make.bat 新增 taskbook / proposal / midterm / forms 目标,clean / cleanall 同步覆盖新产物;CI 新增 build-forms job(Linux + xelatex,每份文档一个矩阵项)编译全部 3 个文档,test-summarycollect-pdfs 相应更新 needs
    Makefile / make.bat gain taskbook / proposal / midterm / forms targets, with clean / cleanall covering the new outputs; CI gains a build-forms job (Linux + xelatex, one matrix leg per document) compiling all three, and test-summary / collect-pdfs were updated accordingly.

  • 全仓中文行文的引号统一为成对全角弯引号 “” / ‘’(代码/verbatim/数学撇号除外),并在 AGENTS.md 记录该约定。
    Chinese prose across the repo now uses paired curly “” / ‘’ (code/verbatim/math-prime excepted), with the convention recorded in AGENTS.md.

  • 文档同步更新:README.md / README-EN.md / CONTRIBUTING.md / AGENTS.md / chapters/01_guide.tex 记录新选项、3 份新文档、选项排序,以及 *_body.tex 中可用的排版命令。
    Docs updated across README.md / README-EN.md / CONTRIBUTING.md / AGENTS.md / chapters/01_guide.tex to cover the new option, the three new documents, option ordering, and the commands available in *_body.tex.

设计取舍 | Design decisions:

  • 键名选用 doctype 而非泛化的 type,以避免与既有的 \infotype{thesis|design|engineering} 宏(同一类中另一条“类型”轴)冲突。
    Chose doctype over a generic type to avoid colliding with the existing \infotype{thesis|design|engineering} macro — a different, pre-existing "type" axis in the same class.

  • 表格封面沿用本模板论文封面 \MakeCover 的版式(整体居中、每字段独占一行、\ulinecentered 定宽下划线,填写前后长度与位置一致、内容过长自动换行),而非逐像素复刻某一份 Word 渲染结果;字体则按各自规范取值,故两者共用版式而不共用字体。
    Form covers reuse this template's own \MakeCover layout (centered, one field per row, fixed-width \ulinecentered underlines that keep length and position whether filled or blank, wrapping when long) rather than pixel-matching any single Word rendering. Typefaces follow each document's own spec, so the two share layout but not typeface.

  • 封面大标题用半角括号(\tjformheadertext),使“开题报告 / 中期报告”标题在小初号下仍能单行排下;正文各处仍用全角括号的 \tjheadertext
    Cover titles use half-width parentheses (\tjformheadertext) so the 开题报告 / 中期报告 headings still fit on one line at 小初; body text keeps the full-width \tjheadertext.

  • 一/二级分节标题均为手工编号,不计入目录、不参与章节编号:列表环境无法把序号本身也置为黑体,且会额外引入列表缩进。
    Level-1 and level-2 headings are manually numbered and enter neither the TOC nor the chapter numbering: a list environment cannot set the label itself in 黑体, and would add its own indentation.

检查清单 | Checklist

  • 已通读贡献指南
  • 如涉及模板功能变更,已编写注释并更新对应文档。
  • 如涉及模板功能变更,已尽可能在各平台上进行测试。
    • CI 覆盖:build(3 OS × {XeLaTeX, LuaLaTeX})、build-variants、新增的 build-forms(3 份文档各一个矩阵项)、test-summarycollect-pdfspackage;结果以本 PR 的 Checks 页为准。
    • 本地:make(默认选项)与 make taskbook / make proposal / make midterm 均编译通过,3 份表格零 Overfull/Underfull 警告。
    • 选项组合:doctype={taskbook,proposal,midterm} × field=humanities 均编译通过,封面标题与分节标题按 field 正确切换且仍单行排下。
    • 复选框:\midtermdecision{agree} 在段首正确渲染(勾号完整落在方框内),信息说明页 \tjcheckbox 的判断逻辑不变。
    • 逐页目视核对全部封面与正文页(课题信息表、签字区、审核意见框、复选框、起讫时间下划线)。

已知事项 | Known items:

  • main.tex 相对 dev 新增若干 Underfull \hbox 提示,全部位于 chapters/01_guide.tex:新增说明段落中的长 \verb 记号不可断行,两端对齐时行内空格被拉伸。仅影响手册排版观感,不影响版面结构。
    Relative to dev, main.tex gains a number of Underfull \hbox messages, all in chapters/01_guide.tex: long \verb tokens in the new documentation cannot be broken, so justified lines stretch their interword spaces. Cosmetic to the manual only; no structural effect.

关联 Issue | Related Issues

无 | None.

截图 | Screenshots

模板输出有变化:新增 3 份文档,并改变了论文信息说明页复选框的呈现。各文档编译产物可从本 PR 的 CI collect-pdfs artifact 下载核对。
The template output changes: three new documents, plus a different rendering of the thesis info page's checkbox. Compiled PDFs for every document can be downloaded from this PR's CI collect-pdfs artifact.

Adds support for 3 official Tongji administrative documents alongside the
thesis: 毕业设计(论文)任务书 (task book), 开题报告 (opening/proposal report),
and 中期报告 (mid-term report). Each is its own compilable entry point
(taskbook.tex/proposal.tex/midterm.tex) sharing chapters/metadata.tex's
school/major/student/title/advisor fields with the thesis.

- New `doctype` kvoption (thesis|taskbook|proposal|midterm, default thesis)
  drives a `\MakeDocument` dispatcher, mirroring the existing degree/field/algo
  option pattern. Default is unchanged, so main.tex's thesis flow is
  unaffected.
- New cls building blocks: \tjformtable (bordered form table), \tjformnote/
  \tjformhint (the two shades of gray annotation text used in the official
  templates), \tjformsection, \tjdateblank, \tjreviewbox, and \taskbookperiod
  (auto-computes the task book's duration in weeks from start/end dates via
  pgfcalendar, ceiling-rounded).
- Body content for each document lives in chapters/{taskbook,proposal,midterm}
  _body.tex, following the same input-and-edit pattern as chapters/appendix.tex.
- Makefile/make.bat gain taskbook/proposal/midterm/forms targets; clean/
  cleanall cover the new outputs too.
- CI: new build-forms job (Linux+xelatex, matching build-variants' scope)
  compiles all 3 documents; test-summary and collect-pdfs updated accordingly.
- README.md/README-EN.md/CONTRIBUTING.md/chapters/01_guide.tex updated to
  document the new option and documents.

Verified locally: all 3 new documents compile with zero warnings (2/3/4 pages
respectively, matching the official templates' structure), including under
the humanities and twoside variants; main.tex's own compile is unaffected.
Visual comparison against the official .doc templates (rendered via
LibreOffice for high-fidelity page geometry, since the earlier textutil-based
extraction had defaulted to Letter paper and dropped tables) surfaced real
fidelity gaps in the taskbook/proposal/midterm forms added in the previous
commit:

- Page margins were inheriting the thesis body's asymmetric binding-offset
  geometry (top=4.0cm/bottom=2.7cm/left=3.3cm/right=1.8cm) instead of the 3
  forms' own official margins (A4, top=2.3cm/bottom=1.0cm/left=right=3.17cm,
  symmetric) — now geometry branches on doctype.
- The subject-info table and signature block were drawn with a visible
  bordered grid; the official templates use no visible borders at all, just
  underlined blanks (matching \MakeCover's own information-environment
  convention) — removed colortbl/border styling accordingly.
- The 同济大学 calligraphic university-name graphic (figures/tongji.pdf,
  already used by \MakeCover) was missing from the top of all 3 forms.
- The whole cover block was centered; the official templates only center the
  title, with the subject table and signature block flush left — restructured
  \MakeTaskBook/\MakeProposal/\MakeMidterm accordingly (and fixed the
  resulting \parindent-before-tabular overfull that surfaced once the
  \begin{center} wrapper was removed).

Also updates AGENTS.md (untouched by the previous commit despite being the
primary agent-facing architecture doc) and CONTRIBUTING.md's repository-
structure bullet to reflect the new doctype option, the 4 compilation entry
points, and the new .cls macros.

Verified: all 3 documents recompile with zero warnings; re-rendered and
visually re-compared page-by-page against the official LibreOffice-rendered
PDFs after each fix.
A code-reviewer pass found that \taskbookperiod's week count used
\numexpr's "/" for the ceiling-division trick (delta+7)/7, but \numexpr
rounds to nearest rather than truncating (unlike \divide), so the computed
week count silently over-counted by one for date ranges landing on certain
day-of-week residues — verified empirically against a truncating reference
across a range of deltas. Fixed by computing the sum with \numexpr and
truncating with \divide, which is what the "向上取整" (round up) comment
already claimed the code did.

Also fixes several Chinese phrases flagged as reading translated-from-
English rather than natural: the doctype option's `thesis` row in both
chapters/01_guide.tex tables ("本文档描述的论文正文流程,不受影响" and
"...流程,不受本节影响" both leaned on 流程/不受...影响 in a way that read
stiff — rewritten as direct statements matching the terse style of the
sibling table rows), plus two tongjithesis.cls implementation comments
found by an independent native-speaker fluency review (装订 reused to mean
"box register assembled" despite already meaning "bookbinding" elsewhere
in the same file; a redundant 随后随... construction).

Verified: all 4 documents recompile with zero new warnings; the shipped
default \taskbookperiod{2026}{9}{1}{2027}{6}{30} example still renders
"共 44 周", unchanged by the fix (its residue didn't trigger the bug).
…mark overhaul

- New \tjcheckboxeq{current}{target} generalizes the existing \tjcheckbox
  comparison pattern (previously info-page-specific) for reuse elsewhere.
  \midtermdecision{agree|disagree} uses it to make the mid-term report's
  "同意/不同意" checkbox pair flippable from chapters/metadata.tex, matching
  how \infotype already drives the info page's checkboxes. Defaults to both
  boxes unchecked (the printed form is normally hand-checked by the reviewer
  after printing). Documented in chapters/01_guide.tex and metadata.tex.

- main.tex now explicitly lists `doctype=thesis` (previously implicit via
  the option's default) for discoverability, since it's now a documented
  option alongside the others. Also reorders the whole \documentclass[...]
  option block into three tiers — document structure (doctype, oneside,
  degree, field), content-rendering backends (algo, minted, biblatex), then
  typography (fontset, times, fullwidthstop) — applied consistently to
  main.tex, README.md, README-EN.md, and chapters/01_guide.tex's option
  table. Verified the build-variants CI job's sed substitutions still match
  correctly against the reordered block (substring-based, position-
  independent).

- Repo-wide quotation-mark overhaul: converts every straight ASCII "/'
  and traditional corner-bracket 「」/『』 quote in Chinese prose (comments
  in tongjithesis.cls, chapters/*.tex, README.md, CONTRIBUTING.md) to
  properly-paired curly “”/‘’, matching modern Chinese typographic
  convention. Deliberately left untouched: literal string-delimiter quotes
  inside code demos (chapters/03_float.tex's Python listings, matching
  \verb|print("Hello")|) since those are actual code syntax, and the bare
  ' in math-mode derivative notation ($f'(x)$). Documented the convention
  and its exceptions in AGENTS.md.

Verified: all 4 documents recompile with zero new warnings; checkbox flip
confirmed via an isolated compile test (agree/disagree correctly toggle
which box shows a checkmark); quote-pairing verified balanced (equal open/
close counts) across every touched file.
- Form title: 小初 (36pt) 黑体 via \tjfontformtitle; half-width parens
  (\tjformheadertext) so 开题报告/中期报告 headings fit one line
- Logo sized to 1.7cm on the three form covers
- Rework the shared subject table to mirror \MakeCover: centered, one
  field per row, \ulinecentered fixed-width underlines (underline length
  and position stay identical whether a field is filled or blank)
- \tjnumline: 起讫 date numbers sit on fixed-width underlines too
- \tjformsection: 四号黑体, 2em indent
- Body demo prompts rendered as gray hints instead of black body text
- Taller review boxes; signatures use one fixed-width underline per line
- cfg: document the fallback default for \tongjitaskbookweeks
- Reword comments so the Word reference is not called the sole
  '官方模板' (this template is equally official)
\tjnumline used LaTeX's \underline (a heavier/differently-placed rule)
while every other cover underline uses ulem's \uline via \ulinebox /
\ulinecentered. Switch \tjnumline to \uline so all underlines on the
form covers share the same weight and baseline offset.
- \tjchecked wrapped in \mbox: the bare \rlap misbehaves as the first
  box of a paragraph (checkmark detaches, both boxes render empty),
  which broke \midtermdecision{agree} in the midterm review box — the
  one documented use. \mbox forces horizontal mode so the checkmark
  stays inside its box. Info-page \tjcheckbox rendering is unchanged.
- \tongjitaskbookweeks now defaults to empty like the other task-book
  date fields, so an unset week count shows a blank underline instead
  of a stale '32' next to blank date fields. \taskbookperiod still
  fills the computed value on the normal path.
@RizhongLin
RizhongLin force-pushed the feat/doctype-forms branch from 8d3699d to a06bd45 Compare July 22, 2026 21:25
@RizhongLin RizhongLin changed the title feat: add taskbook/proposal/midterm document types via doctype option feat: add taskbook/proposal/midterm documents via doctype option Jul 30, 2026
Audited every text run in the three administrative forms against the
writing spec and fixed the mismatches:

- 开题报告 level-2 headings (1./2./3.) were 宋体; they are 小四黑体.
  The enumerate is replaced by a new \tjformsubsection, because a list
  label cannot itself be set in 黑体.
- Review-box field labels (指导教师意见:/专业审核意见:) and signature
  lines including 年/月/日 were 宋体; they are 小四黑体. New \tjformlabel
  and \tjformsignature scope the switch so the gray hints and the
  同意/不同意 checkbox line inside the same box stay 宋体.
- 任务书 trailing signature line was 小四宋体; it is 四号黑体.
- 中期报告 填写说明 heading was 三号; it is 小二. Its items were 小四;
  they are 四号, now via a tjformnoticebody environment rather than a
  raw \zihao in a writer-editable body file.
- 中期报告 cover date row was 四号; it is 三号.
- \tjformtable now declares \songti instead of inheriting the document
  default: the form info tables are 四号宋体, unlike \MakeCover's
  小二号黑体, so the two share layout but not typeface.

Checkbox glyphs are rebuilt on \tj@checkboxglyph: amssymb's $\square$ is
much smaller than surrounding CJK, so the box is scaled to match, the
mark is height-limited to stay inside it, and the vertical shift now
applies to the whole group — previously only the box moved, so the mark
crossed the top border. Also affects the thesis info page's 成果类型 row.

The three doctype geometry branches were byte-identical; they now sit
behind one \iftongjithesis@form conditional.

01_guide.tex documents the body-editing commands, and drops the claim
that the forms share \thesisadvisor — no form reads it, the advisor is a
handwritten signature slot on all three.
The README pair claimed the three forms share 指导教师 information from
metadata.tex; no form reads \tongjithesisadvisor. Both mirrors now say
the advisor is a handwritten signature slot. Their cleanall description
still mentioned only main.pdf, but clean/cleanall sweep the form PDFs too.

AGENTS.md documents \iftongjithesis@form and lists the form layout
primitives added since the section was written. Hardcoded counts are
removed rather than updated — a line count, a file count and a matrix-leg
count had all drifted, and refreshing them just resets the same trap.
Spec values such as the 0.74cm hanging indent stay: those describe the
specification, not our code.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant