DOC: add documentation about how to use negative page ranges in cat/rm/rotate (#168)

Author: moormaster

docs/user/subcommand-cat.md

@@ -16,6 +16,9 @@ pdfly cat --help
  range means all the pages of the file.
  PAGE RANGES are like Python slices.
  Remember, page indices start with zero.
+ When using page ranges that start with a negative value a
+ two-hyphen symbol -- must be used to separate them from
+ the command line options.
  Page range expression examples:
 
     :     all pages.
@@ -39,7 +42,7 @@ pdfly cat --help
 
 
  Examples
-      pdfly cat -o output.pdf head.pdf content.pdf :6 7: tail.pdf -1
+    pdfly cat -o output.pdf head.pdf -- content.pdf :6 7: tail.pdf -1
         Concatenate all of head.pdf, all but page seven of content.pdf,
         and the last page of tail.pdf, producing output.pdf.
 

docs/user/subcommand-rm.md

@@ -10,13 +10,17 @@ Usage: pdfly rm [OPTIONS] FILENAME FN_PGRGS...
 
  Remove pages from PDF files.
 
- Page ranges refer to the previously-named file.                                                           
+ Page ranges refer to the previously-named file.
  A file not followed by a page range means all the pages of the file.
 
  PAGE RANGES are like Python slices.
-                                                                                                           
+
          Remember, page indices start with zero.
 
+         When using page ranges that start with a negative value a
+         two-hyphen symbol -- must be used to separate them from
+         the command line options.
+
          Page range expression examples:
 
              :     all pages.                   -1    last page.
@@ -44,7 +48,7 @@ Usage: pdfly rm [OPTIONS] FILENAME FN_PGRGS...
 
          Remove all pages except page seven from report.pdf,
          producing a single-page report.pdf.
-                                                                                                           
+
 ╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────╮
 │ *    filename      FILE         [default: None] [required]                                              │
 │ *    fn_pgrgs      FN_PGRGS...  filenames and/or page ranges [default: None] [required]                 │
@@ -68,6 +72,6 @@ pdfly rm document.pdf 4
 Remove the first and last page of `document.pdf`, producing `output.pdf`.
 
 ```
-pdfly rm -o output.pdf document.pdf 1:-1 
+pdfly rm -o output.pdf document.pdf 1:-1
 
-```
+```

docs/user/subcommand-rotate.md

@@ -13,12 +13,22 @@ pdfly rotate --help
      pdfly rotate --output output.pdf input.pdf 90
          Rotate all pages by 90 degrees (clockwise)
 
+     pdfly rotate --output output.pdf input.pdf 90 :3
+         Rotate first three pages by 90 degrees (clockwise)
+
+     pdfly rotate --output output.pdf input.pdf 90 -- -1
+         Rotate last page by 90 degrees (clockwise)
+
  A file not followed by a page range (PGRGS) means all the pages of the file.
 
  PAGE RANGES are like Python slices.
 
          Remember, page indices start with zero.
 
+         When using page ranges that start with a negative value a
+         two-hyphen symbol -- must be used to separate them from
+         the command line options.
+
          Page range expression examples:
 
              :     all pages.                   -1    last page.

pdfly/cat.py

@@ -8,6 +8,10 @@
 
         Remember, page indices start with zero.
 
+        When using page ranges that start with a negative value a
+        two-hyphen symbol -- must be used to separate them from
+        the command line options.
+
         Page range expression examples:
 
             :     all pages.                   -1    last page.
@@ -23,7 +27,7 @@
             ::-1      all pages in reverse order.
 
 Examples
-    pdfly cat -o output.pdf head.pdf content.pdf :6 7: tail.pdf -1
+    pdfly cat -o output.pdf head.pdf -- content.pdf :6 7: tail.pdf -1
 
         Concatenate all of head.pdf, all but page seven of content.pdf,
         and the last page of tail.pdf, producing output.pdf.

pdfly/rm.py

@@ -8,6 +8,10 @@
 
         Remember, page indices start with zero.
 
+        When using page ranges that start with a negative value a
+        two-hyphen symbol -- must be used to separate them from
+        the command line options.
+
         Page range expression examples:
 
             :     all pages.                   -1    last page.
@@ -27,6 +31,10 @@
 
         Remove pages 2 to 4 from document.pdf, producing output.pdf.
 
+    pdfly rm document.pdf -- -1
+
+        Removes the last page from document.pdf, modifying the original file.
+
     pdfly rm document.pdf :-1
 
         Removes all pages except the last one from document.pdf, modifying the original file.

pdfly/rotate.py

@@ -5,12 +5,22 @@
     pdfly rotate --output output.pdf input.pdf 90
         Rotate all pages by 90 degrees (clockwise)
 
+    pdfly rotate --output output.pdf input.pdf 90 :3
+        Rotate first three pages by 90 degrees (clockwise)
+
+    pdfly rotate --output output.pdf input.pdf 90 -- -1
+        Rotate last page by 90 degrees (clockwise)
+
 A file not followed by a page range (PGRGS) means all the pages of the file.
 
 PAGE RANGES are like Python slices.
 
         Remember, page indices start with zero.
 
+        When using page ranges that start with a negative value a
+        two-hyphen symbol -- must be used to separate them from
+        the command line options.
+
         Page range expression examples:
 
             :     all pages.                   -1    last page.