docs: --page-size=A4|Letter|... named-size shortcut for write/page-layout

[sebsnyk]

Summary

v0.19 added --page-width / --page-height on gog docs write and gog docs page-layout (closes #629). Setting A4 today requires the explicit numbers:

gog docs write <id> --page-width=595.275pt --page-height=841.89pt --margin-left=36pt --margin-right=36pt --margin-top=36pt --margin-bottom=36pt

Would be more ergonomic to accept named sizes:

gog docs write <id> --page-size=A4
gog docs page-layout <id> --page-size=Letter

Suggested set

Common print sizes the CLI could map to PT:

Name	Width (pt)	Height (pt)	Notes
A4	595.275	841.890	ISO 216
A5	419.528	595.275	ISO 216
Letter	612	792	US 8.5×11 in
Legal	612	1008	US 8.5×14 in
Tabloid	792	1224	US 11×17 in

Behaviour: --page-size=<name> sets both width and height in one go; mutually exclusive with --page-width / --page-height (or, if both passed, explicit dims override the named preset).

Why

• Removes the magic-number footgun (841.890 is easy to mistype)
• Matches how customers actually think about page layouts ("A4" vs "841.89pt")
• Trivial to add — internal lookup table, no API change needed

Workaround

Pass explicit --page-width=595.275pt --page-height=841.89pt until shipped.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve.

Latest ClawSweeper review: 2026-05-22 21:13 UTC / May 22, 2026, 5:13 PM ET.

Workflow note: Future ClawSweeper reviews update this same comment in place.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Summary
Keep open. Current main and v0.19 only expose explicit page width and height controls; named page-size presets would be a small new CLI feature, not an already-implemented or superseded request.

Reproducibility: not applicable. this is a request for a new shortcut flag rather than a broken existing behavior. Source inspection confirms current main only accepts explicit dimension flags for this path.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Next step
Manual review is needed because the request adds a new CLI flag and needs maintainer agreement on preset names and conflict behavior before implementation.

Review details

Best possible solution:

Add a shared named-size preset on DocsLayoutFlags only after maintainers choose the flag semantics, then cover both docs write and docs page-layout in implementation tests and generated docs.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this is a request for a new shortcut flag rather than a broken existing behavior. Source inspection confirms current main only accepts explicit dimension flags for this path.

Is this the best way to solve the issue?

Unclear until maintainers accept the new CLI surface. If accepted, the narrowest maintainable implementation is a shared preset lookup in DocsLayoutFlags feeding the existing width and height update path.

Label changes:

• add P3: This is a low-risk CLI ergonomics feature request for Google Docs page layout flags.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P3: This is a low-risk CLI ergonomics feature request for Google Docs page layout flags.

Acceptance criteria:

• go test ./internal/cmd -run 'TestDocs(PageLayout|Write).*Page'
• make docs or the repository's generated-command-docs update path after adding the flag

What I checked:

• Current flag surface: DocsLayoutFlags contains --page-width, --page-height, and margin flags, with no named --page-size field. (internal/cmd/docs_layout.go:13, 4dcf7b103dd3)
• Current implementation path: The document style builder independently parses page-width and page-height and applies them to pageSize.width and pageSize.height; there is no preset lookup path. (internal/cmd/docs_layout.go:91, 4dcf7b103dd3)
• Docs write help: Generated command docs for gog docs write list --page-height and --page-width, but not --page-size. (docs/commands/gog-docs-write.md:54, 4dcf7b103dd3)
• Page-layout docs help: Generated command docs for gog docs page-layout also expose only explicit width and height flags for page sizing. (docs/commands/gog-docs-page-layout.md:39, 4dcf7b103dd3)
• Regression coverage for existing behavior: Existing tests cover explicit dimensions such as --page-width=8.5in --page-height=11in, which matches the v0.19 feature but not the requested named-size shortcut. (internal/cmd/docs_set_page_layout_test.go:209, 4dcf7b103dd3)
• History provenance: Blame points the current Docs layout flag implementation to the v0.19.0 release commit, which added explicit dimensions and margins rather than named presets. (internal/cmd/docs_layout.go:13, b25a3c029b37)

Likely related people:

• Peter Steinberger: Git blame and file history point the current Docs layout flag implementation and generated docs to the v0.19.0 release commit authored by Peter Steinberger. (role: recent area contributor; confidence: high; commits: b25a3c029b37; files: internal/cmd/docs_layout.go, internal/cmd/docs_set_page_layout.go, internal/cmd/docs_edit.go)
• sebsnyk: The reporter supplied this named-size request and the related page-width/page-height issue context that led to the v0.19 Docs layout ergonomics work. (role: reporter with workflow context; confidence: medium)

Remaining risk / open question:

• The remaining decision is UX/API shape: accepted preset names and whether --page-size is mutually exclusive with explicit dimensions or overridden by them.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 4dcf7b103dd3.