New PageList processing, supporting PDF and XPS random order.

Supports out-of-order ranges (if the parser allows it and disables the
PageHandler, i.e., flp device). Also adds support for ranges appended
to the "even" and "odd" keyword following a ":".

As before a trailing "-" in a range implies the last page, and as was
supported by the previous 'gxps' code, a leading "-" also is the last page.

For example, with XPS or PDF: -sPageList=odd:3-7,even:4-8,1-,-1,9
prints pages: 3, 5, 7, 4, 6, 8, 1, 2, ..., last, last, last-1, ..., 1, 9

The PageList string is parsed using C code into an array that consists of
an initial int that is > 0 if the list is ordered, followed by sets of
3 integers per range, even/odd flag (odd=1, even=2), start, end. The
final 3 ints are 0,0,0 as a marker.

The initial int is used by 'pagelist_test_printed' as an index to the next
range to be processed when the PageList is used for languages that can only
be processed sequentially (e.g. PS and PCL) and is updated when the page
passes the end of the current range.  A value of -1 means the ranges are
not ordered (not strctly increasing).

The flp_fillpage is changed to ignore errors from processing the PageList
performed by ParsePageList (called from SkipPage) when PageCount is 0
so that parsers that support out of order processing (PDF and XPS) can
continue until later. This should have little or no performance impact
since it is limited to PageCount == 0.

Note that the new PDF parser also uses the C code parser and then uses
the array of ranges returned by ".PDFparsePageList". The old PostScript
based parser has not been updated, although it is easy to do so.

2 files changed, 36 insertions, 31 deletions

diff --git a/doc/Language.htm b/doc/Language.htm
index 44c569d96..25aa67ef6 100644
--- a/doc/Language.htm
+++ b/doc/Language.htm
@@ -2096,10 +2096,11 @@ It has no effect in the new PDF interpreter but is maintained for backwards comp
      media and render the page.</dd>
      <dt><code>&ltint&gt &ltint&gt dopdfpages -</code></dt>
 <dd>     The integers are the first and last pages to be run from the file. Runs a loop from
-     the fist integer to the last. NOTE! If the current dictionary contains a PDFPageList
-     array then we 'get' the entry from the array corresponding to the current loop
-     index, and use that to determine whether we should draw the page. Otherwise we
-     simply draw the page. Uses pdfshowpage to actually render the page.</dd>
+     the fist integer to the last.
+     <p>NOTE! If the current dictionary contains a PDFPageList array the two values on the stack
+     are ignored and we use the range triples from that array (even/odd, start, end) to determine
+     the pages to process. Page numbers for start and end are 1..lastpage and even/odd is 1
+     for odd, 2 for even, otherwise 0. Uses pdfshowpage to actually render the page.</dd>
      <dt><code>- runpdfpagerange &ltint&gt &ltint&gt</code></dt>
 <dd>     Processes the PostScript /FirstPage, /LastPage and /PageList parameters. These are used together to build an internal array
      of page numbers to run, which is used by dopdfpages to actually process the pages if PageList is present,
diff --git a/doc/Use.htm b/doc/Use.htm
index 33e4f679b..86668c1c4 100644
--- a/doc/Use.htm
+++ b/doc/Use.htm
@@ -786,32 +786,47 @@ be drawn, whilst those not listed will not be drawn.</p>
     <dd>Stop after the designated page of the document.
     Pages of all documents in PDF collections are numbered sequentionally.</dd>
 </dl>
+<p>
+</pre></blockquote>
+NOTE: The PDF and XPS interpreters allow the use of a -dLastPage less than -dFirstPage.  In this
+case the pages will be processed backwards from LastPage to FirstPage.
+</p>
 
 <dl>
-    <dt><code>-sPageList=</code><em>pagenumber</em></dt>
+    <dt><code>-sPageList=</code><em>pageranges</em></dt>
 
