One figure containing multiple images.

[jmini]

It would be nice to be able to support multiple images (png) using the same figure (only one caption and one anchor).

Proposed syntax by @mojavelinux:

.Three stages
image::screenshot1.png,screenshot2.png,screenshot3.png[]

If we think about this semantically, it's important to have the images as part of the same macro definition so it's clear they belong together.

The current workaround today is to fake it by using 3 block images and only putting the title on the last one:

image::screenshot1.png[]

image::screenshot2.png[]

.Three stages
image::screenshot3.png[]

Related discussion on the mailing list: One figure containing multiple images.

[rockyallen]

A possible problem with the proposed syntax is that you then have nowhere to specify macro attributes (ie for image sizes) individually. Since + means "continue the previous block" for paragraphs, would it be natural to extend it to images?

[[screenshots]]
[arrange="grid"]
.Three stages
image::screenshot1.png[]
+
image::screenshot2.png[width="20mm"]
+
image::screenshot3.png[]

This syntax could possibly be extended further to include a legend (http://discuss.asciidoctor.org/Docbook-figures-with-notes-or-legend-td2567.html)

[mojavelinux]

Good point @rockyallen. Actually, what makes even more sense is to allow the open block to be repurposed to hold an image group that would otherwise behave like an image block (get a caption like an image).

[[screenshots]]
[image-seq]
.Three stages
--
image::screenshot1.png[]
image::screenshot2.png[width=20mm]
image::screenshot3.png[]
--

I'm open to other names aside from image-seq. The layout could then be controlled using roles...or perhaps an explicit "arrange" attribute as you have suggested.

[rockyallen]

The open block + role looks good. How would it specify these use cases?

• Steps in a printed instruction manual that must be presented in a specific order
• Embedded slide show (HTML)
• Embedded gallery of thumbnails (HTML)
• "Views" of the same object with no natural order or relation, that can be rearranged to maximise visibility depending on the display size
• Arrangements of sub images in a specific geometric relation, not necessarily orthogonal (eg main image and views on arbitrary directions)
• Individual image sizing
• Overall image sizing

Some possible alternatives (in addition to, or instead of):

• Tables Put the images in a table, and switch the borders off. The only change needed in Asciidoctor would be to the ability to override the label and sequence number, so that it comes out as "Figure 3" instead of "Table 6", and gets added to the list of figures instead of the list of tables. Maybe an option [label="figure"]. Or would this just be confusing?
• SVG I think you can group images in arbitrary ways using embedded SVG. This probably works already, but I haven't tried it.

[mojavelinux]

How would it specify these use cases?

Mostly I think they are outside the scope of the default converter and should be handled using custom templates, extensions or a custom converter. We want to spend time on the wide-spread use cases and allow the framework / processor to be molded to fit specific requirements of certain projects / shops. Of course, we're always aiming to strike that ideal balance.

Maybe an option [label="figure"].

You might be happy to know this is already possible (though a bit verbose).

[caption='Figure {counter:figure-number}. ', frame=none, grid=none]
.Screenshots
|===
|image:screenshot-1.png[]
|image.screenshot-2.png[]
|image.screenshot-3.png[]
|===

The only problem is that the caption appears at the top instead of the bottom (since that's where it goes for tables). Also, the CSS is adding alternating background colors to the rows...but you can fix that with a little docinfo CSS.

I think you can group images in arbitrary ways using embedded SVG

This is actually a serious solution that should always be considered. It came up in another discussion about slide design when using AsciiDoc. For arbitrary layouts with unique requirements, it makes sense to leverage the design capabilities of SVG and simply embed it. It's a trade-off, but a reasonable one under the right circumstances.

[mojavelinux]

Steps in a printed instruction manual that must be presented in a specific order

I think an ordered list should be sufficient for this use case. It's true you may lose some expressiveness from DocBook's procedure element, but to the human reading it I really question whether those extra semantics are worth it. As for how it appears, that's something that custom CSS and HTML afford you.

[hsablonniere]

What's the status on this? I would definitely need this for a blog post.

[mojavelinux]

Not yet implemented in core, but I've been experimenting with the design in the Bespoke.js converter. I think a comma-separated list of paths in the target (i.e., image::one.jpg,two.jpg,three.jpg[]) is the way to go when the images are individual frames in the same sequence. (It's possible to implement this idea using a Treeprocessor).

That design may not work well when the images are discrete (different dimensions and alt text). In that case, it probably makes more sense to have discrete image macros that are grouped inside an open block. It's probably important to recognize that we have more than one use case here.

[pinggit]

just a heads up... is this resolved yet? what's the solution for this today? I tested this and it still does not work

.rebase
--
image::https://cloud.githubusercontent.com/assets/2038044/22177700/76b3a3a0-dff1-11e6-966d-abba4535f5f4.png[]
image::https://cloud.githubusercontent.com/assets/2038044/22177702/80bbdb4c-dff1-11e6-8214-b4c0ca10ce7d.png[]
--

this workaround works though:

image::https://cloud.githubusercontent.com/assets/2038044/22177700/76b3a3a0-dff1-11e6-966d-abba4535f5f4.png[]

.rebase
image::https://cloud.githubusercontent.com/assets/2038044/22177702/80bbdb4c-dff1-11e6-8214-b4c0ca10ce7d.png[]

[bmarwell]

Something like this is needed for next-gen image formats: https://github.com/asciidoctor/asciidoctor/issues/4273

[kharann]

How would it specify these use cases?

Mostly I think they are outside the scope of the default converter and should be handled using custom templates, extensions or a custom converter. We want to spend time on the wide-spread use cases and allow the framework / processor to be molded to fit specific requirements of certain projects / shops. Of course, we're always aiming to strike that ideal balance.

Maybe an option [label="figure"].

You might be happy to know this is already possible (though a bit verbose).

[caption='Figure {counter:figure-number}. ', frame=none, grid=none]
.Screenshots
|===
|image:screenshot-1.png[]
|image.screenshot-2.png[]
|image.screenshot-3.png[]
|===

The only problem is that the caption appears at the top instead of the bottom (since that's where it goes for tables). Also, the CSS is adding alternating background colors to the rows...but you can fix that with a little docinfo CSS.

I think you can group images in arbitrary ways using embedded SVG

This is actually a serious solution that should always be considered. It came up in another discussion about slide design when using AsciiDoc. For arbitrary layouts with unique requirements, it makes sense to leverage the design capabilities of SVG and simply embed it. It's a trade-off, but a reasonable one under the right circumstances.

Is it possible now to put the caption of the table at the bottom? I'm using this for a side-by-side image, but since it's a table the caption is at the bottom. I was curious if I could do this with a Role perhaps, or what to change to accomplish this.

[wmat]

Could you do it in the theme?

table: caption: end: bottom

On Mon, May 8, 2023 at 8:55 AM Anhkha Vo @.***> wrote:

How would it specify these use cases?

Mostly I think they are outside the scope of the default converter and should be handled using custom templates, extensions or a custom converter. We want to spend time on the wide-spread use cases and allow the framework / processor to be molded to fit specific requirements of certain projects / shops. Of course, we're always aiming to strike that ideal balance.

Maybe an option [label="figure"].

You might be happy to know this is already possible (though a bit verbose).

[caption='Figure {counter:figure-number}. ', frame=none, grid=none] .Screenshots |=== |image:screenshot-1.png[] |image.screenshot-2.png[] |image.screenshot-3.png[] |===

The only problem is that the caption appears at the top instead of the bottom (since that's where it goes for tables). Also, the CSS is adding alternating background colors to the rows...but you can fix that with a little docinfo CSS.

I think you can group images in arbitrary ways using embedded SVG

This is actually a serious solution that should always be considered. It came up in another discussion about slide design when using AsciiDoc. For arbitrary layouts with unique requirements, it makes sense to leverage the design capabilities of SVG and simply embed it. It's a trade-off, but a reasonable one under the right circumstances.

Is it possible now to put the caption of the table at the bottom? I'm using this for a side-by-side image, but since it's a table the caption is at the bottom. I was curious if I could do this with a Role perhaps, or what to change to accomplish this.

— Reply to this email directly, view it on GitHub https://github.com/asciidoctor/asciidoctor/issues/1287#issuecomment-1538310986, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAN6ZGR6X5FEG2DEQ4DOVTXFDUKHANCNFSM4A4TJ5RA . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[kharann]

Could you do it in the theme? table: caption: end: bottom

This would change the caption of ALL tables, wouldn't it? I would like to do it only at the tables which I use for Side-by-side images. I was curious if I could add a CSS class or something for it