How to provide alternative figures for HTML (.gif) and PDF (.png) versions of a book?

[friendly]

Description

Using Quarto: 1.3.450

In a book project I have several animated .gif images for the HTML version, but I need to replace these with static .png images for the LaTeX / PDF version. Following https://quarto.org/docs/authoring/conditional.html I tried to use the following conditional blocks:

But wait! Where does that 4D thing (a _tesseract_) come from?
To really see a tesseract it helps to view it in an animation over time (@fig-tesseract).
But like the Square, contemplating 3D from a
2D world, it takes some imagination.

::: {#fig-tesseract .content-visible when-format="HTML"}
<div align="center">
<iframe width="256" height="256" src="images/tesseract.gif"></iframe>
</div>
Animation of a tesseract, a cube changing over time.
:::

::: {#fig-tesseract .content-visible when-format="PDF"}
![](../images/tesseract-frames.png)
Frames from an animation of a tesseract, a cube changing over time. This appears as a true animation in the online version.
:::

This worked for the HTML version before I added the .content-visible when-format="HTML"
This no longer works. In the HTML version, no image appears and the figure reference is unresolved

The same thing happens in the PDF version: No image, unresolved reference.

Is it that the figure label, #fig-tesseract causes .content-visible not to work?

More generally, I suspect I will run into other problems trying to allow for multiple formats for this book. Is there a more comprehensive guide for doing this?

[mcanouil]

You should separate conditional divs from cross-ref divs.

Also why are you using raw HTML to include GIF? It should work using the markdown syntax without having to do anything.

And if you really need raw HTML, put it in a raw code block: ```{=html}.

[friendly]

I'm only using raw HTML, because this is all I knew to include a GIF image. I agree that's ugly. What is the pure markdown equivalent of using

::: {#fig-tesseract .content-visible when-format="HTML"}
<div align="center">
<iframe width="256" height="256" src="images/tesseract.gif"></iframe>
</div>
Animation of a tesseract, a cube changing over time.
:::

[cscheid]

::: {.content-visible when-format="HTML"}

::: {#fig-tesseract}

```{=html}
<div align="center">
<iframe width="256" height="256" src="images/tesseract.gif"></iframe>
</div>
```

Animation of a tesseract, a cube changing over time.
:::

:::

[cscheid]

Is it that the figure label, #fig-tesseract causes .content-visible not to work?

Yes, I think that's what's happening. In this case, you need to move .content-visible to its own surrounding div. We try to make it so that div classes can be "flattened" like that, but I'm not sure that we can do that in the case of cross-referenceable elements.

I actually am surprised that this was working before. I would have suspected that the repeated fig-tesseract ids would confuse our system. I'm not quite sure how to get everything you need to work (because you have different captions in the two documents). Let me get back to you on this.

[cscheid]

I'm again surprised that the following works!

---
title: issue-8172
format:
  pdf: default
  html: default
---

But wait! Where does that 4D thing (a _tesseract_) come from?
To really see a tesseract it helps to view it in an animation over time (@fig-tesseract).
But like the Square, contemplating 3D from a
2D world, it takes some imagination.

::: {.content-visible when-format="html"}

::: {#fig-tesseract}

```{=html}
<div align="center">
<iframe width="256" height="256" src="https://placeholder.co/400"></iframe>
</div>
```

Animation of a tesseract, a cube changing over time.
:::

:::

::: {.content-visible when-format="pdf"}

![Frames from an animation of a tesseract, a cube changing over time. This appears as a true animation in the online version.
](https://placeholder.co/400){#fig-tesseract}

:::

EDIT: Ok, the reason this works is that there's no requirement that FloatRefTargets elements be unique in the document right until the crossref filter happens. So if there are multiple FloatRefTargets with repeated identifiers, but they eventually become unique (like the conditional content filter will do), then there's no problem.

It's almost like we designed it carefully! 😆

[friendly]

Thanks so much for this!
I really appreciate the assistance of the Quarto team.

[mcanouil]

The syntax for images as GIF is an image.
There is no reason to go with RAW HTML.

---
title: issue-8172
format:
  html: default
  pdf: default
---

But wait! Where does that 4D thing (a _tesseract_) come from?
To really see a tesseract it helps to view it in an animation over time (@fig-tesseract).
But like the Square, contemplating 3D from a
2D world, it takes some imagination.

::: {.content-visible when-format="html"}

![Animation of a tesseract, a cube changing over time.](https://media1.tenor.com/images/2ed919ce9aa9018d8d19f474cbb90847/tenor.gif){#fig-tesseract}

:::

::: {.content-visible when-format="pdf"}

![Frames from an animation of a tesseract, a cube changing over time. This appears as a true animation in the online version.
](https://placeholder.co/400){#fig-tesseract}

:::

Screen.Recording.2024-01-08.at.19.46.00.mov

[mcanouil]

I don't understand? There is nothing specific to Books.
It's multiple format rendering with conditional content which is described (using exactly PDF and HTML as outputs) in https://quarto.org/docs/authoring/conditional.html.

What would you add?

[friendly]

I would add a concrete example of this use case -- including a GIF image in HTML vs. a PNG/PDF in PDF format.

[mcanouil]

There is no difference between the two, the syntax is 100% the same.
See https://quarto.org/docs/authoring/conditional.html#content-hidden.

[cscheid]

Can I suggest that the general issue of preparing books (or other projects) for HTML & LaTeX/PDF output deserves an addition to Quarto documentation? Something like this would make a good start.

Yes, that's a very good idea. We need to think more deeply about the use cases, but we hear you. Stay tuned.

[mcanouil]

FYI, there was already some addition to highlight that it is not limited to PDF/HTML: #7466

Here the issue is to avoid cluttering the documentation while providing something general enough for anyone to reuse and adapt.

[friendly]

@mcanouil

avoid cluttering the documentation while providing something general enough for anyone to reuse and adapt

Can I suggest trying to think more from a user's perspective? I did read the docs and they were insufficient for me to solve this for my use case. Why? Because the "general enough" didn't provide guidance to what would differ inside conditional blocks.

Cluttering can be avoided by simply having a separate linked document with examples.

Alternatively, I wish someone could write a blog post on this topic.

[mcanouil]

There is a repository with examples which for now is not used very much unfortunately.

The discussion board is also there to provide a lot of use case with code. It is searchable.

Note that I agree the current example showing only text in the conditional content divs does not unveil what this features could really do but I do not think having an image extension change does that either.
For instance, some users are using raw code in the conditional content, I think an example showing that the conditional contents divs is a way to use a format specific code is more helpful.

For example, what I have in mind:

---
format:
  html: default
  pdf: default
crossref:
  custom:
    - kind: float
      reference-prefix: Video
      key: vid
      latex-env: video
---

::: {.content-visible when-format="html"}

:::: {#vid-cern}

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

"CERN: The Journey of Discovery"

::::

In @vid-cern ...

:::


::: {.content-visible when-format="pdf"}

![CERN: The Journey of Discovery](https://giudice.web.cern.ch/figure/fig7-1.jpg){#fig-cern}

In @fig-cern ([also as a video](https://www.youtube.com/embed/wo9vZccmqwc)) ...

:::