-<dd>There are three possible values for this; even, odd or a list of pages to be processed.
-A list can include single pages or ranges of pages.
-Ranges of pages use the minus sign '-', individual pages and ranges of pages are separated
-by commas ','. A trailing minus '-' means process all remaining pages. For example;
+<dd>Page ranges are separated by a comma ','. Each range of pages can consist of:
+<p><blockquote><pre>
+(a) a single page number.
+(b) a range with a starting page number, followed by a dash '-' followed by an ending page number.
+(c) a range with a starting page number, followed by a dash '-' which ends at the last page.
+(d) the keyword "even" or "odd", which optionally can be followed by a colon ':' and a page range.
+    If there is no page range then all even or odd pages are processed in forward order.
+(e) a range with an initial dash '-' followed by and ending page number which starts at the
+    last page and ends at the specified page <i>(PDF and XPS only)</i>.
+</pre></blockquote>
+For example:
 <p><blockquote><pre>
 -sPageList=1,3,5 indicates that pages 1, 3 and 5 should be processed.
 -sPageList=5-10 indicates that pages 5, 6, 7, 8, 9 and 10 should be processed.
 -sPageList=1,5-10,12- indicates that pages 1, 5, 6, 7, 8, 9, 10 and 12 onwards should be processed.
+-sPageList=odd:3-7,9-,-1,8 processes pages 3, 5, 7, 9, 10, 11, ..., last, last, last-1, ..., 1, 8
 </pre></blockquote>
-Note: Use of PageList overrides FirstPage and/or LastPage, if you set these as well as PageList they will be ignored. The
- list of pages should be given in increasing order, you cannot process pages out of order and inserting higher numbered pages before lower numbered
- pages in the list will generate an error.
+Note: Use of PageList overrides FirstPage and/or LastPage, if you set these as well as PageList they will be ignored.
 </p>
-
-<p>The PDF interpreter and the other language interpreters handle these in slightly different ways. Because
-PDF files enable random access to pages in the document the PDF inerpreter only interprets and renders
-the required pages. PCL and PostScript cannot be handled in ths way, and so all the pages must be interpreted.
-However only the requested pages are rendered, which can still lead to savings in time. Be aware that
-using the '%d' syntax for OutputFile does not reflect the page number in the original document. If you
-chose (for example) to process even pages by using <code>-sPageList=even</code>, then the output of
+<p>
+Be aware that using the <code>%d</code> syntax for <code>-sOutputFile=...</code> does not reflect the page number in the original document.
+If you chose (for example) to process even pages by using <code>-sPageList=even</code>, then the output of
 <code>-sOutputFile=out%d.png</code> would still be
-out0.png, out1.png, out2.png etc......
+out1.png, out2.png, out3.png etc......
+</p>
+<p>
+For PostScript or PCL input files, the list of pages must be given in increasing order, you cannot process pages out of order or
+repeat pages and this will generate an error. PCL and PostScript require that all the pages must be interpreted,
+however since only the requested pages are rendered, this can still lead to savings in time.
+</p>
+<p>The PDF and XPS interpreters handle this in a slightly different way. Because these file types provide for random access to
+individual pages in the document these inerpreters only need to process the required pages, and can do so in any order.
 </p>
 <p>
 Because the PostScript and PCL interpreters cannot determine when a document terminates, sending multple
@@ -824,17 +839,6 @@ is applied to each PDF file separately. So if you were to set <code>-sPageList=1
  exercise caution when using this switch, and probably should not use it at all when processing a mixture of PostScript
  and PDF files on the same command line.
 </p>
-<p>
-The XPS language like the PDF language allows random access to pages.  The XPS interpreter handles all the PageList cases
-discussed above.  It also handles cases such as:
-<blockquote><pre>
--sPageList=1,2,1,2 indicates repeated pages.  Pages processed in order 1, 2, 1, 2.
--sPageList=10-5 indicates pages will be processed in the order 10, 9, 8, 7, 6, 5.
--sPageList=1-,-1 indicates first processing from page 1 to end and then from end to page 1.
-</pre></blockquote>
-In addition, the XPS interpreter allows the use of a -dLastPage < -dFirstPage.  In this
-case the pages will be processed backwards from LastPage to FirstPage.
-</p>
 
 </dd>
 </dl>