org: LaTeX specific attributes
12.7.4 LaTeX specific attributes
--------------------------------
LaTeX understands attributes specified in an ‘ATTR_LATEX’ line. They
affect tables, images, plain lists, special blocks and source blocks.
Tables in LaTeX export
......................
For LaTeX export of a table, you can specify a label and a caption
(Images and tables). You can also use attributes to control
table layout and contents. Valid LaTeX attributes include:
‘:mode’
Nature of table’s contents. It can be set to ‘table’, ‘math’,
‘inline-math’ or ‘verbatim’. In particular, when in ‘math’ or
‘inline-math’ mode, every cell is exported as-is, horizontal rules
are ignored and the table will be wrapped in a math environment.
Also, contiguous tables sharing the same math mode will be wrapped
within the same environment. Default mode is determined in
‘org-latex-default-table-mode’.
‘:environment’
Environment used for the table. It can be set to any LaTeX table
environment, like ‘tabularx’(1), ‘longtable’, ‘array’, ‘tabu’(2),
‘bmatrix’... It defaults to ‘org-latex-default-table-environment’
value.
‘:caption’
‘#+CAPTION’ keyword is the simplest way to set a caption for a
table (Images and tables). If you need more advanced
commands for that task, you can use ‘:caption’ attribute instead.
Its value should be raw LaTeX code. It has precedence over
‘#+CAPTION’.
‘:float’
‘:placement’
Float environment for the table. Possible values are
‘sidewaystable’, ‘multicolumn’, ‘t’ and ‘nil’. When unspecified, a
table with a caption will have a ‘table’ environment. Moreover,
‘:placement’ attribute can specify the positioning of the float.
‘:align’
‘:font’
‘:width’
Set, respectively, the alignment string of the table, its font size
and its width. They only apply on regular tables.
‘:spread’
Boolean specific to the ‘tabu’ and ‘longtabu’ environments, and
only takes effect when used in conjunction with the ‘:width’
attribute. When ‘:spread’ is non-‘nil’, the table will be spread
or shrunk by the value of ‘:width’.
‘:booktabs’
‘:center’
‘:rmlines’
They toggle, respectively, ‘booktabs’ usage (assuming the package
is properly loaded), table centering and removal of every
horizontal rule but the first one (in a "table.el" table only). In
particular, ‘org-latex-tables-booktabs’ (respectively
‘org-latex-tables-centered’) activates the first (respectively
second) attribute globally.
‘:math-prefix’
‘:math-suffix’
‘:math-arguments’
A string that will be inserted, respectively, before the table
within the math environment, after the table within the math
environment, and between the macro name and the contents of the
table. The ‘:math-arguments’ attribute is used for matrix macros
that require more than one argument (e.g., ‘qbordermatrix’).
Thus, attributes can be used in a wide array of situations, like
writing a table that will span over multiple pages, or a matrix product:
#+ATTR_LATEX: :environment longtable :align l|lp{3cm}r|l
| ..... | ..... |
| ..... | ..... |
#+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times
| a | b |
| c | d |
#+ATTR_LATEX: :mode math :environment bmatrix
| 1 | 2 |
| 3 | 4 |
In the example below, LaTeX command ‘\bicaption{HeadingA}{HeadingB}’
will set the caption.
#+ATTR_LATEX: :caption \bicaption{HeadingA}{HeadingB}
| ..... | ..... |
| ..... | ..... |
Images in LaTeX export
......................
Images that are linked to without a description part in the link, like
‘[[file:img.jpg]]’ or ‘[[./img.jpg]]’ will be inserted into the PDF
output file resulting from LaTeX processing. Org will use an
‘\includegraphics’ macro to insert the image(3).
You can specify specify image width or height with, respectively,
‘:width’ and ‘:height’ attributes. It is also possible to add any other
option with the ‘:options’ attribute, as shown in the following example:
#+ATTR_LATEX: :width 5cm :options angle=90
[[./img/sed-hr4049.pdf]]
If you need a specific command for the caption, use ‘:caption’
attribute. It will override standard ‘#+CAPTION’ value, if any.
#+ATTR_LATEX: :caption \bicaption{HeadingA}{HeadingB}
[[./img/sed-hr4049.pdf]]
If you have specified a caption as described in Images and
tables, the picture will be wrapped into a ‘figure’ environment and
thus become a floating element. You can also ask Org to export an image
as a float without specifying caption by setting the ‘:float’ attribute.
You may also set it to:
− ‘t’: if you want to use the standard ‘figure’ environment. It is
used by default if you provide a caption to the image.
− ‘multicolumn’: if you wish to include an image which spans multiple
columns in a page. This will export the image wrapped in a
‘figure*’ environment.
− ‘wrap’: if you would like to let text flow around the image. It
will make the figure occupy the left half of the page.
− ‘nil’: if you need to avoid any floating environment, even when a
caption is provided.
To modify the placement option of any floating environment, set the
‘placement’ attribute.
#+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement {r}{0.4\textwidth}
[[./img/hst.png]]
If the ‘:comment-include’ attribute is set to a non-‘nil’ value, the
LaTeX ‘\includegraphics’ macro will be commented out.
Plain lists in LaTeX export
...........................
Plain lists accept two optional attributes: ‘:environment’ and
‘:options’. The first one allows the use of a non-standard environment
(e.g., ‘inparaenum’). The second one specifies additional arguments for
that environment.
#+ATTR_LATEX: :environment compactitem :options [$\circ$]
- you need ``paralist'' package to reproduce this example.
Source blocks in LaTeX export
.............................
In addition to syntax defined in Literal examples, names and
captions (Images and tables), source blocks also accept a
‘:float’ attribute. You may set it to:
− ‘t’: if you want to make the source block a float. It is the
default value when a caption is provided.
− ‘multicolumn’: if you wish to include a source block which spans
multiple columns in a page.
− ‘nil’: if you need to avoid any floating environment, even when a
caption is provided. It is useful for source code that may not fit
in a single page.
#+ATTR_LATEX: :float nil
#+BEGIN_SRC emacs-lisp
Code that may not fit in a single page.
#+END_SRC
Special blocks in LaTeX export
..............................
In LaTeX back-end, special blocks become environments of the same name.
Value of ‘:options’ attribute will be appended as-is to that
environment’s opening string. For example:
#+BEGIN_ABSTRACT
We demonstrate how to solve the Syracuse problem.
#+END_ABSTRACT
#+ATTR_LATEX: :options [Proof of important theorem]
#+BEGIN_PROOF
...
Therefore, any even number greater than 2 is the sum of two primes.
#+END_PROOF
becomes
\begin{abstract}
We demonstrate how to solve the Syracuse problem.
\end{abstract}
\begin{proof}[Proof of important theorem]
...
Therefore, any even number greater than 2 is the sum of two primes.
\end{proof}
If you need to insert a specific caption command, use ‘:caption’
attribute. It will override standard ‘#+CAPTION’ value, if any. For
example:
#+ATTR_LATEX: :caption \MyCaption{HeadingA}
#+BEGIN_PROOF
...
#+END_PROOF
Horizontal rules
................
Width and thickness of a given horizontal rule can be controlled with,
respectively, ‘:width’ and ‘:thickness’ attributes:
#+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt
-----
---------- Footnotes ----------
(1) Requires adding the ‘tabularx’ package to
‘org-latex-packages-alist’.
(2) Requires adding the ‘tabu’ package to ‘org-latex-packages-alist’.
(3) In the case of TikZ (<http://sourceforge.net/projects/pgf/>)
images, it will become an ‘\input’ macro wrapped within a ‘tikzpicture’
environment.