Allow a watermark image to be specified

[mojavelinux]

A watermark image goes above the text, whereas a background image goes below the text. We could either introduce a dedicated setting for specifying a watermark, or we could add an option to the background image. However, since there's a chance the design will call for both, the separate option is probably the right approach.

[mojavelinux]

The tricky part is that Prawn does not provide a hook when leaving a page. But we can simply iterate all the pages at the end and apply the watermark as a stamp.

The proposed name for the property is page-foreground-image. (I'm also open to page-watermark-image).

The image will be applied on every page except for imported pages, which includes the title page. The reason we don't touch imported pages is that it can cause the PDF to become corrupt.

[mojavelinux]

Before we merge, which attribute do we like better?

• page-foreground-image
• page-watermark-image

I'm leaning towards the first since it's a) parallel with "background" and b) might not always be a watermark.

[mojavelinux]

Watermark is pretty poorly defined (and its meaning been distorted). So I think we should stick with page-foreground-image.

[BrianEmberling]

page-foreground-image and :page-foreground-image: seem to work for me, but I cannot get [opacity=50%] to work with either form (using .png or .svg image). The final .pdf always renders the watermark with 100% opacity blocking all text behind it. Any hint how to get this to work?

[mojavelinux]

Asciidoctor PDF doesn't apply opacity to the image. The opacity has to be in the image itself.