Intial feature sets for figures.

[argent0]

Hi,

This is what I suggest should be the starting point in adding figure support to pandoc. Please share your comments.

General Considerations

In writing this I consider documents consisting of a main body of text and supporting
material (like tables, figures, text boxes, etc...).

I will also follow @mb21's mention of the HTML5 figure description:

Usually a <figure> is an image, illustration, diagram, code snippet, etc.,
that is referenced in the main flow of a document, but that can be moved to
another part of the document or to an appendix without affecting the main
flow.

On Figures

With this in mind I believe that having figure support in pandoc means , at
least, allowing the content to be an image, table or code snippet. That coupled
with a caption and that can be referenced in the main body, or other figures.

The first issue I see with this is that, Image is in a different level
(Inline) than CodeBlock and Table (Block).

So maybe a good initial step is to aim for Block level stand alone image. That
is an image with a caption ([Block] or [InLinie])

[argent0]

So to keep in line with the current implementations for Table and CodeBlock that are implemented at the Block level. I propose:

data Block =
   ...
   | Illustration Attr Caption Target
  ...

As an starting point. This is very much like a Link but at the Block level and different semantics . Where we could then continue building on features like the ones described here.

[tarleb]

That's an interesting question: are there formats which allow to specify block-level images? For LaTeX, HTML, JATS, and DOCX, it appears that images only become block elements by wrapping them in a figure environment or similar. Pandoc uses the Plain constructor to "lift" inline elements to the block-level.

[argent0]

Initially I'm going to study the functionality in HTML and LaTex because they provide explicit mechanism to define a figure. This still leaves unaddressed situations like

<p>...</p>
<img ..>
<p>...</p>

This page uses a different nomenclature than HTML5, so perhaps one could rename Illustration to Figure.

Next hing I'm going to study the HTML and LaTex reader to understand if and how a constructor like Illustration would fit.

[tarleb]

Maybe the JATS <fig> element can serve as another inspiration for us. It is similar to the HTML <figure> element, but slightly more explicit in what it can contain.

[argent0]

After reading about JAT's <fig> element, I see many paralles with LaTex's Float concept.

With this in mind it seems that a constructor more similar to despresc's one would reflect the concept better.

data Block
  = ...
    | Figure Attr Caption [Block]
    ...

With respesct to the information about a figure I see three aspects:

1. The concent: That is the table, the image, the code block. This should be the priority when considering the internal representation.

2. The "relationship" with the rest of the document. As in, "this figure belongs in that section". Which different formats have different ways to declare. And could be reflected in pandoc by either:

   a. its position relative to other blocks (like Header) in the [Block] list of the document.
   b. in its own Div (the Block constructor)

   This could be "decided" by the input format and its reader. That is: in the way it builds the AST

3. The layout information: as in put this figure on the top of the opposite page. This information should perhaps be translated into attributes, since control over layout differs greatly among output formats.

The need to represent something like JATS's <garphic> tag at the Block level.I think Still remains. Perhaps rename Illustration to Graphic.

[tarleb]

If I understand correctly, then one motivation for a second constructor like Illustration or Graphic is to have a block-level element to represent an image. I'd prefer if we'd ignore this at the moment, as [Plain [Image ...]] should work well enough for the time being. We can revisit this problem once we have tackled Figure.

The other observations are very apt and I think we're on a good way there.

[argent0]

One Issue not contemplated in the current simpleFigure is the alt-text. Should we require it explicitly?

simpleFigure :: Attr -> [Inline] -> Text -> Text -> Text -> Text -> Blocks
simpleFigure attr figureCaption url title altDescription =
  singleton $ Para [Image (insertAttribute "alt-text" altDescription attr) figureCaption (url, "fig:" <> title)]
  where
  insertAttribute k v attrs = _ --inserts a new key-value attribute pair

[tarleb]

I fear that the type signature would become more confusing. I'd hate having to remember if it's "title, then alt text" or the other way around.

[tarleb]

While looking at the Builder code, I remembered that there is a convention of using With for all builders that take Attr as their first element. We should probably do that here, too.

[argent0]

This means two functions? Like:

simpleFigureWith :: Attr -> ...
simpleFigureWith = ...

simpleFigure :: [Inline] -> ...
simpleFigure = simpleFigureWith ("", [], []) ...

[tarleb]

That would be the most consistent, I think. The other non-With functions in the module use nullAttr, which is the same as ("",[],[]).