Wiki source code of Images, Figures and Captions
Last modified by Vincent Massol on 2026/08/30 20:43
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | The LaTeX exporter turns every image of an exported page into a LaTeX ##\includegraphics## command, and it understands both of the ways XWiki gives an image or a table a caption: the Figure macro and the extended image syntax of XWiki Syntax 2.1. | ||
| 2 | |||
| 3 | == Images == | ||
| 4 | |||
| 5 | An image that stands alone in its paragraph is centred in the exported document; an image that sits in a line of text stays where it is. The image file itself is copied into the [[export package>>doc:documentation.extensions.dev.latex.export-package.WebHome]], so the exported document needs nothing from the wiki to compile. | ||
| 6 | |||
| 7 | == Image Size == | ||
| 8 | |||
| 9 | The ##width## and ##height## parameters of an image are translated as follows. | ||
| 10 | |||
| 11 | |=Written as|=Exported as|=Example | ||
| 12 | |a width in percent|a fraction of ##\linewidth##|##width=50%## gives ##width=0.5\linewidth## | ||
| 13 | |a height in percent|a fraction of ##\textheight##, that is of the height of the page|##height=50%## gives ##height=0.5\textheight## | ||
| 14 | |any other unit|pixels|##width=100## gives ##width=100px## | ||
| 15 | |||
| 16 | For example: | ||
| 17 | |||
| 18 | {{code language="none"}} | ||
| 19 | [[image:whatever||width="100"]] | ||
| 20 | {{/code}} | ||
| 21 | |||
| 22 | is exported as: | ||
| 23 | |||
| 24 | {{code language="tex"}} | ||
| 25 | \includegraphics[width=100px]{whatever} | ||
| 26 | {{/code}} | ||
| 27 | |||
| 28 | == Captioned Figures and Tables == | ||
| 29 | |||
| 30 | Caption an image or a table with the [[Figure macro>>doc:extensions:Extension.Figure Macro.WebHome]] and the ##figureCaption## macro inside it. The export writes a LaTeX ##figure## environment for a figure and a ##table## environment for a table, each holding a ##\caption##, and an ##id## macro placed in the caption becomes the ##\label## that a cross-reference points at. | ||
| 31 | |||
| 32 | The ##type## parameter of the Figure macro states the type by hand. Left out, or set to ##automatic##, the type is inferred from the content: a figure whose content is a table alone becomes a ##table##. Stating it by hand needs version 1.6 or later of the [[Numbered Figures Application>>doc:extensions:Extension.Numbered Content.Numbered Figures Application.WebHome]] where that application is used. | ||
| 33 | |||
| 34 | A caption may span several paragraphs, hold line breaks or hold a list. What that means for a list of figures is described below. | ||
| 35 | |||
| 36 | {{code language="none"}} | ||
| 37 | See figure {{reference figure="f1"/}}. | ||
| 38 | |||
| 39 | {{figure}} | ||
| 40 | [[image:apple.png||width=100]] | ||
| 41 | |||
| 42 | {{figureCaption}}{{id name="f1"/}}An image{{/figureCaption}} | ||
| 43 | {{/figure}} | ||
| 44 | |||
| 45 | See table {{reference figure="t1"/}}. | ||
| 46 | |||
| 47 | {{figure}} | ||
| 48 | |a|b | ||
| 49 | |||
| 50 | {{figureCaption}}{{id name="t1"/}}A table{{/figureCaption}} | ||
| 51 | {{/figure}} | ||
| 52 | |||
| 53 | {{figure type='table'}} | ||
| 54 | ... | ||
| 55 | {{/figure}} | ||
| 56 | {{/code}} | ||
| 57 | |||
| 58 | {{image reference="figure-macro-output.png" size="large" alt="The compiled export, showing the apple image as Figure 1 and a two-cell table as Table 1, each with its caption underneath"/}} | ||
| 59 | |||
| 60 | The extended image syntax of XWiki Syntax 2.1 carries a caption too, in the label of the image reference — ##~[~[An image~>~>image~:apple.png]]##. It produces the same captioned figure as the Figure macro. | ||
| 61 | |||
| 62 | == Captions in the List of Figures and Tables == | ||
| 63 | |||
| 64 | The **Figures** and **Tables** [[export options>>doc:documentation.extensions.user.latex.export-page.export-options.WebHome]] put a list of figures and a list of tables in the exported document. An entry of such a list is a single line, so the export flattens each caption into inline content and writes the two-part LaTeX form ##\caption[flattened]{full}##: the bracketed version goes to the list, the braced one stays under the figure. | ||
| 65 | |||
| 66 | Flattening keeps text formatting, links, inline macros, and the content of a Raw macro whose syntax is ##latex/1.0## — that content is taken as it stands and is expected to be inline. It drops standalone macros, the content of a Raw macro in any other syntax, and the figure and table numbers that a numbering application puts in front of a caption. What is left is joined with spaces. | ||
| 67 | |||
| 68 | {{info}} | ||
| 69 | It is up to you to make sure that a caption survives that conversion and still works inside a LaTeX ##\caption## command, especially where the caption uses an inline macro or the Raw macro. | ||
| 70 | {{/info}} | ||
| 71 | |||
| 72 | So this caption: | ||
| 73 | |||
| 74 | {{code language="none"}} | ||
| 75 | {{figureCaption}}{{id name="test"/}}Image **caption**. | ||
| 76 | |||
| 77 | {{raw syntax="latex/1.0"}}Raw content kept.{{/raw}} | ||
| 78 | |||
| 79 | {{raw syntax="html/4.01"}}Raw content removed.{{/raw}} | ||
| 80 | |||
| 81 | With [[//several//>>https://xwiki.org]] paragraphs {{info}}and an inline macro.{{/info}} | ||
| 82 | |||
| 83 | {{info}}standalone macro{{/info}} | ||
| 84 | |||
| 85 | * And a | ||
| 86 | * list! | ||
| 87 | {{/figureCaption}} | ||
| 88 | {{/code}} | ||
| 89 | |||
| 90 | is exported as: | ||
| 91 | |||
| 92 | {{code language="latex"}} | ||
| 93 | \caption[Image \textbf{caption}. Raw content kept. With \href{https://xwiki.org}{\textit{several}} paragraphs \xwikiinfoinline{and an inline macro.} And a list!]{\label{test}Image \textbf{caption}. | ||
| 94 | |||
| 95 | Raw content kept. | ||
| 96 | |||
| 97 | With \href{https://xwiki.org}{\textit{several}} paragraphs \xwikiinfoinline{and an inline macro.} | ||
| 98 | |||
| 99 | \begin{xwikiinfo}{} | ||
| 100 | standalone macro | ||
| 101 | \end{xwikiinfo} | ||
| 102 | |||
| 103 | \begin{itemize} | ||
| 104 | \item And a | ||
| 105 | \item list! | ||
| 106 | \end{itemize}} | ||
| 107 | {{/code}} | ||
| 108 | |||
| 109 | The Raw macro in ##latex/1.0## is kept and the one in ##html/4.01## is gone, and the list of figures shows the bracketed part alone: | ||
| 110 | |||
| 111 | {{code language="latex"}} | ||
| 112 | Image \textbf{caption}. Raw content kept. With \href{https://xwiki.org}{\textit{several}} paragraphs \xwikiinfoinline{and an inline macro.} And a list! | ||
| 113 | {{/code}} |
