Open-MBEE · HuiJun · Sep 24, 2026 · Sep 24, 2026 · Sep 24, 2026 · Sep 24, 2026
diff --git a/changes/unreleased/document-convention-themes.added.md b/changes/unreleased/document-convention-themes.added.md
@@ -0,0 +1,2 @@
+- **Three convention themes for `-html-theme`: `nasa`, `ieee` and `acm`.** Each follows a published manuscript convention — the NASA STI Report Series (Times 12pt body, Arial headings, tables and captions, letter page with one-inch margins, roman-numbered front matter), IEEE Transactions (Times 10pt body, 8pt captions and tables, centred small-caps section heads, italic subheads, justified with a one-pica indent, letter page with 0.67in margins) and ACM's `acmart` (Libertine 10pt body falling back to Times, bold sans numbered heads, 9pt captions, letter page) — black on white, with thin horizontal table rules, and sets the same faces and point sizes on screen as on paper so a page and its PDF agree. IEEE and ACM output is single-column; the sources, the values verified against them and the choices made where a convention is silent are recorded in `docs/project/html-document-backend.md`.
+- **A theme now governs the PDF page.** A bundled theme may carry a print companion, `themes/<name>.print.css`, which the PDF backend lays over its print stylesheet in a third cascade layer, `opensysml-print-theme`, so the theme's page size and margins, faces, body size, heading scale, caption and table sizes and page-number footer reach paper instead of being overwritten by the print sheet's defaults; the `print` and `report` themes carry one too, so `report`'s Charter/Georgia stack and larger body now print. The order is the default sheet and theme, the print sheet, the theme's companion, then `-html-css` sheets unlayered; `-html-no-default-css` leaves every bundled sheet out, and the pandoc engine still refuses `-html-theme`.
diff --git a/changes/unreleased/pdf-default-font-stack.fixed.md b/changes/unreleased/pdf-default-font-stack.fixed.md
@@ -0,0 +1 @@
+- **A PDF's default faces are Times, Arial and Courier, not whatever the generic family resolves to.** The print stylesheet asked for bare `serif`, `sans-serif` and `monospace`, which fontconfig resolves to DejaVu on most Linux machines — a face some 15 % wider and taller than Times at the same nominal size, so an 11pt page read like 13pt — while the metric-compatible Liberation faces installed beside it were never chosen. The default body, heading, code and page-number stacks now name the conventional families first, their free metric-compatible equivalents next (`"Times New Roman", Times, "Liberation Serif", "Nimbus Roman", serif`; `Arial, Helvetica, "Liberation Sans", "Nimbus Sans", sans-serif`; `"Courier New", Courier, "Liberation Mono", "Nimbus Mono PS", monospace`) and the generic family last, for the pandoc engine's page as for WeasyPrint's and Prince's. Page size, margins and every point size are unchanged, and the HTML page keeps its system face.
diff --git a/cmd/sysml/render_document_html_test.go b/cmd/sysml/render_document_html_test.go
@@ -352,7 +352,7 @@ func TestRenderDocumentHTMLTheme(t *testing.T) {
 	wantReport(t, runCommand(t, exec.Command(binary, "-html-default-css", "-html-theme", "print")),
 		0, "@layer opensysml;", "/* print:")
 	wantReport(t, runCommand(t, exec.Command(binary, "-html-default-css", "-html-theme", "fancy")),
-		2, `no bundled theme is named "fancy"`, "default, modern, print, report")
+		2, `no bundled theme is named "fancy"`, "default, acm, ieee, modern, nasa, print, report")
 
 	wantReport(t, check(t, binary, documentModel, "-render-document", "Reports::MassReport",
 		"-doc-form", "html", "-html-theme", "fancy"), 2, `no bundled theme is named "fancy"`)

