Texor : Figures

Images are an essential component in any article, However due to the differences in the support for various graphic formats between LaTeX and markdown/HTML we need to fallback on raster graphics.

Graphics.Format	LaTeX	Markdown	RMarkdown	Texor Compatibility
PNG	✓	✓	✓	✓
JPG	✓	✓	✓	✓
PDF	✓	✗	✗	✓(after rasterization)
Tikz	✓	✗	✓(using tikz engine)	✓(after rasterization)
Algorithm	✓	✗	✗	✓ (using pseudocodejs)

Table 1 : Image Format support in various Markup/Typesetting Languages

As we can observe from the above table, raster (PNG and JPG) images are relatively easy to handle and do not require any additional pre-processing. Pandoc handles it well.

PNG,JPG images are easily included as markdown images with captions, labels and other parameters.

For other image formats like tikz and algorithm, they are first isolated and compiled into a PDF, then to a PNG using pdftools package.

For the best results after conversion :

1. Avoid using framebox or any other latex command to wrap the \includegraphics{} . This might interfere with the packages ability to properly read the path and copy the relevant image properly.
2. Try to keep the actual content of the caption without any LaTeX markup (normal text), as it is not reflected in HTML properly.

Figures as Code chunks

In newer versions of texor package, a new option is available to convert figures into Rmarkdown style code chunks to include figures there. If the option fig_in_r is set TRUE, a custom Lua Filter will transform the image structure.

For example :

\begin{figure}
  \includegraphics{image/sample.png}
  \caption{This is a sample caption}
  \labeL{fig:image-1}
\end{figure}

will be converted to

```{r , echo=FALSE , fig.cap="This is a sample caption", fig.alt="graphic without alt text",
 fig.show='hold', fig.align="center", out.width="100%"}
knitr::include_graphics(c("image/sample.png"))
```

if the option fig_in_r is set FALSE, a simple markdown figure would be generated

![Figure 1: This is a sample caption](image/sample.png){width="100%"
alt="graphic without alt text"}

Notes

1. Default handling of the texor package is to generate R markdown style code chunks to include images using knitr::include_graphics(c(file_path)). This mechanism was added using a unique Lua filter ^[Included in texor v1.5.0 and above] which can also handle multiple images in a single figure environment as well. The Lua filter is open source and available under MIT License here.
2. If you set the option fig_in_r = FALSE in rnw_to_rmd() or latex_to_web() functions, you can revert back to simple markdown figures which has the following syntax ![caption](file_path){#identifier ..}.
3. Some authors used to add verbatim environments inside figure environments to be able to add captions. To maintain parity, the texor package transforms the block into a raw HTML block so as to enable such out of the box use of figure environment in markdown.
4. In case you set fig_in_r = FALSE, the captions added to the figures will be appended with figure numbering which would also be reflected in the references to the figures throughout the document as well. If you want to add or change the position of the position of the figures exercise caution.
5. To add to accessibility, we have added a default alt-text to every figure which is meant to motivate the author to replace it with a better alt-text rather than repeating the caption as alt-text. However in case of bulk conversions the alt-text is a reasonable placeholder compared to no alt-text at all.

Some common issues

1. PNG Converted from PDF did not render correctly

The texor package does not convert the PDFs into PNGs. This is handled by pdftools using poppler utils. Some older versions of poppler might miss out on some fonts or bug fixes. To avoid this please install the latest poppler utils available for your distribution.

2. How to include Multi-Page PDF files ?

Currently there is no automated solution to fix this issue, but texor package identifies if the pdf file is multi-paged and it will generate png files of every page. So you can include the original multi-pdf file once and rename the other included pdf files as filename_pageno.png

for example this figure environment will not convert properly as there are multiple pages in this and the naming will change for the rasterized png files.

\begin{figure}
\includegraphics[page=1]{plots.pdf}\includegraphics[page=2]{plots.pdf}
\includegraphics[page=3]{plots.pdf}\includegraphics[page=4]{plots.pdf}
\caption{ A few output plots}
\label{fig:1}
\end{figure}

Instead you can declare the figure block as this and remove the dummy figure block later in Rmd :

\begin{figure}
% a dummy pdf image to invoke the pdf-to-png conversion
% remove this image from the figure environment later in Rmd
\includegraphics[page=1]{plots.pdf}
%
%
\includegraphics[page=1]{plots_1.png}\includegraphics[page=2]{plots_2.png}
\includegraphics[page=3]{plots_3.png}\includegraphics[page=4]{plots_4.png}
\caption{ A few output plots}
\label{fig:1}
\end{figure}