ox-latex-subfig

Presentation

You can read this text more comfortably with Emacs, just donwload README.org.

This package turns an Org table (https://orgmode.org) into a series of \LaTeX subfloat. It also enables subcaptions, different widths for the sub-figures and to pass options to the \LaTeX includegraphics and includesvg commands.

The program is actually a filter for Org tables. It uses regular expressions to replace the text that Org's \LaTeX exporter produces with suitable minipage and subfloat environments.

Config ARCHIVE noexport

How

Installation

Get the code

To install, you can clone this repository using the Linux terminal:

torsocks git clone https://www.notabug.org/broncodev/ox-latex-subfig

That will create an ox-latex-subfig sub-directory where you typed that command. Then, you can add one of these 2 into your Emacs init file (usually =.emacs= or init.el=; you can find it in the Emac's =user-init-file variable):

Load into Emacs

Autoload with (require 'package)

#+begin_src emacs-lisp (with-eval-after-load "ox" (add-to-list 'load-path "/path/to/use-package") (require 'ox-latex-subfig) ;; ;; If you want the caption above the figure ;; (add-to-list 'org-latex-caption-above 'subfig) ) #+end_src

Autoload with use-package.el (https://github.com/jwiegley/use-package)

#+BEGIN_SRC emacs-lisp ;; Add use-package to `load-path' (add-to-list 'load-path "/path/to/use-package") ;; Load `use-package' (require 'use-package) ;; Enable (use-package ox-latex-subfig :init (setq org-latex-prefer-user-labels t) :load-path "/path/to/ox-latex-subfig/" :after "ox" :config (require 'ox-latex-subfig) ;; ;; If you want the caption above the figure ;; (add-to-list 'org-latex-caption-above 'subfig) ) #+END_SRC

Add needed packages into your Org file

In your Org file, you'll need to load the subfig package. This is included in many GNU/Linux distibutions. Techincally, the caption and hyperref packages are also needed for captions and links in the PDF, but no further configuration is needed in vanilla Org (check org-latex-packages-alist and org-latex-default-packages-alist).

,#+LATEX_HEADER: \usepackage{subfig}

Install TeX Live

pacman -S texlive-core

sudo apt-get install texlive-generic-extra

SVG support (optional)

If you are going to use svg files, you will need the \LaTeX svg package. You can get it with the texlive-latexextra in some distributions

pacman -S texlive-latexextra

,#+LATEX_HEADER: \usepackage{svg} ,#+LATEX_HEADER: \svgpath{{my/path1}{my/figures/path}}

Use (examples)

There is a transmission.svg included in this repository, which comes from the transmission-gtk package (http://www.transmissionbt.com/). If you convert that file to png (with ImageMagick: convert transmission.svg transmission.png), the examples below will show an image. You can also replace transmission.png and transmission.svg with something that you prefer (try example-image-a.png).

Plain example

,#+LATEX_HEADER: \usepackage{svg} ,#+LATEX_HEADER: \usepackage{subfig} ,#+NAME: fig:hello ,#+CAPTION: This caption has two ,#+caption: #+caption: lines ,#+ATTR_LATEX: :environment subfig :width 0.3\textwidth | | | Description |

Description

\begin{figure}[htbp] \noindent\null\hfill% \begin{minipage}[l]{0.3\textwidth}% \centering% \subfloat[Description]{% \includesvg[width=\textwidth]{transmission}}% \end{minipage}\hfill\null% \caption{\label{fig:hello}This caption has two \texttt{\#+caption:} lines}% \end{figure}%

Example with links (Org and \LaTeX), specific width, vertical alignment and list of figures

One can have sub-captions, links, set vertical alignment and provide options to the =\includegraphics= or =\includesvg= \LaTeX macros.

Sub-captions

second row of the table, even if empty

Links

next to the description, in regular Org syntax (e.g. <<my-link>>)

Options

third row of the table (optional; passed to \includegraphics or \includesvg)

List of figures

just add lofdepth to the \LaTeX subfig package.

Vertical alignment

with the :align option for #+ATTR_LATEX: (may have more than one value. For example: =:align bt=; see Ex. ex-lof)

Specific width

with the :width option for #+ATTR_LATEX:. If more than one value is provided, it has to be a comma-separated list with no spaces (see Ex. ex-empty-caption-diff-width). The first value corresponds to the first column, and so on.

,#+latex_header: \usepackage{svg} ,#+latex_header: \usepackage[lofdepth]{subfig}

<>

,#+latex: \listoffigures

,#+NAME: fig:ex-lof ,#+CAPTION: Getting sub-captions, links, a list of figures and options ,#+ATTR_LATEX: :environment subfig :width 0.4\textwidth :align b | | | | Description<> | This is a very long description which should not fit on a single line on a regular page | | width=0.3\textwidth | | This sub-figure is here (Fig. subfig-ex-lof)

Description	This is a very long description which should not fit on a single line on a regular page
width=0.3\textwidth
his sub-figure is here (Fig. subfig-ex-lof

\listoffigures

\begin{figure}[htbp] \noindent\null\hfill% \begin{minipage}[b]{0.4\textwidth}% \centering% \subfloat[Description]{% \includesvg[width=0.3\textwidth]{transmission}}% \end{minipage}\hfill% \begin{minipage}[b]{0.4\textwidth}% \centering% \subfloat[This is a very long description which should not fit on a single line on a regular page]{% \includesvg[width=\textwidth]{transmission}}% \end{minipage}\hfill\null% \caption{\label{fig:ex-lof}Getting sub-captions, links, a list of figures and options}% \end{figure}% This sub-figure is here (Fig. \ref{subfig-ex-lof})

Empty caption, link and different widths

,#+latex_header: \usepackage{subfig}

<>

,#+NAME: fig:ex-empty-caption-diff-width ,#+CAPTION: Empty caption, link and different widths ,#+ATTR_LATEX: :environment subfig :width 0.4\textwidth,0.5\textwidth :align b | | | | | | | width=0.9\textwidth | width=0.8\textwidth |

\begin{figure}[htbp] \noindent\null\hfill% \begin{minipage}[b]{0.4\textwidth}% \centering% \subfloat[]{% \includesvg[width=0.9\textwidth]{transmission}}% \end{minipage}\hfill% \begin{minipage}[b]{0.5\textwidth}% \centering% \subfloat[]{% \includesvg[width=0.8\textwidth]{transmission}}% \end{minipage}\hfill\null% \caption{\label{fig:hello}Empty caption, link and different widths}% \end{figure}%

Two images on top of each other

This is a hack, but works to have two subfigures on top of each other.

,#+LATEX_HEADER: \usepackage{subfig} ,#+LATEX_HEADER: \usepackage{svg}

<>

,#+CAPTION: Two images on top of each other ,#+ATTR_LATEX: :environment subfig :width \textwidth :align b | | | Above. \medskip | | width=0.4\textwidth | | | | Underneath. | | width=0.3\textwidth |

\begin{figure}[htbp] \noindent\null\hfill% \begin{minipage}[b]{\textwidth}% \centering% \subfloat[Above. \medskip]{% \includesvg[width=0.4\textwidth]{transmission}}% \end{minipage}\hfill% \begin{minipage}[b]{\textwidth}% \centering% \subfloat[Underneath.]{% \includesvg[width=0.3\textwidth]{transmission}}% \end{minipage}\hfill\null% \caption{Two images on top of each other}% \end{figure}%

Extra Advice

If you were using \LaTeX subcaption (now deprecated; the reason to create ox-latex-subfig) through ox-latex-subfigure as I was, you may need to update your Org documents. Here is a convenient one-liner that can help you (files may have spaces in their names):

find . -type f \-name '*.org' -exec \ grep -l '\(:environment subfigure\|usepackage.subcaption\)' \{\} + | \ while IFS= read -r -d$'\n' file; do printf "$file\n"; sed -i 's/:environment subfigure/:environment subfig/g; s/usepackage.subcaption./usepackage{subfig}/g;' "$file"; done

Known bugs (don't do this)

Either #+CAPTION: or #+name: are needed

To fix this, just add either #+caption: or #+name: (not empty).

,#+LATEX_HEADER: \usepackage{svg} ,#+LATEX_HEADER: \usepackage{subfig} ,#+ATTR_LATEX: :environment subfig | | | Description |

\begin{center} \begin{subfig}{l} \toprule \begin{center} \includesvg[width=.9\linewidth]{transmission} \end{center}\\ Description\\ \bottomrule \end{subfig} \end{center}

Not enough horizontal space specified by :width (or :align)

In this example, one would expect to have 2 pictures atop and 2 at the bottom. However, only 2 values of :width are provided. When the number of :width (or :align) values is less than the number of sub-figures, the last value is used for the remaining pictures. Since there are 4 pictures and only 2 values here (namely 0.4\textwidth and 0.6\textwidth) the latter is used for the figures at the top right, bottom left and bottorm right. \LaTeX still uses the last width value and the pictures "overflow" the margin.

Although it is proper \LaTeX code, it will not render what one would expect. Trying to minimise the issue with the options which are passed to includesvg or includegraphics will not change the fact that the minipage tries to take 0.6\textwidth.

,#+latex_header: \usepackage{subfig}

,#+NAME: fig:hello ,#+CAPTION: This caption has two ,#+caption: #+caption: lines ,#+ATTR_LATEX: :environment subfig :width 0.4\textwidth,0.6\textwidth :align b | | | | Top left | Top right | | width=0.9\textwidth | width=0.8\textwidth | | | | | Bottom left | Bottom right | | width=0.7\textwidth | width=0.85\textwidth | \hline

\begin{figure}[htbp] \noindent\null\hfill% \begin{minipage}[b]{0.4\textwidth}% \centering% \subfloat[Top left]{% \includesvg[width=0.9\textwidth]{transmission}}% \end{minipage}\hfill% \begin{minipage}[b]{0.6\textwidth}% \centering% \subfloat[Top right]{% \includesvg[width=0.8\textwidth]{transmission}}% \end{minipage}\hfill% \begin{minipage}[b]{0.6\textwidth}% \centering% \subfloat[Bottom left]{% \includesvg[width=0.7\textwidth]{transmission}}% \end{minipage}\hfill% \begin{minipage}[b]{0.6\textwidth}% \centering% \subfloat[Bottom right]{% \includesvg[width=0.85\textwidth]{transmission}}% \end{minipage}\hfill\null% \caption{\label{fig:hello}This caption has two \texttt{\#+caption:} lines}% \end{figure}%

\hline

file:ex-bug-long-width.png

Disarranging the caption and the options

The row following the figure is destined to set the description (and label, a.k.a. reference or tag). If they are switched, the program will place them in \LaTeX code, but that code would be invalid.

,#+latex_header: \usepackage{subfig} ,#+NAME: fig:hello ,#+CAPTION: This caption has two ,#+caption: #+caption: lines ,#+ATTR_LATEX: :environment subfig :width 0.4\textwidth,0.5\textwidth | | | | width=0.5\textwidth | | | Left subfigure | |

Disarranging the rows of the sub-figures

The program expects that links to subfigures are on the same row.

,#+latex_header: \usepackage{subfig} ,#+NAME: fig:hello ,#+CAPTION: This caption has two ,#+caption: #+caption: lines ,#+ATTR_LATEX: :environment subfig :width 0.4\textwidth,0.5\textwidth | | | | width=0.5\textwidth | | | Left subfigure | |

Providing spurious data

In general, providing either a) only one option for :width and :align, or b) the same number of options (to :width and :align) as there are figures is the best way for the program to work. If there are more of these options than figures, they will be disregarded. If there are less, the last is used for the remaining figures. This can be a feature, but some may find unexpected results.

Breaking the code

If you look at the code, there are ways to make it fail on purpose! Try these:

Misplacing \LaTeX macros or commands as options or descriptions

If you really want, you can pass a macro or command as a sub-caption (description) or option (to includegraphics or includesvg), but that will be at your own risk

,#+LATEX_HEADER: \usepackage{svg} ,#+LATEX_HEADER: \usepackage{subfig} ,#+NAME: fig:hello ,#+CAPTION: This caption has two ,#+caption: #+caption: lines ,#+ATTR_LATEX: :environment subfig | | file:transmission.svg]] | | \end{subfig} | Right subcaption | | \end{table} | |

,#+LATEX_HEADER: \usepackage{svg} ,#+LATEX_HEADER: \usepackage{subfig} ,#+NAME: fig:hello ,#+CAPTION: This caption has two ,#+caption: #+caption: lines ,#+ATTR_LATEX: :environment subfig | | file:transmission.svg]] | | \end{subfig} | \end{table} |

,#+LATEX_HEADER: \usepackage{svg} ,#+LATEX_HEADER: \usepackage{subfig} ,#+NAME: fig:hello ,#+CAPTION: This caption has two ,#+caption: #+caption: lines ,#+ATTR_LATEX: :environment subfig | | file:transmission.svg]] | | | \end{subfig} | | option=val | \end{table} |

TODO Other things to improve

[ ] allow for inner horizontal alignment

Each subfigure is horizontallly centred in the minipage. Similar to :width, one could use a comma-separated list for :align to provide horizontal and vertical alignment. Right now, only vertical alignment can be provided

[ ] Use rx-notation

There are many things which can be now simplified thanks to the rx-notation

Contributions

• conao3, a.k.a linktohack
• creator of ox-latex-subfigure.el (on which this project was initially based)
• @eoma
• org-mode 9 compatibility
• eDgar
• SVG support
• Individual options for each subfigure (width etc)
• Different widths
• Different aligns
• Subfig and minipage compatibility
• Examples, documentation
• others
• Emacs team (mailing list and manual)
• Org team (mailing list and manual)
• using minipage and subfig
• subfig documentation
• caption documentation
• https://tex.stackexchange.com/a/6486
• https://tex.stackexchange.com/questions/68001/side-by-side-minipage-figures
• https://tex.stackexchange.com/a/127386
• https://texblog.org/2011/05/24/placing-figures-side-by-side-subfig/#comment-5520
• centering with \hfill and \null
• https://tex.stackexchange.com/questions/349355/center-two-images-using-multiple-hfills#comment857816_349355
• https://tex.stackexchange.com/a/349356
• https://tex.stackexchange.com/a/528921

Testing environment

• "GNU Emacs 28.2 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.36, cairo version 1.17.6) of 2023-01-03"
• Org mode version 9.4.6 (release_9.4.6-13-g4be129)
• \LaTeX svg v2.02k (2020/11/26)
• \LaTeX subfig 1.3 2005/07/05
• \LaTeX caption v3.6 2022/02/20
• \LaTeX hyperref v7.00n 2022-02-21
• XeTeX 3.141592653-2.6-0.999995 (TeX Live 2023)
• kpathsea version 6.3.5
• Compiled with ICU version 73.2; using 73.2
• Compiled with zlib version 1.2.13; using 1.2.13
• Compiled with FreeType2 version 2.13.1; using 2.13.1
• Compiled with Graphite2 version 1.3.14; using 1.3.14
• Compiled with HarfBuzz version 7.3.0; using 7.3.0
• Compiled with libpng version 1.6.40; using 1.6.40
• Compiled with pplib version v2.05 less toxic i hope
• Compiled with fontconfig version 2.14.2; using 2.14.2

License

GNU General Public License Version 3 (GPL v.3) GNU Free Document License 1.3 (https://www.gnu.org/licenses/fdl-1.3.html)

More config ARCHIVE noexport