Add support for inline images

[mojavelinux]

Add support for the inline image macro. This requires adding a convenience method for placing an image in the flow of text. It would be nice to have direct support for this in Prawn, though we can get away with using a method in Asciidoctor PDF until it becomes available upstream.

[getreu]

+1 Jens

[mikeosbornma]

+1

[madmas]

+1

[mojavelinux]

I'll reiterate that it would be nice to have direct support in Prawn, though I'm open to doing what we have to do in Asciidoctor PDF to support it before then.

Btw, I did do some experimentation with wrapping text around image in Asciidoctor PDF so you can get an idea of the type of logic we need to do.

https://github.com/opendevise/editions/blob/master/lib/editions/pdf_extensions.rb#L88

Another approach is to take the approach the DocBook toolchain takes, which is to assume that inline images should be centered on the line vertically and thus we only have to worry about reserving blank space for them horizontally.

This is definitely something we take for granted when using HTML :)

[mojavelinux]

I'd say going into the 1.5.0 release, we should have some basic support in some form...even if it's rough. We can then enhance from there.

[plaindocs]

+1

[mojavelinux]

To help move this along, I was thinking that part of the challenge here is a design issue. An inline image means that text needs to be wrapped around it...that is, if it's a larger image. If we can assume that inline images fit within a line (like the DocBook toolchain assumes), then we could easily implement this by leaving enough horizontal space for the image and coming back to insert it. Would that fit some of the requirements up front, or is support for wrapping text around the image critical? Maybe we could handle this as two separate issues.

[getreu]

I think at this stage reproducing the behaviour of the Docbook toolchain as best as possbile is a good idea. We still need the docbook toolchain for production environments but asciidoctor-pdf gives already good results in many usecases. We should make sure they produce the same. (BTW. I recently discoverd small difference in treating callouts. I will file a bug report as soon I have some time).

[mojavelinux]

at this stage reproducing the behaviour of the Docbook toolchain as best as possbile is a good idea.

👍

[thomseno]

+1

[mojavelinux]

I've got a prototype of this working. The code is very ugly at the moment, but the result is already looking quite nice. Here's a preview.

As you can see, the idea is to give enough room for the width of the image and allow the height to grow outwards (up and down) from the center of the line. This allows us to accommodate images without squishing them vertically. However, if they grow too tall, they will overlap the text on the line above and below. But you can just adjust the width of the image until it fits :)

[mojavelinux]

The way I have to implement this is quite strange, but perhaps a good opportunity for an API improvement in Prawn. I have to calculate the width of the image (or the explicit width) and insert the appropriate number of non-breaking spaces in the text to make room for the image. Then, I intercept the printing of the spaces and put the image there instead.

What I'd like to be able to do is tell Prawn to reserve a certain amount of width of a fragment and just skip writing anything. Seems reasonable enough. But this hack will work for our purposes now.

[mojavelinux]

Support for inline images is now in master, and I think it goes beyond what even DocBook supports. We're more on par with HTML, though vertical alignment is still primitive (as described in the pull request). Feel free to test!

[mojavelinux]

Missing files restored. Now you should be able to test ;)