Allow spool limits for pdf prints

[akberenz]

Reference

Before	After
qz.configs.create('Zebra', { perSpool: 10 }	qz.configs.create('Zebra', { spool: { size: 10 } } )

Raw only

Before	After
qz.configs.create('Zebra', { endOfDoc: '^XZ' }	qz.configs.create('Zebra', { spool: { end: '^XZ' } } )

Compatibility:

• 2.1.3 and higher only. QZ Tray will continue to honor the old, deprecated API for raw only.
• qz-tray.js will automatically convert the new API to the old format if an older QZ Tray version is detected.

---

perSpool option added for pdf pixel prints, closes #727

[tresf]

@bberenz I believe we need to add some form of backwards compatibility routine or else QZ Tray 2.1.3+ will take the old perSpool: 1 from older qz-tray.js versions, and run with it, resulting in e.g. 1,000 separately spooled documents for instances like the original bug report.

Perhaps a sane way to provide this is to check for endOfDoc on the pixel side, since it was previously ONLY required for raw, ignored otherwise. Then, if endOfDoc is there, assume perSpool wasn't really intended over on the pixel-side.

Edit: No, I think that logic is flawed. Hmm... Ideas welcome. Maybe we need to start sending the qz-tray.js version? Or wrap the perSpool into a new object for 2.1, e.g. { spool: { per: 1, start:|end: 'P1\n' } }, then write a compat() for 2.0?

[akberenz]

Should we just put the pixel option under a different property?
Something like "splitSpool:<int>"?

[tresf]

Should we just put the pixel option under a different property?

I quite prefer keeping raw and pixel using similar APIs. I was trying to find an API indicator suggesting that 1 was a relic safe to ignore, but I couldn't find one.

My proposal to yours is similar but uses an object. I'm not sure if this is overkill, but would make home to more spool control parameters in the future. For example, if we find a way to control winspool's behavior such as "keep spooled documents", or "send directly to the printer", etc although these may be better suited in a non-print(...) API since they're sweeping. Other future possibilities include page-handling, such as sending page 7 to a different tray. These types of advanced printing capabilities are missing from the PDF spec and may have value, thus a place in the API namespace. Thoughts welcome.

[akberenz]

That'd probably be the way to go besides just blanket ignoring a value of 1 for pixel spools then.
I'd probably go with something besides config.spool.per, maybe spool.sendPer or spool.size?

[tresf]

Implemented object notation via 4f1b58b (untested). Feedback welcome.

[tresf]

✅ PASS: QZ Tray 2.1.3-RC1
✅ PASS: QZ Tray 2.1.2
✅ PASS: Using deprecated syntax { perSpool: 1, endOfDoc: '^XZ' }

[tresf]

Documentation updated: https://qz.io/wiki/2.1-Pixel-Printing#advanced-print-spooling. Raw documentation still uses the old syntax for now, but I've added a note about the new syntax. https://github.com/qzind/tray/wiki/2.1-Raw-Printing#advanced-print-spooling