273 lines
12 KiB
Org Mode
273 lines
12 KiB
Org Mode
# Created 2022-03-03 Thu 01:39
|
|
#+title: June 2021
|
|
#+date: 2021-06-34
|
|
#+author: TEC
|
|
#+subtitle: A relaxed month
|
|
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[fn: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[fn:2] is getting very close to merging 😀.
|
|
You'll just have to stick around to hear about those in a future edition of TMIO 😉.
|
|
|
|
#+caption: It's right around the corner, I swear!
|
|
[[file:figures/dilbert-zenos-paradox.jpg]]
|
|
|
|
[fn:1] As has been the writing of this blog post 😜
|
|
|
|
[fn:2] First-class support for citations is coming to Org! With support for [[https://citationstyles.org/][CSL]]
|
|
and [[https://en.wikipedia.org/wiki/BibTeX][BibTeX]], with a number of citation processors 🙌. Soon^{TM}
|
|
|
|
* 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.
|
|
|
|
#+caption: A LaTeX export of a simple document with a reference to both the first and second section.
|
|
#+caption: "2" what? Section 2, Table 2, Figure 2, ...
|
|
[[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 [[https://ctan.org/pkg/cleveref][cleveref]] package
|
|
I can set this to =\\cref{%s}= and then add src_elisp{("capitalize" "cleveref" nil)}[fn:3] to ~org-latex-packages-alist~.
|
|
|
|
#+caption: A LaTeX export of the same document, but now using ~cleveref~. Note the change from "1" and "2" to "Section 1" and "Section 2".
|
|
[[file:figures/org-latex-cref-reference-to-sec.png]]
|
|
|
|
[fn: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.
|
|
|
|
* A diversion into writing Org for LaTeX
|
|
|
|
Speaking of LaTeX exports, a member of the Org mailing list recently told us
|
|
about [[https://arxiv.org/abs/2106.05096][a paper]] pushed to [[https://arxiv.org/][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.
|
|
|
|
** 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 [[https://orgmode.org/manual/LaTeX-fragments.html][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.
|
|
|
|
** 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.
|
|
#+begin_src org
|
|
[[file:figures/salvador-dali-persistence-of-memory.jpg]]
|
|
#+end_src
|
|
When exported to LaTeX this will be expanded to
|
|
#+begin_src LaTeX
|
|
\includegraphics[width=.9\linewidth]{figures/salvador-dali-persistence-of-memory.jpg}
|
|
#+end_src
|
|
|
|
As soon as you add a =#+caption=, though, Org knows you mean business and
|
|
generates a /proper/ figure.
|
|
#+begin_src org
|
|
,#+caption: A famous surrealist painting
|
|
[[file:figures/salvador-dali-persistence-of-memory.jpg]]
|
|
#+end_src
|
|
#+begin_src LaTeX
|
|
\begin{figure}[htbp]
|
|
\centering
|
|
\includegraphics[width=.9\linewidth]{figures/salvador-dali-persistence-of-memory.jpg}
|
|
\caption{A famous surrealist painting}
|
|
\end{figure}
|
|
#+end_src
|
|
|
|
As you may have guessed from the fact this works without a LaTeX-specific
|
|
keyword, this works nicely in HTML too 🙂.
|
|
#+caption: A famous surrealist painting
|
|
[[file:figures/salvador-dali-persistence-of-memory.jpg]]
|
|
|
|
The LaTeX backend also accepts additional image attributes ([[https://orgmode.org/manual/Images-in-LaTeX-export.html][manual page]]). For
|
|
example, to set the image width I can simply add
|
|
#+begin_src org
|
|
,#+attr_latex: :width 0.4\linewidth
|
|
#+end_src
|
|
above the image link.
|
|
|
|
You can do the same with tables:
|
|
#+begin_src org
|
|
,#+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 |
|
|
#+end_src
|
|
|
|
I like to set src_elisp{(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_src LaTeX
|
|
\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}
|
|
#+end_src
|
|
|
|
Org is nice and does the right thing^{TM} by including the caption at the top.
|
|
#+caption: Look ma, I put the caption in the right place.
|
|
[[file:figures/org-table-to-latex-example.png]]
|
|
|
|
There are also some [[https://orgmode.org/manual/Images-in-LaTeX-export.html][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=.
|
|
|
|
** Code blocks
|
|
|
|
By default, source code blocks are translated verbatim. We can do better than
|
|
that however. We can tell Org to use [[https://ctan.org/pkg/listings][listings]], but I'd recommend going one step
|
|
further and using [[https://ctan.org/pkg/minted][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 [[https://pygments.org/][pygments]].
|
|
|
|
This can easily be accomplished via the following snippet:
|
|
#+begin_src emacs-lisp
|
|
(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"))
|
|
#+end_src
|
|
|
|
To customise =minted=, as well as inserting content into the [[Preamble content][preamble]], one can
|
|
also customise ~org-latex-minted-options~ to control what options are applied to
|
|
each =minted= environment.
|
|
|
|
** Custom environments
|
|
|
|
Org has a number of [[https://orgmode.org/manual/Blocks.html][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_src org
|
|
,#+begin_warning
|
|
Pay close attention! This is very important.
|
|
,#+end_warning
|
|
#+end_src
|
|
and the content will be wrapped in =\begin{warning} ... \end{warning}=.
|
|
|
|
** 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).
|
|
#+begin_src org
|
|
,#+latex: \newpage
|
|
#+end_src
|
|
|
|
For larger snippets of LaTeX, there's always the export block.
|
|
#+begin_src org
|
|
,#+begin_export latex
|
|
\cleardoublepage
|
|
\vfil
|
|
\hfil This page is intentionally left blank \hfil
|
|
\vfil
|
|
\newpage
|
|
,#+end_export
|
|
#+end_src
|
|
|
|
** 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:=.
|
|
#+begin_src org
|
|
,#+latex_header: \newcommand{\RR}{\mathbb{R}}
|
|
,#+latex_header: \usepackage{svg} % so that [[file:*.svg]] works nicely
|
|
#+end_src
|
|
This is great for adding one-off =\usepackage= commands, but what if you find
|
|
yourself wanting a package (like [[https://ctan.org/pkg/svg][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 [[https://ctan.org/pkg/koma-script][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:
|
|
#+begin_src emacs-lisp
|
|
(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}")))
|
|
#+end_src
|
|
|
|
See the documentation for ~org-latex-classes~ for more information on how the
|
|
preamble template in handled.
|
|
|
|
* 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_
|