Figure Output

[argent0]

Hi, I've been working on pandoc's output figures. That is, from pandoc's new
internal representation of a figure to the various output formats.

data Block =
    -- | Figure, with attributes, caption and caption position, width
    -- (optional), and content (list of blocks)
    | Figure Attr Caption [Block]

General behaviour

To make our changes the least intrusive, most of the formats follow the output that was previously used for pandoc's Divs.

Let's take for example the markdown output:

• This is how Div is handled.

Click to expand example

$ ./pandoc -f native -t markdown
[Div ("fig-id",[],[]) [Para [Image ("",[],[]) [] ("foo.png", "fig:")]]]
^D
::: {#fig-id}
![](foo.png)
:::

• This is how Figure is handled. It adds the figure class if not already
  present among the classes.

$ ./pandoc -f native -t markdown
[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]])
[Para [Image ("",[],[]) [] ("foo.png", "fig:")]]]
^D
::: {#fig-id .figure}
![](foo.png)
:::

Most output formats follow this scheme:
- Haddock
- OpenDocument
- FB2
- ZimWiki
- MediaWiki, add class "figure"
- LaTeX
- ICML
- Markdown, add class "figure"
- DokuWiki
- Docbook, allows for better handling
- ConTeXt
- AsciiDoc
- JATS
- Man
- RTF
- HTML
- Jira

Click to expand example

A figure with title

pandoc -f native -t jira
[Figure ("fig-id",[],[("title","This is the title")]) (Caption Nothing []) []]
^D
{panel:title=This is the title}
{anchor:fig-id}
{panel}

Exceptions

Textile

Handles like an html figure.

Texinfo

I've considered three cases:

1. A float that is a figure: use @float Figure. This output was tested with makeinfo and info.

Click to expand example

% pandoc -f native -t texinfo
[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Image ("",[],[]) [] ("foo.png", "fig:")]]]
^D
@node Top
@top Top

@float Figure
@image{foo,,,Caption,png}
@caption{Caption}
@end float

2. Float that has no caption and doesn't contain a SimpleFigure: use @float

Click to expand example

% pandoc -f native -t texinfo
[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Image ("",[],[]) [] ("foo.png", "")]]]

^D
@node Top
@top Top

@float
@image{foo,,,,png}
@end float

3. A float that is a table: use @float Table

Click to expand example

% pandoc -f native -t texinfo
[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]])
[Table ("",[],[]) (Caption Nothing
 [])
 [(AlignDefault,ColWidthDefault)
 ,(AlignDefault,ColWidthDefault)
 ,(AlignDefault,ColWidthDefault)]
 (TableHead ("",[],[])
 [Row ("",[],[])
  [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
   [Plain [Str "Fruit"]]
  ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
   [Plain [Str "Price"]]
  ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
   [Plain [Str "Quantity"]]]])
 [(TableBody ("",[],[]) (RowHeadColumns 0)
  []
  [Row ("",[],[])
   [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
    [Plain [Str "Apple"]]
   ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
    [Plain [Str "25",Space,Str "cents"]]
   ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
    [Plain [Str "33"]]]
  ,Row ("",[],[])
   [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
    [Plain [Str "\"Navel\"",Space,Str "Orange"]]
   ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
    [Plain [Str "35",Space,Str "cents"]]
   ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
    [Plain [Str "22"]]]
  ,Row ("",[],[])
   [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
    []
   ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
    []
   ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
    [Plain [Str "45"]]]])]
 (TableFoot ("",[],[])
 [])]]

^D
@node Top
@top Top

@float Table
@multitable {"Navel" Orange} {35 cents} {Quantity} 
@headitem 
Fruit
 @tab Price
 @tab Quantity
@item 
Apple
 @tab 25 cents
 @tab 33
@item 
"Navel" Orange
 @tab 35 cents
 @tab 22
@item 
45
@end multitable
@caption{Caption}
@end float

4. A float the isn't a table nor a figure: use @float.

Click to expand example

% pandoc -f native -t texinfo
[Figure ("fig-id",[],[]) (Caption Nothing [Para[ Str "Caption"]]) [Para [Str "Content"]]]

^D
@node Top
@top Top

@float
Content
@caption{Caption}
@end float

This is according to the documentation here.

RST

Figure float with caption at the figure level.

Click to expand example

% pandoc -f native -t rst
[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Image ("",[],[]) [] ("foo.png", "fig:")]]]

^D
.. container:: float
   :name: fig-id

   .. figure:: foo.png
      :alt: 

According to the documentation here

XWiki

Using Groups

Click to expand example

% pandoc -f native -t xwiki
[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]

^D
(((
{{id name="fig-id" /}}content
)))

Further modifications

These modifications are more involved and are up for discussion.

ConTeXt

ConTeXt supports floating elements. This would require a modification to the
template.

\definefloat[intermezzo][intermezzos]

Click to expand example

\starttext

\startstandardmakeup
  % \middlelined{How to make a document.}
  % \middlelined{by}
  % \middlelined{The Author}
\stopstandardmakeup

\completecontent

\chapter{Introduction}
... your text\index{indexentry} ...
\chapter{One Chapter}

\section[firstparagraph]{The first paragraph}

... your text ...

\section{The second paragraph}

\subsection{the first sub paragraph}

... your text\index{another indexentry} ...

\subsection{the second sub paragraph}

... your text ...

\section{The third paragraph}

... your text ...

\chapter{Another Chapter}

% Need to tell ConTeXt where the cow picture is stored
\setupexternalfigures[location={local,default}]

\startcolumns[n=3]
    caption=none
    \placefigure{none}{\externalfigure[cow][height=1cm]}
\column
    key=none
    \placefigure[none]{}{\externalfigure[cow][height=1cm]}
\column
    empty caption
    \placefigure{}{\externalfigure[cow][height=1cm]}
\stopcolumns

... your text ...

\chapter[lastchapter]{The Last Chapter}

\definefloat[intermezzo][intermezzos]

\placeintermezzo[][]{An intermezzo.}
\startframedtext
At the beginning of this century there was a tramline from Zwolle toBlokzijl via
Hasselt. Other means of transport became more importantand just before the
second world war the tramline was stopped.Nowadays such a tramline would have
been become very profitable.

caption=none
\placefigure{none}{\externalfigure[cow][height=1cm]}

\placeintermezzo[][]{An inter-intermezzo.}
\startframedtext
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
\stopframedtext

\stopframedtext

... your text ...

\completeregister

\stoptext

LaTeX

The issue is that \figure can't contain further \figure's inside. There are
alternative packages:

Click to expand example

\usepackage{caption}
\usepackage{subcaption}
...
\begin{figure}
     \begin{subfigure}[b]{0.5\textwidth}
		Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod

     	\begin{subfigure}[b]{0.5\textwidth}
			\centering
			This.
         	\caption{Inner 1.1}
     	\end{subfigure}
     	\begin{subfigure}[b]{0.5\textwidth}
			\centering
			That.
         	\caption{Inner 1.2}
     	\end{subfigure}
         \caption{Inner 1}
         \label{fig:inner1}
     \end{subfigure}
     \begin{subfigure}[b]{0.5\textwidth}
		Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
         \caption{$Inner 2$}
         \label{fig:inner2}
     \end{subfigure}
        \caption{Outer caption}
        \label{fig:outer}
\end{figure}

The caption package plays well with latex's default
classes(book,
report, article) and beamer and thesis.

But is not installed in the default ubuntu package. It is on ubuntu on this
package.

One idea would be to include figure support as an extension.

HTML5

I'll show a tentative output when I have it ready.