Some implementation notes:
* cups-pdf, and cups-pdf-to-pdf,
support multiple instances with differing configurations.
This can be accomplished by creating multiple configuration
files with names `cups-pdf-{instance-name}.conf`.
The Nixos module supports this feature by providing
the option `instances` which is an attrset
mapping instance names to instance configurations.
To simplify module usage,
an instance `pdf` is created by default.
* To use a cups-pdf instance, one also needs
a cups queue that connects to the backend.
The module does this automatically by default,
using the `hardware.printers.ensurePrinters`.
It uses one of the ppd files which is
included in the cups-pdf package.
If this isn't desired (e.g. because printer queues
should be created by hand, or configured differently),
the `installPrinter` option can be turned off
(for each instance separately).
* In our configuration, cups calls external programs
using the `cups` account and the `lp` group.
cups-pdf refuses to operate without root privileges,
likely because it needs to change the
ownership of it output pdf files so that
(only) the print job's owner can access them.
The module installs a suid root wrapper for the backend
program that can only be called by the `lp` group.
The cups-pdf package is replaced by a wrapper
package which calls the suid root wrapper.
So cups can call its backend programs as usual.
Unlike the XML doc renderer, the AsciiDoc and CommonMark renderers don't
pretty-print certain complex types, like literal expressions, DocBook
literals, and derivations. These types are dumped into the documentation
as JSON.
This commit parses and unwraps these types when loading the
JSON-formatted NixOS options. The AsciiDoc and CommonMark renders have
also been combined into a single script to allow code reuse.
Its scripts disagree a bit with our flexible
logging approach and our default logging config.
Might want to revisit this at some point.
The `mkdir` failures in the log are harmless.
