From a1994a53438612405c1d00d7bd9b3ef78ae477ef Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Thu, 15 Oct 2020 14:52:14 -0400 Subject: [PATCH] Fix/clarify documentation on --rotate option (fixes #470) Make clear that you almost always want + or - before an angle when specifying rotation. --- TODO | 1 - manual/qpdf-manual.xml | 10 ++++++---- qpdf/qpdf.cc | 4 +++- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/TODO b/TODO index d194310e..ea81a716 100644 --- a/TODO +++ b/TODO @@ -2,7 +2,6 @@ Candidates for upcoming release =============================== * Trivial fixes: - * #470: odd/even -- doc bug * #468: doc typo * Remove travisci * Update manual to clearly state qpdf's exit codes including mention diff --git a/manual/qpdf-manual.xml b/manual/qpdf-manual.xml index 48262e70..74f0279a 100644 --- a/manual/qpdf-manual.xml +++ b/manual/qpdf-manual.xml @@ -936,14 +936,16 @@ make portion of the parameter may be either 90, 180, or 270. If preceded by or , the angle is added to or subtracted from - the specified pages' original rotations. Otherwise the pages' - rotations are set to the exact value. For example, the command - qpdf in.pdf out.pdf --rotate=+90:2,4,6 + the specified pages' original rotations. This is almost always + what you want. Otherwise the pages' rotations are set to the + exact value, which may cause the appearances of the pages to + be inconsistent, especially for scans. For example, the + command qpdf in.pdf out.pdf --rotate=+90:2,4,6 --rotate=180:7-8 would rotate pages 2, 4, and 6 90 degrees clockwise from their original rotation and force the rotation of pages 7 through 9 to 180 degrees regardless of their original rotation, and the command qpdf in.pdf - out.pdf --rotate=180 would rotate all pages by 180 + out.pdf --rotate=+180 would rotate all pages by 180 degrees. diff --git a/qpdf/qpdf.cc b/qpdf/qpdf.cc index b685d2e5..4e697660 100644 --- a/qpdf/qpdf.cc +++ b/qpdf/qpdf.cc @@ -1276,7 +1276,9 @@ ArgParser::argHelp() << "format as with the --pages option, described below. Repeat the option\n" << "to rotate multiple groups of pages. If the angle is preceded by + or -,\n" << "it is added to or subtracted from the original rotation. Otherwise, the\n" - << "rotation angle is set explicitly to the given value.\n" + << "rotation angle is set explicitly to the given value. You almost always\n" + << "want to use + or - unless you are certain about the internals of the PDF\n" + << "you are working with.\n" << "\n" << "If --split-pages is specified, each page is written to a separate output\n" << "file. File names are generated as follows:\n"