paper-muncher: Remove subcommands and improve configuration of overflow behavior.

[sleepy-monax]

This PR focuses on making Paper Muncher easier to use for first-time users and adds more flexible overflow handling. The CLI no longer requires subcommands, and new overflow modes make it possible to generate continuous single-page PDFs.

Simplified CLI

You can now just run:

paper-muncher index.html -o output.pdf

Why --overflow

The parameter name comes from CSS’s own overflow property, which defines how content that exceeds its container is handled. Paper Muncher now exposes the same concept at the document level, deciding what happens when rendered content exceeds the page boundaries.

paginate - split content into multiple pages
crop - crop content to the page size
visible - render only visible content
auto - automatically choose based on output format

[Copilot]

Pull Request Overview

This PR simplifies Paper Muncher's CLI by removing the print and render subcommands, consolidating them into a single unified command. It introduces a new --overflow parameter to control how content that exceeds page boundaries is handled, with modes including auto, paginate, crop, and visible.

Key changes:

• Removed separate print and render subcommands in favor of a streamlined single-command interface
• Added new Overflow enum and --overflow flag to control pagination behavior
• Renamed --unsecure flag to --sandboxed with inverted logic for better clarity
• Consolidated PrintOption and RenderOption into a unified Option struct

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/mod.cpp	New module exporting the unified run function with Overflow enum and consolidated Option struct
src/main.cpp	Removed subcommands, consolidated CLI arguments, and integrated new overflow parameter
readme.md	Updated basic usage examples to reflect simplified CLI
meta/plugins/reftest.py	Updated test command to use --overflow paginate instead of print subcommand
doc/usage.md	Removed separate command sections and consolidated documentation
doc/install.md	Updated installation example to use simplified command

[Louciole]

First : i agree with the technical refactoring, it's great and needed.

but I don't really know if --overflow is the best option, while it's descriptive it implies that there is a possible overflow

Wich is false. if the box grow it's not overflowing, if we paginate neither. and this behavior is only possible in the Y axis.
It's not too bad but I prefer : --pagination (auto|true|false) (maybe the crop should be at users discretion in their CSS and not a PM option)

[sleepy-monax]

@Louciole it’s called --overflow because it mirrors how the ui handles content exceeding the viewport (scrollableOverflow). It’s not about CSS boxes but about what happens when the document is larger than the render area.

--pagination only covers part of that; it can’t express visible (expand canvas to fit full content). --overflow stays broader and future-proof.

edit: crop should be the default; otherwise, the image size can become unpredictable for users. Also, letting CSS control viewport behavior is odd, since itself can already be managed through media queries, creating a weird dependency loop.

[Louciole]

@Louciole it’s called --overflow because it mirrors how the ui handles content exceeding the viewport (scrollableOverflow). It’s not about CSS boxes but about what happens when the document is larger than the render area.

I understand that but you didn't address my concerns

--pagination only covers part of that; it can’t express visible (expand canvas to fit full content). --overflow stays broader and future-proof.

Pagination false should be visible, crop is a weird use case that only make sense for images in my opinion
I'm not attached to '--pagination' and I understand your concerns, we can maybe find something better !

edit: crop should be the default; otherwise, the image size can become unpredictable for users. Also, letting CSS control viewport behavior is odd, since itself can already be managed through media queries, creating a weird dependency loop.

Mhhhh since we allow sizing in CSS having both options is REALLY odd, if the document is set to A4 and then we try to convert it to demi-raisin because it's what the users put in their CLI it should stay A4 in my opinion (more flexible and compliant with CSS's spec), documents knows their sizes (except for non paginated documents where we should listen for the CLI)

[sleepy-monax]

@Louciole

while it's descriptive it implies that there is a possible overflow

This flag defines the policy for what happens when overflow occurs.

Wich is false. if the box grow it's not overflowing, if we paginate neither. and this behavior is only possible in the Y axis.

The Y-axis part isn’t accurate. Overflow can occur on both X and Y. Right now, pagination only applies vertically, but there are potential use cases for horizontal overflow, for example, SVG backgrounds or multi-column layouts in illustrated books with full-spread images.

Pagination false should be visible, crop is a weird use case that only make sense for images in my opinion
I'm not attached to '--pagination' and I understand your concerns, we can maybe find something better !

--overflow felt like the least-worst name: technically accurate, broad enough to cover different cases, and already aligned with existing terminology. Since auto handles most use cases, I think a technical name works fine here. There’s still a valid discussion to have about the default for images (crop vs visible) and how that interacts with width/height.

If the box grow it's not overflowing

It actually is overflowing the viewport. Page size, height, and width define the viewport, not the box itself. Pagination happens when the content box extends beyond the root fragmentainer established by that viewport.

Mhhhh since we allow sizing in CSS having both options is REALLY odd, if the document is set to A4 and then we try to convert it to demi-raisin because it's what the users put in their CLI it should stay A4 in my opinion (more flexible and compliant with CSS's spec), documents knows their sizes (except for non paginated documents where we should listen for the CLI)

That’s outside the scope of this PR. CSS always has the final say on page size. The CLI option just provides a base page size, see #90 and css-page-3.

[Louciole]

The Y-axis part isn’t accurate. Overflow can occur on both X and Y. Right now, pagination only applies vertically, but there are potential use cases for horizontal overflow, for example, SVG backgrounds or multi-column layouts in illustrated books with full-spread images.

meh they could be handled in CSS styling the root element or the pages, if the root element is overflow scroll we should grow to match
and the overflow pagination here can happen only on 1 axis (at a time)

--overflow felt like the least-worst name: technically accurate, broad enough to cover different cases, and already aligned with existing terminology. Since auto handles most use cases, I think a technical name works fine here. There’s still a valid discussion to have about the default for images (crop vs visible) and how that interacts with width/height.

I agree it's not too bad, I need to think a bit about other possibilities and if there's no better solution we could work with that, BUT the existing terminology is paged documents and continuous documents, there's no other concepts and thus no need for other terminology (crop and visible should be done using CSS). Since there's only two options and a magic keyword I think a boolean works the best here. (+ it's easier to remember for users)

It actually is overflowing the viewport. Page size, height, and width define the viewport, not the box itself. Pagination happens when the content box extends beyond the root fragmentainer established by that viewport.

yup but that viewport is a social construct in a paginated document, 100vw should always be the width of a page (https://drafts.csswg.org/css-values-4/#viewport-relative-lengths) the viewport size here is irrelevant and everything is based on the CSS declarations.
What the flag really mean is "Do we want to take the "@page" rules into account or not"

That’s outside the scope of this PR. CSS always has the final say on page size. The CLI option just provides a base page size, see #90 and css-page-3.

Granted

[sleepy-monax]

@Louciole

I agree it's not too bad, I need to think a bit about other possibilities and if there's no better solution we could work with that, BUT the existing terminology is paged documents and continuous documents, there's no other concepts and thus no need for other terminology (crop and visible should be done using CSS). Since there's only two options and a magic keyword I think a boolean works the best here. (+ it's easier to remember for users)

Ok then let's not block the PR over bikesheeding. If one of us has a better name then we can have another PR

[Louciole]

I prefer not to change the CLI every other day, if we can agree on a good interface, then it will last. Since we don't NEED it to be merged right now we can wait till Monday