diff --git a/cmd/sysml/usage.go b/cmd/sysml/usage.go
@@ -432,7 +432,8 @@ func doc() usage.Doc {
 					"these tools is needed until PDF output is asked for; " +
 					"scripts/download-doc-pdf-toolchain.sh provisions pinned copies.",
 				"HTML output needs nothing external and loads nothing by default: -html-theme " +
-					"picks one of the bundled looks (default, modern, print, report), -html-css adds " +
+					"picks one of the bundled looks (default, acm, ieee, modern, nasa, print, report; " +
+					"acm, ieee and nasa follow those bodies' manuscript conventions), -html-css adds " +
 					"your own stylesheets, -html-no-default-css drops the default one, " +
 					"-html-fragment writes the document element alone to embed in a " +
 					"page of yours, and -html-default-css writes the default sheet out " +
@@ -604,7 +605,7 @@ func registerFlags(fs *flag.FlagSet) {
 	fs.BoolVar(&pdfNumbering, "doc-number-sections", false, "Number the section headings hierarchically (html or pdf)")
 	fs.StringVar(&pdfEngine, "pdf-engine", "", "Converter -doc-form pdf drives: weasyprint (default), pandoc or prince")
 
-	fs.StringVar(&htmlTheme, "html-theme", "", "Style the HTML page or PDF with a bundled theme layered over the default stylesheet: default, modern, print or report")
+	fs.StringVar(&htmlTheme, "html-theme", "", "Style the HTML page or PDF with a bundled theme layered over the default stylesheet: default, acm, ieee, modern, nasa, print or report")
 	fs.Var(&htmlCSS, "html-css", "Style the HTML or PDF with this stylesheet too: a file is inlined, a URL is linked (repeatable, applied in order after the default sheet)")
 	fs.BoolVar(&htmlNoCSS, "html-no-default-css", false, "Leave the default stylesheet out, so only -html-css sheets style the HTML or PDF")
 	fs.BoolVar(&htmlFragment, "html-fragment", false, "Write the document element alone, without the page shell or a stylesheet, to embed in a page of your own")

diff --git a/docs/manual/outputs.md b/docs/manual/outputs.md
@@ -169,7 +169,7 @@ renderer emits no `style` attributes to compete with.
 
 | Flag | Effect |
 |---|---|
-| `-html-theme <name>` | Layer a bundled theme over the default sheet: `default`, `modern`, `print` or `report` |
+| `-html-theme <name>` | Layer a bundled theme over the default sheet: `default`, `acm`, `ieee`, `modern`, `nasa`, `print` or `report` |
 | `-html-default-css` | Write the default sheet and exit, to copy from; with `-html-theme`, the theme's whole sheet |
 | `-html-css <file\|url>` | Add a sheet after the default one: a file is inlined, a URL is linked (repeatable, applied in order) |
 | `-html-no-default-css` | Leave the default sheet out |
@@ -185,6 +185,17 @@ unlayered CSS still wins over both:
 | `modern` | Clean corporate sans-serif: filled table headers, zebra rows, rounded surfaces for code and contents |
 | `report` | Formal technical report: serif body, wider measure, open tables ruled top and bottom, captions above |
 | `print` | Monochrome and compact for paper: black rules, no fills, tables and figures kept whole across page breaks, external links spelled out |
+| `nasa` | NASA STI report series: Times 12pt body, Arial headings, tables and captions, letter page with 1in margins, page numbers centred below, black on white |
+| `ieee` | IEEE Transactions manuscript: Times 10pt body, 8pt captions and tables, centred small-caps section heads, italic subheads, justified with a 1pc indent, letter page with 0.67in margins, single column |
+| `acm` | ACM article (`acmart`): Libertine 10pt body falling back to Times, bold sans numbered heads, 9pt captions, letter page with 1in margins, single column |
+
+The three convention themes set their faces and point sizes on screen as on
+paper, so a page and its PDF agree. The Libertine fonts `acm` names are
+rarely installed, so Times metrics are what most machines print; and none of
+the three lays out two columns or writes a cover beyond the title, since the
+document model carries no report number, authors or affiliations. The
+sources and the choices made where a convention is silent are recorded in
+[the backend's design notes](../project/html-document-backend.md#bundled-themes).
 
 A theme needs the default sheet under it, so it is refused with
 `-html-no-default-css`, and a fragment has no page to style, so it is refused
@@ -242,15 +253,23 @@ of tables and figures, the title page and contents on pages of their own —
 is declared in a second cascade layer after the default sheet:
 
 ```css
-@layer opensysml;        /* the default sheet, or the theme over it */
-@layer opensysml-print;  /* the PDF backend's print sheet */
+@layer opensysml;              /* the default sheet, or the theme over it */
+@layer opensysml-print;        /* the PDF backend's print sheet */
+@layer opensysml-print-theme;  /* the theme's print companion, when it has one */
 ```
 
-Both layers draw their values from the same `--sysml-*` tokens and write no
-`style` attributes, so `-html-theme` rethemes a PDF as it does a page,
-`-html-css` sheets apply unlayered after both layers and win on cascade
-origin, and `-html-no-default-css` leaves both layers out so that only your
-sheets — `@page` rules included — style the PDF. A sheet's relative `url()`
+A theme that means to govern paper carries a print companion — `print`,
+`report`, `nasa`, `ieee` and `acm` do — that the PDF backend lays over the
+print sheet in the third layer, so the theme's page size and margins, faces,
+body size, heading scale and page-number footer reach the PDF rather than
+being overwritten by the print sheet's defaults. All three layers draw their
+values from the same `--sysml-*` tokens and write no `style` attributes, so
+`-html-theme` rethemes a PDF as it does a page, `-html-css` sheets apply
+unlayered after every layer and win on cascade origin, and
+`-html-no-default-css` leaves every bundled layer out so that only your
+sheets — `@page` rules included — style the PDF. Without a theme, the PDF is
+set in Times, Arial and Courier where they are installed and in their
+metric-compatible free equivalents (Liberation, Nimbus) where they are not. A sheet's relative `url()`
 and `@import` references resolve against the PDF's directory, as a page's
 resolve against the page's. The pandoc engine reads Markdown and writes its
 own HTML, so `-html-theme` and `-html-no-default-css` are refused for it,
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		- Three convention themes for `-html-theme`: `nasa`, `ieee` and `acm`. Each follows a published manuscript convention — the NASA STI Report Series (Times 12pt body, Arial headings, tables and captions, letter page with one-inch margins, roman-numbered front matter), IEEE Transactions (Times 10pt body, 8pt captions and tables, centred small-caps section heads, italic subheads, justified with a one-pica indent, letter page with 0.67in margins) and ACM's `acmart` (Libertine 10pt body falling back to Times, bold sans numbered heads, 9pt captions, letter page) — black on white, with thin horizontal table rules, and sets the same faces and point sizes on screen as on paper so a page and its PDF agree. IEEE and ACM output is single-column; the sources, the values verified against them and the choices made where a convention is silent are recorded in `docs/project/html-document-backend.md`.
		- A theme now governs the PDF page. A bundled theme may carry a print companion, `themes/<name>.print.css`, which the PDF backend lays over its print stylesheet in a third cascade layer, `opensysml-print-theme`, so the theme's page size and margins, faces, body size, heading scale, caption and table sizes and page-number footer reach paper instead of being overwritten by the print sheet's defaults; the `print` and `report` themes carry one too, so `report`'s Charter/Georgia stack and larger body now print. The order is the default sheet and theme, the print sheet, the theme's companion, then `-html-css` sheets unlayered; `-html-no-default-css` leaves every bundled sheet out, and the pandoc engine still refuses `-html-theme`.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		- A PDF's default faces are Times, Arial and Courier, not whatever the generic family resolves to. The print stylesheet asked for bare `serif`, `sans-serif` and `monospace`, which fontconfig resolves to DejaVu on most Linux machines — a face some 15 % wider and taller than Times at the same nominal size, so an 11pt page read like 13pt — while the metric-compatible Liberation faces installed beside it were never chosen. The default body, heading, code and page-number stacks now name the conventional families first, their free metric-compatible equivalents next (`"Times New Roman", Times, "Liberation Serif", "Nimbus Roman", serif`; `Arial, Helvetica, "Liberation Sans", "Nimbus Sans", sans-serif`; `"Courier New", Courier, "Liberation Mono", "Nimbus Mono PS", monospace`) and the generic family last, for the pandoc engine's page as for WeasyPrint's and Prince's. Page size, margins and every point size are unchanged, and the HTML page keeps its system face.