expand to document dimensions and marks, and provide resize method using CropMark

1 files changed, 97 insertions, 4 deletions

diff --git a/USE.md b/USE.md
index d65fbeb..f03aa3c 100644
--- a/USE.md
+++ b/USE.md
@@ -17,7 +17,76 @@ or look at underlying scripts `pdftops`and `pstopdf13`.
 	pdftops %f
 	ps2pdf13 infile outfile
 
-## Resize PDF with crop marks
+## PDF resizing and/or scaling
+
+PDF **resizing** is changing *media* size,
+either together with or independent of content.
+
+PDF **scaling** (a.k.a. "zooming") is changing *content* size,
+relative to size of media size.
+
+Both resizing and scaling at once can be confusing.
+A suggested approach is to first media+content together,
+then scale content relative to this new target media size.
+
+### PDF dimensions
+
+Resizing and/or scaling PDF files
+is tied to input and output dimensions.
+Simple measures are standard page formats like A4, A3, or letter,
+but more reliable are internal "box" dimensions measured in "pt":
+
+In addition to page sizes,
+PDF files technically annotate content using several "boxes":
+
+  * MediaBox: full printable area
+    * Required
+  * CropBox: area displayed in a PDF viewer
+    * Optional, defaults to MediaBox
+  * BleedBox: area including TrimBox/ArtBox and bleed
+    * Optional, defaults to MediaBox
+    * Must be larger than TrimBox/ArtBox, and smaller than MediaBox
+  * TrimBox: subset of printable area without bleed, cropmarks etc.
+    * Optional
+  * ArtBox: essential subset of printable area
+    * Optional
+
+(Technically a "BoundingBox" is not a PDF hint
+but the equivalent of ArtBox in EPS and DSC-compliant Postscript.)
+
+E.g. an A4 sized PDF page
+is technically a page with a /MediaBox of approx. [595 x 842 pt][page_dimensions].
+
+### Extracting PDF box hints
+
+Resolve all boxes (computing from defaults any omitted ones):
+
+	pdfinfo -box -l -1 input.pdf
+
+Extract MediaBox:
+
+	gs -dQUIET -dNODISPLAY -dNOSAFER -sFileName=input.pdf \
+	-c "FileName (r) file runpdfbegin 1 1 pdfpagecount {pdfgetpage /MediaBox get {=print ( ) print} forall (\n) print} for quit"
+
+To check if other boxes exist,
+replace `/MediaBox` with e.g. `/CropBox` in above command,
+and test if running the command succeeds.
+
+### Computing PDF dimensions
+
+Ghostscript can virtually render each page and compute the area used,
+useful e.g. for cropping a PDF.
+
+Compute BoundingBox for each page individually (*not* across them all):
+
+	gs -q -dBATCH -dNOPAUSE -sDEVICE=bbox -dLastPage=1 input.pdf 2>&1 | grep %%BoundingBox
+
+Source: <https://stackoverflow.com/a/52644056>
+
+[page_dimensions]: <https://ghostscript.readthedocs.io/en/latest/Use.html#appendix-paper-sizes-known-to-ghostscript>
+  "Postscript page dimensions as defined in Ghostscript"
+
+### Resize PDF with crop marks
 
 Simple resizing to fit target paper size
 can often be done on-the-fly at the print dialog.
@@ -47,7 +116,7 @@ one of its features is easy scaling by area.
 
 	plakativ --factor=0.5 --size=250mmx337mm --output=output.pdf input.pdf
 
-### using Ghostscript
+### using Ghostscript with fitPage
 
 Ghostscript resizing is done by first defining target size
 and then tell to resize content to fit that target with `FitPage`.
@@ -59,7 +128,31 @@ and explicitly set those values scaled down by 21/29.7
 (the ratio between A3 and A4 page formats).
 
 Example command,
-for a PDF document with width 910.24 and height 1258.9
-(as reported by `pdfinfo`):
+resizing from A3+ to A4
+(source width 910.24 and height 1258.9 as reported by `pdfinfo`):
 
 	gs -o output.pdf -sDEVICE=pdfwrite -dDEVICEWIDTHPOINTS=643.60333 -dDEVICEHEIGHTPOINTS=890.131 -dFIXEDMEDIA -dFitPage -dCompatibilityLevel=1.4 input.pdf
+
+TODO: maybe options `-dDEVICEWIDTHPOINTS` and `-dDEVICEHEIGHTPOINTS` can be shortened as `-dDEVICEWIDTH` and `-dDEVICEHEIGHT`
+
+### using Ghostscript with setpagedevice
+
+Some PDF documents embeds `/CropBox` marks
+which is not handled by the `-dfitPage` option.
+For effectively resizing such documents,
+each page need to have applied a `/CropBox` mark matching the new size.
+
+Example command,
+resizing from A4 to printable-area-A4
+(i.e. a dumb printer always auto-resizing to fit):
+
+	gs -o output.pdf -sDEVICE=pdfwrite -dDEVICEWIDTHPOINTS=595 -dDEVICEHEIGHTPOINTS=842 -dFIXEDMEDIA -dCompatibilityLevel=1.4 \
+	-c "<</EndPage {0 eq {[/CropBox [0 0 567 802] /PAGE pdfmark true}{false}ifelse}>> setpagedevice" -f input.pdf
+
+TODO: maybe options `-dDEVICEWIDTHPOINTS` and `-dDEVICEHEIGHTPOINTS` are superfluous
+
+TODO: maybe options `-dDEVICEWIDTHPOINTS` and `-dDEVICEHEIGHTPOINTS` can be shortened as `-dDEVICEWIDTH` and `-dDEVICEHEIGHT`
+
+TODO: maybe works only with `CropMark` applied for whole PDF file (and when none are applied?) but fails when input file already contain per-page `CropMark` hints
+
+Source: <https://stackoverflow.com/a/26989410>