356 lines
13 KiB
Plaintext
356 lines
13 KiB
Plaintext
━━━━━━━━━━━━━━━━━
|
||
JUNE 2021
|
||
A relaxed month
|
||
|
||
TEC
|
||
━━━━━━━━━━━━━━━━━
|
||
|
||
|
||
2021-06-34
|
||
|
||
|
||
The previous two months have been pretty good for Org development — with
|
||
many bug fixes and feature improvements. This month has been
|
||
substantially slower than the last[1], but that’s not to say not much is
|
||
happening: in fact, there are some rather nifty contributions lined up
|
||
for the not-too-distant future and a certain long-awaited feature
|
||
branch[2] is getting very close to merging 😀. You’ll just have to stick
|
||
around to hear about those in a future edition of TMIO 😉.
|
||
|
||
<file:figures/dilbert-zenos-paradox.jpg>
|
||
|
||
|
||
Customise the reference command used in LaTeX
|
||
═════════════════════════════════════════════
|
||
|
||
Previously, whenever you linked to another part of your document (with
|
||
or without giving it a name) — for example with `[[Profound section]]'
|
||
or similar — when exporting to LaTeX Org would /always/ use the `\ref'
|
||
command.
|
||
|
||
<file:figures/org-latex-default-reference-to-sec.png>
|
||
|
||
You can now set the format string `org-latex-reference-command'
|
||
(`\\ref{%s}' by default) to anything you’d like. For example, making
|
||
use of the [cleveref] package I can set this to `\\cref{%s}' and then
|
||
add `("capitalize" "cleveref" nil)'[3] to `org-latex-packages-alist'.
|
||
|
||
<file:figures/org-latex-cref-reference-to-sec.png>
|
||
|
||
|
||
[cleveref] <https://ctan.org/pkg/cleveref>
|
||
|
||
|
||
A diversion into writing Org for LaTeX
|
||
══════════════════════════════════════
|
||
|
||
Speaking of LaTeX exports, a member of the Org mailing list recently
|
||
told us about [a paper] pushed to [arXiv] which was written /entirely/
|
||
in Org. Why don’t we use that as a prompt to talk a bit about
|
||
generating LaTeX documents from Org?
|
||
|
||
For an experienced LaTeX-er, Org may initially appear best suited to
|
||
simple documents, but in fact it’s possible to reproduce any LaTeX
|
||
structure in Org with no more difficulty (often less) than in LaTeX.
|
||
|
||
|
||
[a paper] <https://arxiv.org/abs/2106.05096>
|
||
|
||
[arXiv] <https://arxiv.org/>
|
||
|
||
Simple elements
|
||
───────────────
|
||
|
||
The “basic” Org elements are simply translated to their LaTeX
|
||
counterparts. Markup like *bold*, /italic/, etc. are simply translated
|
||
through `org-latex-text-markup-alist'.
|
||
|
||
For those of us who dabble with equations, Org is [very accomodating].
|
||
You can type (LaTeX-style) inline and display equations in exactly the
|
||
same way (`\( \)' and `\[ \]'), and what’s more, if you have a LaTeX
|
||
environment statement `\begin{...}' on its own line, Org will
|
||
recognise it and pass it into the generated LaTeX.
|
||
|
||
|
||
[very accomodating] <https://orgmode.org/manual/LaTeX-fragments.html>
|
||
|
||
|
||
Figures and tables
|
||
──────────────────
|
||
|
||
One area where the improvement when moving to Org is particularly
|
||
apparent is with figures and tables. To simply include an image, an
|
||
image link alone is sufficient.
|
||
┌────
|
||
│ [[file:figures/salvador-dali-persistence-of-memory.jpg]]
|
||
└────
|
||
When exported to LaTeX this will be expanded to
|
||
┌────
|
||
│ \includegraphics[width=.9\linewidth]{figures/salvador-dali-persistence-of-memory.jpg}
|
||
└────
|
||
|
||
As soon as you add a `#+caption', though, Org knows you mean business
|
||
and generates a /proper/ figure.
|
||
┌────
|
||
│ #+caption: A famous surrealist painting
|
||
│ [[file:figures/salvador-dali-persistence-of-memory.jpg]]
|
||
└────
|
||
┌────
|
||
│ \begin{figure}[htbp]
|
||
│ \centering
|
||
│ \includegraphics[width=.9\linewidth]{figures/salvador-dali-persistence-of-memory.jpg}
|
||
│ \caption{A famous surrealist painting}
|
||
│ \end{figure}
|
||
└────
|
||
|
||
As you may have guessed from the fact this works without a
|
||
LaTeX-specific keyword, this works nicely in HTML too 🙂.
|
||
<file:figures/salvador-dali-persistence-of-memory.jpg>
|
||
|
||
The LaTeX backend also accepts additional image attributes ([manual
|
||
page]). For example, to set the image width I can simply add
|
||
┌────
|
||
│ #+attr_latex: :width 0.4\linewidth
|
||
└────
|
||
above the image link.
|
||
|
||
You can do the same with tables:
|
||
┌────
|
||
│ #+caption: A selection of famous paintings by Salvador Dalí
|
||
│ | Year | Painting |
|
||
│ |------+----------------------------|
|
||
│ | 1931 | The persistence of memory |
|
||
│ | 1937 | Swans reflecting elephants |
|
||
│ | 1837 | Metamorphosis of narcissus |
|
||
│ | 1952 | Galatea of the spheres |
|
||
│ | 1966 | Tuna fishing |
|
||
└────
|
||
|
||
I like to set `(setq org-latex-tables-booktabs t)' to use the nice
|
||
`booktabs' rules in the generated tables. Just remember to ensure the
|
||
`booktabs' package is loaded.
|
||
|
||
┌────
|
||
│ \begin{table}[htbp]
|
||
│ \caption{A selection of famous paintings by Salvador Dalí}
|
||
│ \centering
|
||
│ \begin{tabular}{rl}
|
||
│ \toprule
|
||
│ Year & Painting\\
|
||
│ \midrule
|
||
│ 1931 & The persistence of memory\\
|
||
│ 1937 & Swans reflecting elephants\\
|
||
│ 1837 & Metamorphosis of narcissus\\
|
||
│ 1952 & Galatea of the spheres\\
|
||
│ 1966 & Tuna fishing\\
|
||
│ \bottomrule
|
||
│ \end{tabular}
|
||
│ \end{table}
|
||
└────
|
||
|
||
Org is nice and does the right thing^{TM} by including the caption at
|
||
the top.
|
||
<file:figures/org-table-to-latex-example.png>
|
||
|
||
There are also some [more attributes] you can supply to tables. Should
|
||
I want the table to spread out I could use `#+attr_latex: :environment
|
||
tabularx' (as long as I’ve loaded the `tabularx' package) and then set
|
||
the columns with `:align lX'.
|
||
|
||
|
||
[manual page] <https://orgmode.org/manual/Images-in-LaTeX-export.html>
|
||
|
||
[more attributes]
|
||
<https://orgmode.org/manual/Images-in-LaTeX-export.html>
|
||
|
||
|
||
Code blocks
|
||
───────────
|
||
|
||
By default, source code blocks are translated verbatim. We can do
|
||
better than that however. We can tell Org to use [listings], but I’d
|
||
recommend going one step further and using [minted]. For this to work
|
||
we need to perform three actions:
|
||
⁃ Tell Org we want to use `minted' environments for source code
|
||
⁃ Load the `minted' package by default
|
||
⁃ Add `-shell-escape' to our LaTeX compiler flags, so `minted' may
|
||
call [pygments].
|
||
|
||
This can easily be accomplished via the following snippet:
|
||
┌────
|
||
│ (setq org-latex-listings 'minted
|
||
│ ;; as long as you have latexmk installed
|
||
│ org-latex-pdf-process
|
||
│ '("latexmk -f -pdf -%latex -shell-escape -interaction=nonstopmode -output-directory=%o %f"))
|
||
│ (add-to-list 'org-latex-packages-alist '("" "minted"))
|
||
└────
|
||
|
||
To customise `minted', as well as inserting content into the
|
||
[preamble], one can also customise `org-latex-minted-options' to
|
||
control what options are applied to each `minted' environment.
|
||
|
||
|
||
[listings] <https://ctan.org/pkg/listings>
|
||
|
||
[minted] <https://ctan.org/pkg/minted>
|
||
|
||
[pygments] <https://pygments.org/>
|
||
|
||
[preamble] See section Preamble content
|
||
|
||
|
||
Custom environments
|
||
───────────────────
|
||
|
||
Org has a number of [blocks] which are treated specially, like
|
||
`#+begin_src' for source code, and `#+begin_centre' for centred text.
|
||
When exporting this same syntax allows you to wrap Org content in any
|
||
LaTeX environments (as long as it doesn’t match one of Org’s
|
||
recognised environments).
|
||
|
||
For example, if you wrote a `warning' environment in LaTeX to box and
|
||
emphasise text, to wrap some Org content in it one simply needs to
|
||
write:
|
||
┌────
|
||
│ #+begin_warning
|
||
│ Pay close attention! This is very important.
|
||
│ #+end_warning
|
||
└────
|
||
and the content will be wrapped in `\begin{warning} ...
|
||
\end{warning}'.
|
||
|
||
|
||
[blocks] <https://orgmode.org/manual/Blocks.html>
|
||
|
||
|
||
The LaTeX escape hatches
|
||
────────────────────────
|
||
|
||
Should there be a particular LaTeX command you wish to insert
|
||
somewhere, you simply need to put it on its own line with `#+latex:'
|
||
in front and it will be transferred to the generated LaTeX (this works
|
||
with other formats too).
|
||
┌────
|
||
│ #+latex: \newpage
|
||
└────
|
||
|
||
For larger snippets of LaTeX, there’s always the export block.
|
||
┌────
|
||
│ #+begin_export latex
|
||
│ \cleardoublepage
|
||
│ \vfil
|
||
│ \hfil This page is intentionally left blank \hfil
|
||
│ \vfil
|
||
│ \newpage
|
||
│ #+end_export
|
||
└────
|
||
|
||
|
||
Preamble content
|
||
────────────────
|
||
|
||
Should you wish to include the line in the preamble (before
|
||
`\begin{document}'), then all you need to do is use `#+latex_header:'.
|
||
┌────
|
||
│ #+latex_header: \newcommand{\RR}{\mathbb{R}}
|
||
│ #+latex_header: \usepackage{svg} % so that [[file:*.svg]] works nicely
|
||
└────
|
||
This is great for adding one-off `\usepackage' commands, but what if
|
||
you find yourself wanting a package (like [svg]) to be always
|
||
included? Well the we have the aforementioned
|
||
`org-latex-packages-alist' which will include the packages set when
|
||
exporting; you can even set some packages to only be included when
|
||
using a certain LaTeX compiler.
|
||
|
||
Should you want to use a certain preset preamble, you can make use of
|
||
the `#+latex_class' keyword. This is used to set the base preamble
|
||
template used when generating the LaTeX. See `org-latex-classes' for
|
||
what’s available by default. You should see entries for:
|
||
⁃ article
|
||
⁃ report
|
||
⁃ book
|
||
⁃ beamer
|
||
|
||
One of these is always used when generating LaTeX; when no
|
||
`#+latex_class' is set in the document, the template named by
|
||
`org-latex-default-class' will be used.
|
||
|
||
What’s great about this is that is makes it really easy to add your
|
||
own templates. Each template simply takes three components:
|
||
1. A name
|
||
2. A preamble template
|
||
3. A series of format strings to translate headings to LaTeX, with and
|
||
without numbering
|
||
|
||
For example, I’m quite a fan of the [KOMA-script] family. Should I
|
||
want to add a `kart' class (for: *k*oma *art*icle), I simply need to
|
||
do something like the following:
|
||
┌────
|
||
│ (add-to-list 'org-latex-classes
|
||
│ '("kart" ; class name
|
||
│ "\\documentclass{scrartcl}" ; preamble template
|
||
│ ("\\section{%s}" . "\\section*{%s}") ; H1 translation
|
||
│ ("\\subsection{%s}" . "\\subsection*{%s}") ; H2 translation
|
||
│ ("\\subsubsection{%s}" . "\\subsubsection*{%s}") ; H3...
|
||
│ ("\\paragraph{%s}" . "\\paragraph*{%s}")
|
||
│ ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))
|
||
└────
|
||
|
||
See the documentation for `org-latex-classes' for more information on
|
||
how the preamble template in handled.
|
||
|
||
|
||
[svg] <https://ctan.org/pkg/svg>
|
||
|
||
[KOMA-script] <https://ctan.org/pkg/koma-script>
|
||
|
||
|
||
Other improvements
|
||
══════════════════
|
||
|
||
⁃ `ox-koma-letter.el' has been brought into Org’s main directory from
|
||
the ) `contrib/' repo _Bastien Guerry_
|
||
⁃ Speed up publishing by using delayed hooks and temp buffers instead
|
||
of finding files _Gustav Wikström_
|
||
⁃ Improve generated HTML quality: prevent W3C warning and add some
|
||
accessibility labels _TEC_
|
||
⁃ Make the behaviour of the “goto variant” of `org-refile'
|
||
(`org-speed-commands') less confusing _Marco Wahl_
|
||
⁃ Backport an update to the OpenDocument schema _Kyle Meyer_
|
||
|
||
|
||
Bugfixes
|
||
════════
|
||
|
||
⁃ Off by one error in texinfo menu generation _Nicolas Goaziou_
|
||
⁃ Error in entry/conversion of non-24h times in the agenda _Nicolas
|
||
Goaziou_
|
||
⁃ Only use `replace-buffer-contents' with Emacs 27+ when saving src
|
||
blocks, as the behaviour isn’t consistent until then _Nicolas
|
||
Goaziou_
|
||
⁃ Prevent “before first headline” error in `org-clock' when clocking
|
||
out _Nicolas Goaziou_
|
||
⁃ Avoid setting the global agenda name when following a timestamp link
|
||
_Ingo Lohmar_
|
||
⁃ Don’t bind `<tab>' in `org-mode-map' _Nicolas Goaziou_
|
||
⁃ Erroneous tangling of source block with `:tangle no' to a file `no'
|
||
when the tangle command is called with a single universal argument
|
||
_Jacopo De Simoi_
|
||
|
||
|
||
|
||
Footnotes
|
||
─────────
|
||
|
||
[1] As has been the writing of this blog post 😜
|
||
|
||
[2] First-class support for citations is coming to Org! With support
|
||
for [CSL] (<https://citationstyles.org/>) and [BibTeX]
|
||
(<https://en.wikipedia.org/wiki/BibTeX>), with a number of citation
|
||
processors 🙌. Soon^{TM}
|
||
|
||
[3] I’m rather a fan of the `capitalize' option because (1)
|
||
technically the reference to a named object is a proper noun, and (2)
|
||
this means you don’t have to worry about references not being
|
||
capitalized when appearing at the start of a sentence.
|