Compare commits
No commits in common. "master" and "html" have entirely different histories.
|
|
@ -1,6 +0,0 @@
|
|||
*.org linguist-detectable=true
|
||||
assets/figures/*.png filter=lfs diff=lfs merge=lfs -text
|
||||
assets/figures/*.jpg filter=lfs diff=lfs merge=lfs -text
|
||||
assets/figures/*.gif filter=lfs diff=lfs merge=lfs -text
|
||||
assets/figures/*.svg filter=lfs diff=lfs merge=lfs -text
|
||||
assets/figures/*.mp4 filter=lfs diff=lfs merge=lfs -text
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
html/
|
||||
content/rss.org
|
||||
.orgids
|
||||
|
|
@ -0,0 +1,301 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-12 Fri 13:39 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>Welcome</title>
|
||||
<meta name="author" content="TEC" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="Welcome" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="TEC" />
|
||||
<meta property="og:article:published_time" content="2021-04-26T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2021-04-27T02:12:21+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2021-04-26, <span class='acr'>TEC</span></div>
|
||||
|
||||
<h1 class="title">Welcome</h1>
|
||||
</header><div id="outline-container-introduction" class="outline-2">
|
||||
<h2 id="introduction">Introduction<a aria-hidden="true" href="#introduction">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-introduction">
|
||||
<p>
|
||||
Org is an absolutely marvellous project. However, a quick glance at
|
||||
<a href="https://orgmode.org">https://orgmode.org</a> can lead one to think “so… it’s an Emacs version of
|
||||
Markdown? What’s the big deal?”. While it’s easy to understand how someone might
|
||||
think that at first, that impression misses two crucial points:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li>While for simple constructs (<b>bold</b>, <i>italic</i>, headlines, etc.) the syntax is very
|
||||
much analogous<sup><a id="fnr.1" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>, Org scales to much more powerful forms that are a
|
||||
headache to replicate in Markdown</li>
|
||||
<li>Org mode was developed in Emacs, for Emacs. The integrations for Org put <i>every
|
||||
other plaintext markup editing experience to shame</i>. <b>This is a bold statement</b>,
|
||||
and I stand by it.</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
This blog exists because of the second point. The world does not stand still,
|
||||
while new Markdown editors et al. are <a href="https://github.com/marktext/marktext">popping</a> <a href="https://github.com/ApostropheEditor/Apostrophe">up</a> <a href="https://remarkableapp.github.io/linux.html">left</a>, <a href="https://github.com/brrd/Abricotine">right</a>, <a href="https://github.com/DaveJarvis/keenwrite">and</a> <a href="https://znote.io/">centre</a> — Org
|
||||
has not languished. The <a href="https://orgmode.org/list/">mailing list</a> is active, as is development, and the
|
||||
number of things you can do with Org is only increasing.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
However, if one doesn’t want to receive tens to hundreds of emails a week, it
|
||||
can be all too easy to miss out on exciting developments<sup><a id="fnr.2" class="footref" href="#fn.2" role="doc-backlink">2</a></sup> 😢. So, to help keep
|
||||
you abreast of the latest in Org, I’m starting a blog ✨. Like all good things,
|
||||
it is <a href="https://github.com/tecosaur/this-month-in-org/">written entirely in Org</a>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Inspired by <a href="https://pointieststick.com/category/this-week-in-kde/">This Week in <span class='acr'>KDE</span></a> I’m thrilled to announce <i>This Month in Org</i> (we have
|
||||
slightly less going on than a Desktop Environment<sup><a id="fnr.3" class="footref" href="#fn.3" role="doc-backlink">3</a></sup>). Each month I shall
|
||||
endeavour to present the highlights of Org development.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Who knows, perhaps you might see something you’d like to help out with or
|
||||
suggest improvements too. We’d love you to <a href="https://orgmode.org/community.html">get in touch</a>.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-catching-up-lost" class="outline-2">
|
||||
<h2 id="catching-up-lost">Catching up on lost time — a year in review<a aria-hidden="true" href="#catching-up-lost">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-catching-up-lost">
|
||||
<p>
|
||||
I joined the Org mailing list in May last year, it’s almost been a year since
|
||||
then and we’ve seen the release of Org 9.4, and its inclusion in Emacs 27.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
I’m not going to do 12 months of work for just this one post, but I’d like to
|
||||
give you a sample of what’s changed over the last year.
|
||||
</p>
|
||||
</div>
|
||||
<div id="outline-container-new-discussion-tracker" class="outline-3">
|
||||
<h3 id="new-discussion-tracker">A new discussion tracker — <a href="https://updates.orgmode.org/">updates.orgmode.org</a><a aria-hidden="true" href="#new-discussion-tracker">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-new-discussion-tracker">
|
||||
<p>
|
||||
Mid last year Bastien rolled out tracker for
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li>Upcoming changes</li>
|
||||
<li>Help requests</li>
|
||||
<li>Bugs</li>
|
||||
<li>Patches</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
This should help ensure nothing slips through the cracks of the <span class='acr'>ML</span>.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org03d28e5">
|
||||
<img src="figures/screenshot-of-updates-orgmode-org.png" alt="screenshot-of-updates-orgmode-org.png" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 1: </span>A screenshot of <a href="https://updates.orgmode.org/">updates.orgmode.org</a></figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
It’s very slick, and Bastien built a <a href="https://github.com/bzg/woof">mailbox monitor</a> just for it — so be sure
|
||||
to check it out. This should make it easier to see what needs doing. If you feel
|
||||
inclined to help out with Org check out the <i>Help requests</i> section in particular.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
You can also get <span class='acr'>RSS</span> feeds for individual sections, or get the information as
|
||||
<span class='acr'>JSON</span> to work into your own projects, for example <a href="https://tecosaur.github.io/emacs-config/config.html#development">an elisp function to fetch and
|
||||
apply patches</a>.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-inline-display-remote" class="outline-3">
|
||||
<h3 id="inline-display-remote">Inline display of remote images<a aria-hidden="true" href="#inline-display-remote">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-inline-display-remote">
|
||||
<p>
|
||||
Ever gazed forlornly at a link like
|
||||
<kbd>[[https://github.com/larsmagne/meme/raw/master/images/Grandma-Finds-The-Internet.jpg]]</kbd>
|
||||
wishing you could see the image?
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Wish no more! Thanks to Jack Kamm you can now look upon remote images in all
|
||||
their glory!
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org97973a6">
|
||||
<img src="https://github.com/larsmagne/meme/raw/master/images/Grandma-Finds-The-Internet.jpg" alt="Grandma-Finds-The-Internet.jpg" style="height:16em">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 2: </span>Org mode discovers the internet</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
To get this working, simply set <code class="src src-elisp">org-display-remote-inline-images</code> to
|
||||
<code class="src src-elisp">'download</code> or <code class="src src-elisp">'cache</code>.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-use-org-edit" class="outline-3">
|
||||
<h3 id="use-org-edit">Use <code>org-edit-special</code> (<kbd>C-c '</kbd>) with LaTeX fragments<a aria-hidden="true" href="#use-org-edit">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-use-org-edit">
|
||||
<p>
|
||||
It’s great how in Org you can jump into a LaTeX-mode minibuffer for LaTeX
|
||||
environments, but why leave inline LaTeX fragments out? We’ll, they’re now in.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org056ad3d">
|
||||
<img src="figures/org-edit-special-latex-fragment.png" alt="org-edit-special-latex-fragment.png" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 3: </span>Running <code>org-edit-special</code> on an inline LaTeX fragment</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-control-heading-display" class="outline-3">
|
||||
<h3 id="control-heading-display">Control heading display on startup<a aria-hidden="true" href="#control-heading-display">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-control-heading-display">
|
||||
<p>
|
||||
<kbd>org-num-mode</kbd> is great for when you’re keeping an eye on section numbers, but
|
||||
it’s not fun to find yourself enabling it every time you open a file where you
|
||||
want it. With the new option <kbd>#+startup: num</kbd> by Bastien, you can set and forget
|
||||
at last.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="orgcb68ae3">
|
||||
<img src="figures/org-startup-num-and-levels.png" alt="org-startup-num-and-levels.png" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 4: </span>Opening a buffer with the new <kbd>num</kbd> and <kbd>show2levels</kbd> startup options</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
Should you want to set the number of levels you see on opening a file, there’s
|
||||
now an option for that too. Gustav Wikström has added <i>another</i> new option
|
||||
<kbd>#+startup: show<n>levels</kbd> (where <kbd><n></kbd> is between 2 and 5, inclusive).
|
||||
<i><span class='acr'>NB</span>: This is part of the upcoming 9.5 release</i>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-set-permissions-tangled" class="outline-3">
|
||||
<h3 id="set-permissions-tangled">Set permissions of tangled files<a aria-hidden="true" href="#set-permissions-tangled">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-set-permissions-tangled">
|
||||
<p>
|
||||
Are you particular about your file permissions? If so you’ll likely like John
|
||||
Herrlin’s new source block header argument <kbd>:file-mode</kbd> pertinent. The easiest way
|
||||
to set a permission is with an <a href="https://docs.nersc.gov/filesystems/unix-file-permissions/">octal value</a>, like so:
|
||||
</p>
|
||||
<details id='set-permissions-tangled,code--1' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#set-permissions-tangled,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-block-begin-line">#+begin_src shell :results file :file script.sh :file-mode (identity #o755)</span>
|
||||
<span class="org-org-block"><span class="org-builtin">echo</span></span><span class="org-org-block"> </span><span class="org-org-block"><span class="org-string">"#!/bin/bash"</span></span>
|
||||
<span class="org-org-block"><span class="org-builtin">echo</span></span><span class="org-org-block"> </span><span class="org-org-block"><span class="org-string">"echo Hello World"</span></span>
|
||||
<span class="org-org-block-end-line">#+end_src</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-collection-improvements-source" class="outline-3">
|
||||
<h3 id="collection-improvements-source">A collection of improvements to source block header arguments<a aria-hidden="true" href="#collection-improvements-source">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-collection-improvements-source">
|
||||
<p>
|
||||
These’s been a whole set of these, so I’ll just list them off.
|
||||
</p>
|
||||
<dl class="org-dl">
|
||||
<dt>python, improved <kbd>:return</kbd></dt><dd>Now works with sessions and the <kbd>:epilogue</kbd>
|
||||
argument (Jack Kamm)</dd>
|
||||
<dt>Java, new argument <kbd>:cmdargs</kbd></dt><dd>Add some command line arguments to be passed to
|
||||
<code>java</code> (Jarmo Hurri)</dd>
|
||||
<dt>C/C++, non-system headers with <kbd>:includes</kbd></dt><dd>values that don’t start with <kbd><</kbd>
|
||||
will now be formatted as double-quoted <code class="src src-C"><span class="org-preprocessor">#include</span></code> statements (Brandon
|
||||
Guttersohn)</dd>
|
||||
<dt>Screen, new argument <kbd>:screenrc</kbd></dt><dd>For those of you who still haven’t moved to
|
||||
<kbd>tmux</kbd> (Kenneth D. Mankoff)</dd>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-seven-year-old" class="outline-3">
|
||||
<h3 id="seven-year-old">A seven year old bug was fixed<a aria-hidden="true" href="#seven-year-old">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-seven-year-old">
|
||||
<p>
|
||||
In 2013 <a href="https://lists.gnu.org/archive/html/emacs-orgmode/2013-08/msg00072.html">it was reported</a> that an infinite loop could be triggered in
|
||||
<code>org-agenda-show-new-time</code>. At long last, this has been fixed by Bastien.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="footnotes">
|
||||
<h2 class="footnotes">Footnotes: </h2>
|
||||
<div id="text-footnotes">
|
||||
|
||||
<div class="footdef"><sup><a id="fn.1" class="footnum" href="#fnr.1" role="doc-backlink">1</a></sup> <div class="footpara" role="doc-footnote"><p class="footpara">
|
||||
Aside from somewhat more <a href="https://orgmode.org/quickstart.html">intuitive syntax</a> for emphasis and simple
|
||||
structures, Org also has the advantage of not having <a href="https://github.com/commonmark/commonmark-spec/wiki/markdown-flavors">40 functionally distinct
|
||||
specifications</a>. There is only one Org. <br>
|
||||
<span class='acr'>NB</span>: If you attempt to be pedantic you may say that there are multiple Orgs
|
||||
because, for example, GitHub uses <a href="https://github.com/wallyqs/org-ruby">org-ruby</a>. However, that’s just an incomplete
|
||||
implementation — not a <a href="https://orgmode.org/worg/dev/org-syntax.html">specification</a>.
|
||||
</p></div></div>
|
||||
|
||||
<div class="footdef"><sup><a id="fn.2" class="footnum" href="#fnr.2" role="doc-backlink">2</a></sup> <div class="footpara" role="doc-footnote"><p class="footpara">
|
||||
There is <a href="https://code.orgmode.org/bzg/org-mode/src/master/etc/ORG-NEWS"><span class='acr'>ORG</span>-<span class='acr'>NEWS</span></a>, but do you <i>really</i> check that? Besides, it doesn’t even
|
||||
have pictures.
|
||||
</p></div></div>
|
||||
|
||||
<div class="footdef"><sup><a id="fn.3" class="footnum" href="#fnr.3" role="doc-backlink">3</a></sup> <div class="footpara" role="doc-footnote"><p class="footpara">
|
||||
That said, with <i>interesting</i> projects like the <a href="https://github.com/manateelazycat/emacs-application-framework">Emacs Application
|
||||
Framework</a> and the <a href="https://github.com/ch11ng/exwm">Emacs X Window Manager</a>, one could argue that Org is
|
||||
(sometimes) a major component of a desktop environment…
|
||||
</p></div></div>
|
||||
|
||||
|
||||
</div>
|
||||
</div></div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,17 +1,17 @@
|
|||
# Created 2024-01-12 Fri 13:39
|
||||
#+title: Welcome
|
||||
#+author: TEC
|
||||
#+date: 2021-04-26
|
||||
|
||||
#+author: TEC
|
||||
* Introduction
|
||||
|
||||
Org is an absolutely marvellous project. However, a quick glance at
|
||||
https://orgmode.org can lead one to think "so... it's an Emacs version of
|
||||
Markdown? What's the big deal?". While it's easy to understand how someone might
|
||||
think that at first, that impression misses two crucial points:
|
||||
+ While for simple constructs (*bold*, /italic/, headlines, etc.) the syntax is very
|
||||
- While for simple constructs (*bold*, /italic/, headlines, etc.) the syntax is very
|
||||
much analogous[fn:1], Org scales to much more powerful forms that are a
|
||||
headache to replicate in Markdown
|
||||
+ Org mode was developed in Emacs, for Emacs. The integrations for Org put /every
|
||||
- Org mode was developed in Emacs, for Emacs. The integrations for Org put /every
|
||||
other plaintext markup editing experience to shame/. *This is a bold statement*,
|
||||
and I stand by it.
|
||||
|
||||
|
|
@ -32,6 +32,19 @@ endeavour to present the highlights of Org development.
|
|||
Who knows, perhaps you might see something you'd like to help out with or
|
||||
suggest improvements too. We'd love you to [[https://orgmode.org/community.html][get in touch]].
|
||||
|
||||
[fn:1] Aside from somewhat more [[https://orgmode.org/quickstart.html][intuitive syntax]] for emphasis and simple
|
||||
structures, Org also has the advantage of not having [[https://github.com/commonmark/commonmark-spec/wiki/markdown-flavors][40 functionally distinct
|
||||
specifications]]. There is only one Org. \\
|
||||
NB: If you attempt to be pedantic you may say that there are multiple Orgs
|
||||
because, for example, GitHub uses [[https://github.com/wallyqs/org-ruby][org-ruby]]. However, that's just an incomplete
|
||||
implementation --- not a [[https://orgmode.org/worg/dev/org-syntax.html][specification]].
|
||||
|
||||
[fn:3] There is [[https://code.orgmode.org/bzg/org-mode/src/master/etc/ORG-NEWS][ORG-NEWS]], but do you /really/ check that? Besides, it doesn't even
|
||||
have pictures.
|
||||
|
||||
[fn:2] That said, with /interesting/ projects like the [[https://github.com/manateelazycat/emacs-application-framework][Emacs Application
|
||||
Framework]] and the [[https://github.com/ch11ng/exwm][Emacs X Window Manager]], one could argue that Org is
|
||||
(sometimes) a major component of a desktop environment...
|
||||
* Catching up on lost time --- a year in review
|
||||
|
||||
I joined the Org mailing list in May last year, it's almost been a year since
|
||||
|
|
@ -39,19 +52,17 @@ then and we've seen the release of Org 9.4, and its inclusion in Emacs 27.
|
|||
|
||||
I'm not going to do 12 months of work for just this one post, but I'd like to
|
||||
give you a sample of what's changed over the last year.
|
||||
|
||||
** A new discussion tracker --- [[https://updates.orgmode.org/][updates.orgmode.org]]
|
||||
|
||||
Mid last year Bastien rolled out tracker for
|
||||
+ Upcoming changes
|
||||
+ Help requests
|
||||
+ Bugs
|
||||
+ Patches
|
||||
- Upcoming changes
|
||||
- Help requests
|
||||
- Bugs
|
||||
- Patches
|
||||
|
||||
This should help ensure nothing slips through the cracks of the ML.
|
||||
|
||||
#+caption: A screenshot of [[https://updates.orgmode.org/][updates.orgmode.org]]
|
||||
#+attr_html: :class invertible
|
||||
[[file:figures/screenshot-of-updates-orgmode-org.png]]
|
||||
|
||||
It's very slick, and Bastien built a [[https://github.com/bzg/woof][mailbox monitor]] just for it --- so be sure
|
||||
|
|
@ -61,7 +72,6 @@ inclined to help out with Org check out the /Help requests/ section in particula
|
|||
You can also get RSS feeds for individual sections, or get the information as
|
||||
JSON to work into your own projects, for example [[https://tecosaur.github.io/emacs-config/config.html#development][an elisp function to fetch and
|
||||
apply patches]].
|
||||
|
||||
** Inline display of remote images
|
||||
|
||||
Ever gazed forlornly at a link like
|
||||
|
|
@ -72,22 +82,17 @@ Wish no more! Thanks to Jack Kamm you can now look upon remote images in all
|
|||
their glory!
|
||||
|
||||
#+caption: Org mode discovers the internet
|
||||
#+attr_html: :style height:16em
|
||||
#+attr_latex: :width 0.4\linewidth
|
||||
[[https://github.com/larsmagne/meme/raw/master/images/Grandma-Finds-The-Internet.jpg]]
|
||||
|
||||
To get this working, simply set src_elisp{org-display-remote-inline-images} to
|
||||
src_elisp{'download} or src_elisp{'cache}.
|
||||
|
||||
** Use ~org-edit-special~ (=C-c '=) with LaTeX fragments
|
||||
|
||||
It's great how in Org you can jump into a LaTeX-mode minibuffer for LaTeX
|
||||
environments, but why leave inline LaTeX fragments out? We'll, they're now in.
|
||||
|
||||
#+caption: Running ~org-edit-special~ on an inline LaTeX fragment
|
||||
#+attr_html: :class invertible
|
||||
[[file:figures/org-edit-special-latex-fragment.png]]
|
||||
|
||||
** Control heading display on startup
|
||||
|
||||
=org-num-mode= is great for when you're keeping an eye on section numbers, but
|
||||
|
|
@ -96,56 +101,36 @@ want it. With the new option =#+startup: num= by Bastien, you can set and forget
|
|||
at last.
|
||||
|
||||
#+caption: Opening a buffer with the new =num= and =show2levels= startup options
|
||||
#+attr_html: :class invertible
|
||||
[[file:figures/org-startup-num-and-levels.png]]
|
||||
|
||||
Should you want to set the number of levels you see on opening a file, there's
|
||||
now an option for that too. Gustav Wikström has added /another/ new option
|
||||
=#+startup: show<n>levels= (where =<n>= is between 2 and 5, inclusive).
|
||||
/NB: This is part of the upcoming 9.5 release/
|
||||
|
||||
** Set permissions of tangled files
|
||||
|
||||
Are you particular about your file permissions? If so you'll likely like John
|
||||
Herrlin's new source block header argument =:file-mode= pertinent. The easiest way
|
||||
to set a permission is with an [[https://docs.nersc.gov/filesystems/unix-file-permissions/][octal value]], like so:
|
||||
#+begin_src org
|
||||
,#+begin_src shell :results file :file script.sh :file-mode (identity #o755)
|
||||
echo "#!/bin/bash"
|
||||
echo "echo Hello World"
|
||||
,#+end_src
|
||||
,#+begin_src shell :results file :file script.sh :file-mode (identity #o755)
|
||||
echo "#!/bin/bash"
|
||||
echo "echo Hello World"
|
||||
,#+end_src
|
||||
#+end_src
|
||||
|
||||
** A collection of improvements to source block header arguments
|
||||
|
||||
These's been a whole set of these, so I'll just list them off.
|
||||
+ python, improved =:return= :: Now works with sessions and the =:epilogue=
|
||||
argument (Jack Kamm)
|
||||
+ Java, new argument =:cmdargs= :: Add some command line arguments to be passed to
|
||||
~java~ (Jarmo Hurri)
|
||||
+ C/C++, non-system headers with =:includes= :: values that don't start with =<=
|
||||
will now be formatted as double-quoted src_C{#include} statements (Brandon
|
||||
Guttersohn)
|
||||
+ Screen, new argument =:screenrc= :: For those of you who still haven't moved to
|
||||
=tmux= (Kenneth D. Mankoff)
|
||||
|
||||
- python, improved =:return= :: Now works with sessions and the =:epilogue=
|
||||
argument (Jack Kamm)
|
||||
- Java, new argument =:cmdargs= :: Add some command line arguments to be passed to
|
||||
~java~ (Jarmo Hurri)
|
||||
- C/C++, non-system headers with =:includes= :: values that don't start with =<=
|
||||
will now be formatted as double-quoted src_C{#include} statements (Brandon
|
||||
Guttersohn)
|
||||
- Screen, new argument =:screenrc= :: For those of you who still haven't moved to
|
||||
=tmux= (Kenneth D. Mankoff)
|
||||
** A seven year old bug was fixed
|
||||
|
||||
In 2013 [[https://lists.gnu.org/archive/html/emacs-orgmode/2013-08/msg00072.html][it was reported]] that an infinite loop could be triggered in
|
||||
~org-agenda-show-new-time~. At long last, this has been fixed by Bastien.
|
||||
|
||||
* Footnotes
|
||||
|
||||
[fn:1] Aside from somewhat more [[https://orgmode.org/quickstart.html][intuitive syntax]] for emphasis and simple
|
||||
structures, Org also has the advantage of not having [[https://github.com/commonmark/commonmark-spec/wiki/markdown-flavors][40 functionally distinct
|
||||
specifications]]. There is only one Org. \\
|
||||
NB: If you attempt to be pedantic you may say that there are multiple Orgs
|
||||
because, for example, GitHub uses [[https://github.com/wallyqs/org-ruby][org-ruby]]. However, that's just an incomplete
|
||||
implementation --- not a [[https://orgmode.org/worg/dev/org-syntax.html][specification]].
|
||||
|
||||
[fn:2] That said, with /interesting/ projects like the [[https://github.com/manateelazycat/emacs-application-framework][Emacs Application
|
||||
Framework]] and the [[https://github.com/ch11ng/exwm][Emacs X Window Manager]], one could argue that Org is
|
||||
(sometimes) a major component of a desktop environment...
|
||||
|
||||
[fn:3] There is [[https://code.orgmode.org/bzg/org-mode/src/master/etc/ORG-NEWS][ORG-NEWS]], but do you /really/ check that? Besides, it doesn't even
|
||||
have pictures.
|
||||
|
|
@ -0,0 +1,272 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>2021-04-26-Welcome.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">Welcome
|
||||
</span><span style="color: #9e9e9e;">#+author:</span> TEC
|
||||
<span style="color: #9e9e9e;">#+date:</span> 2021-04-26
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Introduction</span>
|
||||
|
||||
Org is an absolutely marvellous project. However, a quick glance at
|
||||
<span style="color: #3b6ea8; font-weight: 700;">https://orgmode.org</span> can lead one to think "so... it's an Emacs version of
|
||||
Markdown? What's the big deal?". While it's easy to understand how someone might
|
||||
think that at first, that impression misses two crucial points:
|
||||
+ While for simple constructs (<span class="ef-b">*bold*</span>, <span class="ef-i">/italic/</span>, headlines, etc.) the syntax is very
|
||||
much analogous[fn:1], Org scales to much more powerful forms that are a
|
||||
headache to replicate in Markdown
|
||||
+ Org mode was developed in Emacs, for Emacs. The integrations for Org put <span class="ef-i">/every
|
||||
other plaintext markup editing experience to shame/</span>. <span class="ef-b">*This is a bold statement*</span>,
|
||||
and I stand by it.
|
||||
|
||||
This blog exists because of the second point. The world does not stand still,
|
||||
while new Markdown editors et al. are <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/marktext/marktext][popping]]</span> <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/ApostropheEditor/Apostrophe][up]]</span> <span style="color: #3b6ea8; font-weight: 700;">[[https://remarkableapp.github.io/linux.html][left]]</span>, <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/brrd/Abricotine][right]]</span>, <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/DaveJarvis/keenwrite][and]]</span> <span style="color: #3b6ea8; font-weight: 700;">[[https://znote.io/][centre]]</span> --- Org
|
||||
has not languished. The <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/list/][mailing list]]</span> is active, as is development, and the
|
||||
number of things you can do with Org is only increasing.
|
||||
|
||||
However, if one doesn't want to receive tens to hundreds of emails a week, it
|
||||
can be all too easy to miss out on exciting developments[fn:3] 😢. So, to help keep
|
||||
you abreast of the latest in Org, I'm starting a blog ✨. Like all good things,
|
||||
it is <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/tecosaur/this-month-in-org/][written entirely in Org]]</span>.
|
||||
|
||||
Inspired by <span style="color: #3b6ea8; font-weight: 700;">[[https://pointieststick.com/category/this-week-in-kde/][This Week in KDE]]</span> I'm thrilled to announce <span class="ef-i">/This Month in Org/</span> (we have
|
||||
slightly less going on than a Desktop Environment[fn:2]). Each month I shall
|
||||
endeavour to present the highlights of Org development.
|
||||
|
||||
Who knows, perhaps you might see something you'd like to help out with or
|
||||
suggest improvements too. We'd love you to <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/community.html][get in touch]]</span>.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Catching up on lost time --- a year in review</span>
|
||||
|
||||
I joined the Org mailing list in May last year, it's almost been a year since
|
||||
then and we've seen the release of Org 9.4, and its inclusion in Emacs 27.
|
||||
|
||||
I'm not going to do 12 months of work for just this one post, but I'd like to
|
||||
give you a sample of what's changed over the last year.
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** A new discussion tracker --- </span><span style="color: #3b6ea8; font-weight: 700; font-size: 1.15em">[[https://updates.orgmode.org/][</span><span style="color: #3b6ea8; font-weight: 700; font-size: 1.15em">updates.orgmode.org</span><span style="color: #3b6ea8; font-weight: 700; font-size: 1.15em">]</span><span style="color: #3b6ea8; font-weight: 700; font-size: 1.15em">]</span>
|
||||
|
||||
Mid last year Bastien rolled out tracker for
|
||||
+ Upcoming changes
|
||||
+ Help requests
|
||||
+ Bugs
|
||||
+ Patches
|
||||
|
||||
This should help ensure nothing slips through the cracks of the ML.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">A screenshot of [[https://updates.orgmode.org/][updates.orgmode.org]]</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/screenshot-of-updates-orgmode-org.png]]</span>
|
||||
|
||||
It's very slick, and Bastien built a <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/bzg/woof][mailbox monitor]]</span> just for it --- so be sure
|
||||
to check it out. This should make it easier to see what needs doing. If you feel
|
||||
inclined to help out with Org check out the <span class="ef-i">/Help requests/</span> section in particular.
|
||||
|
||||
You can also get RSS feeds for individual sections, or get the information as
|
||||
JSON to work into your own projects, for example <span style="color: #3b6ea8; font-weight: 700;">[[https://tecosaur.github.io/emacs-config/config.html#development][an elisp function to fetch and
|
||||
apply patches]]</span>.
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Inline display of remote images</span>
|
||||
|
||||
Ever gazed forlornly at a link like
|
||||
<span style="color: #9e9e9e;">=</span><span style="color: #9e9e9e; font-weight: 700;">[[https://github.com/larsmagne/meme/raw/master/images/Grandma-Finds-The-Internet.jpg]]</span><span style="color: #9e9e9e;">=</span>
|
||||
wishing you could see the image?
|
||||
|
||||
Wish no more! Thanks to Jack Kamm you can now look upon remote images in all
|
||||
their glory!
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Org mode discovers the internet</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :style height:16em</span>
|
||||
<span style="color: #b1b1b1;">#+attr_latex: :width 0.4\linewidth</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/larsmagne/meme/raw/master/images/Grandma-Finds-The-Internet.jpg]]</span>
|
||||
|
||||
To get this working, simply set <span style="color: #9e9e9e; background-color: #e0e0e0;">src_</span><span style="color: #b1b1b1; background-color: #e0e0e0;">elisp</span><span style="color: #9e9e9e; background-color: #e0e0e0;">{</span><span class="ef-ob">org-display-remote-inline-images</span><span style="color: #9e9e9e; background-color: #e0e0e0;">}</span> to
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">src_</span><span style="color: #b1b1b1; background-color: #e0e0e0;">elisp</span><span style="color: #9e9e9e; background-color: #e0e0e0;">{</span><span class="ef-ob">'download</span><span style="color: #9e9e9e; background-color: #e0e0e0;">}</span> or <span style="color: #9e9e9e; background-color: #e0e0e0;">src_</span><span style="color: #b1b1b1; background-color: #e0e0e0;">elisp</span><span style="color: #9e9e9e; background-color: #e0e0e0;">{</span><span class="ef-ob">'cache</span><span style="color: #9e9e9e; background-color: #e0e0e0;">}</span>.
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Use </span><span style="color: #9e9e9e; font-weight: 700; font-size: 1.15em">~org-edit-special~</span><span style="color: #97365b; font-weight: 700; font-size: 1.15em"> (</span><span style="color: #9e9e9e; font-weight: 700; font-size: 1.15em">=C-c '=</span><span style="color: #97365b; font-weight: 700; font-size: 1.15em">) with LaTeX fragments</span>
|
||||
|
||||
It's great how in Org you can jump into a LaTeX-mode minibuffer for LaTeX
|
||||
environments, but why leave inline LaTeX fragments out? We'll, they're now in.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Running ~org-edit-special~ on an inline LaTeX fragment</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/org-edit-special-latex-fragment.png]]</span>
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Control heading display on startup</span>
|
||||
|
||||
<span style="color: #9e9e9e;">=org-num-mode=</span> is great for when you're keeping an eye on section numbers, but
|
||||
it's not fun to find yourself enabling it every time you open a file where you
|
||||
want it. With the new option <span style="color: #9e9e9e;">=#+startup: num=</span> by Bastien, you can set and forget
|
||||
at last.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Opening a buffer with the new =num= and =show2levels= startup options</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/org-startup-num-and-levels.png]]</span>
|
||||
|
||||
Should you want to set the number of levels you see on opening a file, there's
|
||||
now an option for that too. Gustav Wikström has added <span class="ef-i">/another/</span> new option
|
||||
<span style="color: #9e9e9e;">=#+startup: show<n>levels=</span> (where <span style="color: #9e9e9e;">=<n>=</span> is between 2 and 5, inclusive).
|
||||
<span class="ef-i">/NB: This is part of the upcoming 9.5 release/</span>
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Set permissions of tangled files</span>
|
||||
|
||||
Are you particular about your file permissions? If so you'll likely like John
|
||||
Herrlin's new source block header argument <span style="color: #9e9e9e;">=:file-mode=</span> pertinent. The easiest way
|
||||
to set a permission is with an <span style="color: #3b6ea8; font-weight: 700;">[[https://docs.nersc.gov/filesystems/unix-file-permissions/][octal value]]</span>, like so:
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+begin_src shell :results file :file script.sh :file-mode (identity #o755)
|
||||
echo "#!/bin/bash"
|
||||
echo "echo Hello World"
|
||||
,#+end_src
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** A collection of improvements to source block header arguments</span>
|
||||
|
||||
These's been a whole set of these, so I'll just list them off.
|
||||
+ <span style="font-weight: 700;">python, improved </span><span style="color: #9e9e9e; font-weight: 700;">=:return=</span><span style="font-weight: 700;"> ::</span> Now works with sessions and the <span style="color: #9e9e9e;">=:epilogue=</span>
|
||||
argument (Jack Kamm)
|
||||
+ <span style="font-weight: 700;">Java, new argument </span><span style="color: #9e9e9e; font-weight: 700;">=:cmdargs=</span><span style="font-weight: 700;"> ::</span> Add some command line arguments to be passed to
|
||||
<span style="color: #9e9e9e;">~java~</span> (Jarmo Hurri)
|
||||
+ <span style="font-weight: 700;">C/C++, non-system headers with </span><span style="color: #9e9e9e; font-weight: 700;">=:includes=</span><span style="font-weight: 700;"> ::</span> values that don't start with <span style="color: #9e9e9e;">=<=</span>
|
||||
will now be formatted as double-quoted <span style="color: #9e9e9e; background-color: #e0e0e0;">src_</span><span style="color: #b1b1b1; background-color: #e0e0e0;">C</span><span style="color: #9e9e9e; background-color: #e0e0e0;">{</span><span style="color: #3b6ea8; background-color: #e0e0e0; font-weight: 700;">#include</span><span style="color: #9e9e9e; background-color: #e0e0e0;">}</span> statements (Brandon
|
||||
Guttersohn)
|
||||
+ <span style="font-weight: 700;">Screen, new argument </span><span style="color: #9e9e9e; font-weight: 700;">=:screenrc=</span><span style="font-weight: 700;"> ::</span> For those of you who still haven't moved to
|
||||
<span style="color: #9e9e9e;">=tmux=</span> (Kenneth D. Mankoff)
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** A seven year old bug was fixed</span>
|
||||
|
||||
In 2013 <span style="color: #3b6ea8; font-weight: 700;">[[https://lists.gnu.org/archive/html/emacs-orgmode/2013-08/msg00072.html][it was reported]]</span> that an infinite loop could be triggered in
|
||||
<span style="color: #9e9e9e;">~org-agenda-show-new-time~</span>. At long last, this has been fixed by Bastien.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Footnotes</span>
|
||||
|
||||
[fn:1] Aside from somewhat more <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/quickstart.html][intuitive syntax]]</span> for emphasis and simple
|
||||
structures, Org also has the advantage of not having <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/commonmark/commonmark-spec/wiki/markdown-flavors][40 functionally distinct
|
||||
specifications]]</span>. There is only one Org. \\
|
||||
NB: If you attempt to be pedantic you may say that there are multiple Orgs
|
||||
because, for example, GitHub uses <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/wallyqs/org-ruby][org-ruby]]</span>. However, that's just an incomplete
|
||||
implementation --- not a <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/worg/dev/org-syntax.html][specification]]</span>.
|
||||
|
||||
[fn:2] That said, with <span class="ef-i">/interesting/</span> projects like the <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/manateelazycat/emacs-application-framework][Emacs Application
|
||||
Framework]]</span> and the <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/ch11ng/exwm][Emacs X Window Manager]]</span>, one could argue that Org is
|
||||
(sometimes) a major component of a desktop environment...
|
||||
|
||||
[fn:3] There is <span style="color: #3b6ea8; font-weight: 700;">[[https://code.orgmode.org/bzg/org-mode/src/master/etc/ORG-NEWS][ORG-NEWS]]</span>, but do you <span class="ef-i">/really/</span> check that? Besides, it doesn't even
|
||||
have pictures.
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,227 @@
|
|||
━━━━━━━━━
|
||||
WELCOME
|
||||
|
||||
TEC
|
||||
━━━━━━━━━
|
||||
|
||||
|
||||
2021-04-26
|
||||
|
||||
|
||||
Introduction
|
||||
════════════
|
||||
|
||||
Org is an absolutely marvellous project. However, a quick glance at
|
||||
<https://orgmode.org> can lead one to think “so… it’s an Emacs version
|
||||
of Markdown? What’s the big deal?”. While it’s easy to understand how
|
||||
someone might think that at first, that impression misses two crucial
|
||||
points:
|
||||
⁃ While for simple constructs (*bold*, /italic/, headlines, etc.) the
|
||||
syntax is very much analogous[1], Org scales to much more powerful
|
||||
forms that are a headache to replicate in Markdown
|
||||
⁃ Org mode was developed in Emacs, for Emacs. The integrations for Org
|
||||
put /every other plaintext markup editing experience to
|
||||
shame/. *This is a bold statement*, and I stand by it.
|
||||
|
||||
This blog exists because of the second point. The world does not stand
|
||||
still, while new Markdown editors et al. are [popping] [up] [left],
|
||||
[right], [and] [centre] — Org has not languished. The [mailing list]
|
||||
is active, as is development, and the number of things you can do with
|
||||
Org is only increasing.
|
||||
|
||||
However, if one doesn’t want to receive tens to hundreds of emails a
|
||||
week, it can be all too easy to miss out on exciting developments[2]
|
||||
😢. So, to help keep you abreast of the latest in Org, I’m starting a
|
||||
blog ✨. Like all good things, it is [written entirely in Org].
|
||||
|
||||
Inspired by [This Week in KDE] I’m thrilled to announce /This Month in
|
||||
Org/ (we have slightly less going on than a Desktop
|
||||
Environment[3]). Each month I shall endeavour to present the
|
||||
highlights of Org development.
|
||||
|
||||
Who knows, perhaps you might see something you’d like to help out with
|
||||
or suggest improvements too. We’d love you to [get in touch].
|
||||
|
||||
|
||||
[popping] <https://github.com/marktext/marktext>
|
||||
|
||||
[up] <https://github.com/ApostropheEditor/Apostrophe>
|
||||
|
||||
[left] <https://remarkableapp.github.io/linux.html>
|
||||
|
||||
[right] <https://github.com/brrd/Abricotine>
|
||||
|
||||
[and] <https://github.com/DaveJarvis/keenwrite>
|
||||
|
||||
[centre] <https://znote.io/>
|
||||
|
||||
[mailing list] <https://orgmode.org/list/>
|
||||
|
||||
[written entirely in Org]
|
||||
<https://github.com/tecosaur/this-month-in-org/>
|
||||
|
||||
[This Week in KDE]
|
||||
<https://pointieststick.com/category/this-week-in-kde/>
|
||||
|
||||
[get in touch] <https://orgmode.org/community.html>
|
||||
|
||||
|
||||
Catching up on lost time — a year in review
|
||||
═══════════════════════════════════════════
|
||||
|
||||
I joined the Org mailing list in May last year, it’s almost been a
|
||||
year since then and we’ve seen the release of Org 9.4, and its
|
||||
inclusion in Emacs 27.
|
||||
|
||||
I’m not going to do 12 months of work for just this one post, but I’d
|
||||
like to give you a sample of what’s changed over the last year.
|
||||
|
||||
|
||||
A new discussion tracker — [updates.orgmode.org]
|
||||
────────────────────────────────────────────────
|
||||
|
||||
Mid last year Bastien rolled out tracker for
|
||||
⁃ Upcoming changes
|
||||
⁃ Help requests
|
||||
⁃ Bugs
|
||||
⁃ Patches
|
||||
|
||||
This should help ensure nothing slips through the cracks of the ML.
|
||||
|
||||
<file:figures/screenshot-of-updates-orgmode-org.png>
|
||||
|
||||
It’s very slick, and Bastien built a [mailbox monitor] just for it —
|
||||
so be sure to check it out. This should make it easier to see what
|
||||
needs doing. If you feel inclined to help out with Org check out the
|
||||
/Help requests/ section in particular.
|
||||
|
||||
You can also get RSS feeds for individual sections, or get the
|
||||
information as JSON to work into your own projects, for example [an
|
||||
elisp function to fetch and apply patches].
|
||||
|
||||
|
||||
[updates.orgmode.org] <https://updates.orgmode.org/>
|
||||
|
||||
[mailbox monitor] <https://github.com/bzg/woof>
|
||||
|
||||
[an elisp function to fetch and apply patches]
|
||||
<https://tecosaur.github.io/emacs-config/config.html#development>
|
||||
|
||||
|
||||
Inline display of remote images
|
||||
───────────────────────────────
|
||||
|
||||
Ever gazed forlornly at a link like
|
||||
`[[https://github.com/larsmagne/meme/raw/master/images/Grandma-Finds-The-Internet.jpg]]'
|
||||
wishing you could see the image?
|
||||
|
||||
Wish no more! Thanks to Jack Kamm you can now look upon remote images
|
||||
in all their glory!
|
||||
|
||||
<https://github.com/larsmagne/meme/raw/master/images/Grandma-Finds-The-Internet.jpg>
|
||||
|
||||
To get this working, simply set `org-display-remote-inline-images' to
|
||||
`'download' or `'cache'.
|
||||
|
||||
|
||||
Use `org-edit-special' (`C-c '') with LaTeX fragments
|
||||
─────────────────────────────────────────────────────
|
||||
|
||||
It’s great how in Org you can jump into a LaTeX-mode minibuffer for
|
||||
LaTeX environments, but why leave inline LaTeX fragments out? We’ll,
|
||||
they’re now in.
|
||||
|
||||
<file:figures/org-edit-special-latex-fragment.png>
|
||||
|
||||
|
||||
Control heading display on startup
|
||||
──────────────────────────────────
|
||||
|
||||
`org-num-mode' is great for when you’re keeping an eye on section
|
||||
numbers, but it’s not fun to find yourself enabling it every time you
|
||||
open a file where you want it. With the new option `#+startup: num' by
|
||||
Bastien, you can set and forget at last.
|
||||
|
||||
<file:figures/org-startup-num-and-levels.png>
|
||||
|
||||
Should you want to set the number of levels you see on opening a file,
|
||||
there’s now an option for that too. Gustav Wikström has added
|
||||
/another/ new option `#+startup: show<n>levels' (where `<n>' is
|
||||
between 2 and 5, inclusive). /NB: This is part of the upcoming 9.5
|
||||
release/
|
||||
|
||||
|
||||
Set permissions of tangled files
|
||||
────────────────────────────────
|
||||
|
||||
Are you particular about your file permissions? If so you’ll likely
|
||||
like John Herrlin’s new source block header argument `:file-mode'
|
||||
pertinent. The easiest way to set a permission is with an [octal
|
||||
value], like so:
|
||||
┌────
|
||||
│ #+begin_src shell :results file :file script.sh :file-mode (identity #o755)
|
||||
│ echo "#!/bin/bash"
|
||||
│ echo "echo Hello World"
|
||||
│ #+end_src
|
||||
└────
|
||||
|
||||
|
||||
[octal value]
|
||||
<https://docs.nersc.gov/filesystems/unix-file-permissions/>
|
||||
|
||||
|
||||
A collection of improvements to source block header arguments
|
||||
─────────────────────────────────────────────────────────────
|
||||
|
||||
These’s been a whole set of these, so I’ll just list them off.
|
||||
python, improved `:return'
|
||||
Now works with sessions and the `:epilogue' argument (Jack Kamm)
|
||||
Java, new argument `:cmdargs'
|
||||
Add some command line arguments to be passed to `java' (Jarmo
|
||||
Hurri)
|
||||
C/C++, non-system headers with `:includes'
|
||||
values that don’t start with `<' will now be formatted as
|
||||
double-quoted `#include' statements (Brandon Guttersohn)
|
||||
Screen, new argument `:screenrc'
|
||||
For those of you who still haven’t moved to `tmux' (Kenneth
|
||||
D. Mankoff)
|
||||
|
||||
|
||||
A seven year old bug was fixed
|
||||
──────────────────────────────
|
||||
|
||||
In 2013 [it was reported] that an infinite loop could be triggered in
|
||||
`org-agenda-show-new-time'. At long last, this has been fixed by
|
||||
Bastien.
|
||||
|
||||
|
||||
[it was reported]
|
||||
<https://lists.gnu.org/archive/html/emacs-orgmode/2013-08/msg00072.html>
|
||||
|
||||
|
||||
|
||||
Footnotes
|
||||
─────────
|
||||
|
||||
[1] Aside from somewhat more [intuitive syntax]
|
||||
(<https://orgmode.org/quickstart.html>) for emphasis and simple
|
||||
structures, Org also has the advantage of not having [40 functionally
|
||||
distinct specifications]
|
||||
(<https://github.com/commonmark/commonmark-spec/wiki/markdown-flavors>). There
|
||||
is only one Org.
|
||||
NB: If you attempt to be pedantic you may say that there are multiple
|
||||
Orgs because, for example, GitHub uses [org-ruby]
|
||||
(<https://github.com/wallyqs/org-ruby>). However, that’s just an
|
||||
incomplete implementation — not a [specification]
|
||||
(<https://orgmode.org/worg/dev/org-syntax.html>).
|
||||
|
||||
[2] There is [ORG-NEWS]
|
||||
(<https://code.orgmode.org/bzg/org-mode/src/master/etc/ORG-NEWS>), but
|
||||
do you /really/ check that? Besides, it doesn’t even have pictures.
|
||||
|
||||
[3] That said, with /interesting/ projects like the [Emacs Application
|
||||
Framework]
|
||||
(<https://github.com/manateelazycat/emacs-application-framework>) and
|
||||
the [Emacs X Window Manager] (<https://github.com/ch11ng/exwm>), one
|
||||
could argue that Org is (sometimes) a major component of a desktop
|
||||
environment…
|
||||
|
|
@ -0,0 +1,331 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-12 Fri 13:39 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>April 2021</title>
|
||||
<meta name="author" content="TEC" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="April 2021" />
|
||||
<meta property="og:description" content="Export <i>&amp;</i> plot in style" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="TEC" />
|
||||
<meta property="og:article:published_time" content="2021-04-30T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2021-09-27T03:45:11+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
<link rel="stylesheet" href="img-slider.css">
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2021-04-30, <span class='acr'>TEC</span></div>
|
||||
|
||||
<h1 class="title">April 2021</h1>
|
||||
<p class="subtitle" role="doc-subtitle">Export <i>&</i> plot in style</p>
|
||||
</header><div id="outline-container-discussion-contributor-support" class="outline-2">
|
||||
<h2 id="discussion-contributor-support">A discussion on contributor support<a aria-hidden="true" href="#discussion-contributor-support">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-discussion-contributor-support">
|
||||
<p>
|
||||
Concerns <a href="https://lists.gnu.org/archive/html/emacs-orgmode/2021-04/msg00291.html">were raised</a><sup><a id="fnr.1" class="footref" href="#fn.1" role="doc-backlink">1</a></sup> about some contributors’ patches languishing, and it not
|
||||
being made clear how long it might take to get a response from someone.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
In <a href="https://lists.gnu.org/archive/html/emacs-orgmode/2021-04/msg00549.html">response to this</a>, a the new role of <i>Contributor Steward</i> has been created to:
|
||||
help ensure contributors get a timely response, help out with preliminary patch
|
||||
feedback, and keep <a href="https://updates.orgmode.org/">updates.orgmode.org</a> up to date.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Org now has three Contributor Stewards to ease the process for patch submitters
|
||||
and core maintainers:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li>Timothy / <span class='acr'>TEC</span></li>
|
||||
<li>Tim Cross</li>
|
||||
<li>John Corless</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
If you’ve been thinking about <a href="https://orgmode.org/contribute.html">getting involved with Org</a>, now is a great time to
|
||||
give it a shot!
|
||||
</p>
|
||||
|
||||
<div class="info" id="org437f980">
|
||||
<p>
|
||||
<b>Ways you can contribute to the project</b>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Test patches, improve documentation, translate pages, confirm bugs, feedback on a proposed feature, and more…
|
||||
</p>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-doi-link-exporting" class="outline-2">
|
||||
<h2 id="doi-link-exporting"><span class='acr'><span class='acr'>DOI</span></span> link exporting<a aria-hidden="true" href="#doi-link-exporting">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-doi-link-exporting">
|
||||
<p>
|
||||
<a href="https://www.doi.org/">Digital Document Identifiers</a> (<span class='acr'>DOI</span><small>s</small>) are an <span class='acr'>ISO</span>-standardised way of robustly
|
||||
linking to a particular online resource. You’ll see these a lot with academic
|
||||
papers, for example.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Thanks to Nicolas Goaziou, when exporting to <span class='acr'>HTML</span>, LaTeX, Ascii, and texinfo
|
||||
<span class='acr'>DOI</span><small>s</small> are turned into links, for example <a href="https://doi.org/10.18637/jss.v046.i03">https://doi.org/10.18637/jss.v046.i03</a> becomes:
|
||||
</p>
|
||||
|
||||
<details id='doi-link-exporting,code--1' class='code' open><summary><span class="lang">HTML</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#doi-link-exporting,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-html"><<span class="org-function-name">a</span> <span class="org-variable-name">href</span>=<span class="org-string">"https://doi.org/10.18637/jss.v046.i03"</span>>doi:10.18637/jss.v046.i03</<span class="org-function-name">a</span>>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
<details id='doi-link-exporting,code--2' class='code' open><summary><span class="lang">LaTeX</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#doi-link-exporting,code--2'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-LaTeX"><span class="org-keyword">\href</span>{<span class="org-tex-verbatim">https://doi.org/10.18637/jss.v046.i03</span>}{doi:10.18637/jss.v046.i03}
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
<details id='doi-link-exporting,code--3' class='code' open><summary><span class="lang">text</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#doi-link-exporting,code--3'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-text"><a href="https://doi.org/10.18637/jss.v046.i03"><https://doi.org/10.18637/jss.v046.i03></a>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
<details id='doi-link-exporting,code--4' class='code' open><summary><span class="lang">texinfo</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#doi-link-exporting,code--4'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-texinfo">@<span class="org-keyword">uref</span>{<span class="org-string">https://doi.org/10.18637/jss.v046.i03</span>}
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
This is a minor change, but I think <span class='acr'>DOI</span><small>s</small> are great, so I’m highlighting it.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-org-plot-improvements" class="outline-2">
|
||||
<h2 id="org-plot-improvements">Org plot improvements<a aria-hidden="true" href="#org-plot-improvements">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-org-plot-improvements">
|
||||
<p>
|
||||
Over the past month <kbd>org-plot.el</kbd> has received some attention, my two favourite
|
||||
changes are:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li>You can now call <code>org-plot/gnuplot</code> with <kbd>C-c C-c</kbd> on a <kbd>#+plot</kbd> line <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>When an image is regenerated, all instances of the image in the buffer are
|
||||
refreshed <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
</ul>
|
||||
|
||||
<figure>
|
||||
<video width="100%" height="auto" autoplay loop muted class="doom-one">
|
||||
<source src="figures/org-plot-refreshing.mp4" type="video/mp4" />
|
||||
</video>
|
||||
<figcaption>
|
||||
<span class="figure-number">Figure 1:</span>
|
||||
Regenerating an org-plot graphic, showing off: the ease of re-plotting,
|
||||
the new radar type, and a style set by a new variable.
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
Other than a few minor tweaks and bug fixes, that’s it for April. However, over
|
||||
the last year there have been some rather nice improvements that I didn’t
|
||||
mention in the initial blog post, so let’s go over them now.
|
||||
</p>
|
||||
|
||||
<ul class="org-ul">
|
||||
<li>The inbuilt plot types have been abstracted out into a new structure: <code>org-plot/preset-plot-types</code>.
|
||||
This means if you have a gnuplot template you find yourself using a lot, you
|
||||
can now turn it into a custom plot type 😀 <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>A new plot type has been added: a radar / spider plot <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>Some new plot keywords have arrived too <span class="underline"><span class='acr'>TEC</span></span>
|
||||
<ul class="org-ul">
|
||||
<li><kbd>transpose</kbd> (<kbd>trans</kbd>) — The plot internally does something very similar to <kbd>M-x
|
||||
org-table-transpose-table-at-point</kbd> before using the table data.</li>
|
||||
<li><kbd>ymin</kbd> (<kbd>min</kbd>), <kbd>ymax</kbd> (<kbd>max</kbd>), <kbd>xmin</kbd>, <kbd>xmax</kbd> — Four new keywords (and two
|
||||
aliases) to set the bounds of a plot. Partially supported by the default types.</li>
|
||||
<li><kbd>ticks</kbd> — The number of axis ticks to use along the axis. A good value is
|
||||
guessed based on a prime factorisation based heuristic (welcome to
|
||||
improvements).</li>
|
||||
<li>Some new customisation functions — The new variables
|
||||
<code>org-plot/gnuplot-script-preamble</code>, <code>org-plot/gnuplot-term-extra</code>, and
|
||||
<code>org-plot/gnuplot-script-preamble</code> open up new ways to tweak plots to your
|
||||
liking. For example, <a href="https://tecosaur.github.io/emacs-config/config.html#org-plot">I use this</a> to set line and background colours based on
|
||||
my current Emacs theme.</li>
|
||||
</ul></li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
If you haven’t used Org plot before, I think it’s a great way to quickly
|
||||
visualise data in a table. To get started, all you need is a <kbd>#+plot</kbd> line above
|
||||
the table, with a certain <kbd>type</kbd> specified (e.g. <kbd>type:2d</kbd> for a 2d line plot).
|
||||
Then, if you can specify a certain columns as the independent variable
|
||||
(x-values) with <kbd>ind</kbd>, and list dependant variables (y-values) with <kbd>deps</kbd>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
You can see these parameters set in the figure above,
|
||||
</p>
|
||||
<details id='org-plot-improvements,code--1' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#org-plot-improvements,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-meta-line">#+plot: type:2d ind:1 deps:(2 3 4)</span>
|
||||
<span class="org-org-table">| Xval | Red | Blue | Green |</span>
|
||||
<span class="org-org-table">|------+-----+------+-------|</span>
|
||||
<span class="org-org-table">| 0 | 1 | 2 | 3 |</span>
|
||||
<span class="org-org-table">| 1 | 2 | 3 | 4 |</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
This will call gnuplot and a window showing the plot will appear. If you want to
|
||||
save the plot to a file, just use the <kbd>file</kbd> parameter, e.g.
|
||||
<kbd>file:"demoplot.svg"</kbd> (note the quotes).
|
||||
</p>
|
||||
|
||||
<p>
|
||||
That should get you started, you can see <a href="https://orgmode.org/manual/Org-Plot.html">the manual</a> for the full list of
|
||||
available keywords and find more examples of usage <a href="https://orgmode.org/worg/org-tutorials/org-plot.html">on worg</a>.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-tweaked-ox-html" class="outline-2">
|
||||
<h2 id="tweaked-ox-html">Tweaked <code>ox-html</code> style<a aria-hidden="true" href="#tweaked-ox-html">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-tweaked-ox-html">
|
||||
<p>
|
||||
As displays become more high-res, lines of text which span the whole screen
|
||||
become … long. So long that it genuinely makes it harder to read the text. A
|
||||
small tweak to the default style and lines are now capped at <kbd>60em</kbd> wide and
|
||||
centred in the page — much better 🙂. <span class="underline"><span class='acr'>TEC</span></span>
|
||||
</p>
|
||||
|
||||
<figure>
|
||||
<div class="image-slider invertible">
|
||||
<div><img src="figures/org-html-style-tweak-new.png"/></div>
|
||||
<img src="figures/org-html-style-tweak-old.png"/>
|
||||
</div>
|
||||
<figcaption>
|
||||
<span class="figure-number">Figure 2:</span>
|
||||
The new export style (left) compared to the old (right).
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
Also, the <span class='acr'>HTML</span> export now:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li>has a slightly nicer source block style</li>
|
||||
<li>labels <kbd>authinfo</kbd> blocks</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-collection-export-improvements" class="outline-2">
|
||||
<h2 id="collection-export-improvements">A collection of export improvements<a aria-hidden="true" href="#collection-export-improvements">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-collection-export-improvements">
|
||||
<ul class="org-ul">
|
||||
<li><kbd>Verbatim</kbd> in headings no longer breaks LaTeX exports <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>Make the top level class for exported <span class='acr'>HTML</span> customisable via
|
||||
<code>org-html-content-class</code> / <kbd>#+HTML_CONTENT_CLASS</kbd> <span class="underline">Sameer Rahmani</span></li>
|
||||
<li>Use <kbd><img></kbd> tags for <span class='acr'>SVG</span><small>s</small> with <kbd>ox-html</kbd>, for better behaviour and W3C compliance <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>Remove redundant <code>type="text/javascript"</code> from <code><script></code> elements <span class="underline">Bastien Guerry</span></li>
|
||||
<li><kbd>ox-texinfo</kbd> now generates better headlines, menus, and footnotes <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Parsing during exporting no longer aborts as soon as an <kbd>#+option</kbd> key without
|
||||
a value is encountered, instead that key is skipped over <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li><code>org-html-scripts</code> and <code>org-html-style-default</code> have been changed from constants
|
||||
to configurable values <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>eval macros <kbd>#+macro: ? (eval ...)</kbd> are now a little bit faster <span class="underline">Stefan Monnier</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-miscellaneous-changes" class="outline-2">
|
||||
<h2 id="miscellaneous-changes">Miscellaneous changes<a aria-hidden="true" href="#miscellaneous-changes">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-miscellaneous-changes">
|
||||
<ul class="org-ul">
|
||||
<li><code>org-link-descriptive</code> is now buffer-local, to avoid interfering with other buffers <span class="underline">Kyle Meyer</span></li>
|
||||
<li><kbd>org-colview</kbd> no longer chokes when a special property is updated <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Now coderefs have their whitespace cleaned up during tangling <span class="underline">Tom Gillespie</span></li>
|
||||
<li>Allow for multiple <kbd>%(expressions)</kbd> in <code>org-agenda-prefix-format</code> <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>Code cleanup and refactoring <span class="underline">Nicolas Savage, Aaron L. Zeng, Nicolas Goaziou,
|
||||
Bastien Guerry, Stefa Monnier, Arne Babenhauserheid</span></li>
|
||||
<li>Documentation improvements <span class="underline">Jorge Neto, Erik Hetzner, Cheong Yiu Fung, Kyle Meyer</span></li>
|
||||
<li>New <kbd>ob-sqlite</kbd> maintainer — Nick Savage</li>
|
||||
<li>Make lilypond header arguments user-configurable <span class="underline">Jamie Bayne</span></li>
|
||||
<li>Fix <kbd>ob-C</kbd> regression which mixed up <code>int</code>, <code>double</code>, and <code>char*</code>. Fix another
|
||||
regression with table parameters <span class="underline">tbanel</span></li>
|
||||
<li>Fix indentation of list items and new logbook drawer notes <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Notice when theme changes with LaTeX previews <span class="underline">Yuri Lensky</span></li>
|
||||
<li>Iron out a few edge cases in <kbd>ol.el</kbd> (Org links) <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Some new tests for <kbd>org-protocol</kbd> <span class="underline">Maxim Nikulin</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="footnotes">
|
||||
<h2 class="footnotes">Footnotes: </h2>
|
||||
<div id="text-footnotes">
|
||||
|
||||
<div class="footdef"><sup><a id="fn.1" class="footnum" href="#fnr.1" role="doc-backlink">1</a></sup> <div class="footpara" role="doc-footnote"><p class="footpara">
|
||||
Disclosure: this is me.
|
||||
</p></div></div>
|
||||
|
||||
|
||||
</div>
|
||||
</div></div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,9 +1,9 @@
|
|||
# Created 2024-01-12 Fri 13:39
|
||||
#+title: April 2021
|
||||
#+subtitle: Export /&/ plot in style
|
||||
#+author: TEC
|
||||
#+date: 2021-04-30
|
||||
#+author: TEC
|
||||
#+subtitle: Export /&/ plot in style
|
||||
#+html_head: <link rel="stylesheet" href="img-slider.css">
|
||||
|
||||
* A discussion on contributor support
|
||||
|
||||
Concerns [[https://lists.gnu.org/archive/html/emacs-orgmode/2021-04/msg00291.html][were raised]][fn:1] about some contributors' patches languishing, and it not
|
||||
|
|
@ -15,9 +15,9 @@ feedback, and keep [[https://updates.orgmode.org/][updates.orgmode.org]] up to d
|
|||
|
||||
Org now has three Contributor Stewards to ease the process for patch submitters
|
||||
and core maintainers:
|
||||
+ Timothy / TEC
|
||||
+ Tim Cross
|
||||
+ John Corless
|
||||
- Timothy / TEC
|
||||
- Tim Cross
|
||||
- John Corless
|
||||
|
||||
If you've been thinking about [[https://orgmode.org/contribute.html][getting involved with Org]], now is a great time to
|
||||
give it a shot!
|
||||
|
|
@ -28,6 +28,7 @@ give it a shot!
|
|||
Test patches, improve documentation, translate pages, confirm bugs, feedback on a proposed feature, and more...
|
||||
#+end_info
|
||||
|
||||
[fn:1] Disclosure: this is me.
|
||||
* DOI link exporting
|
||||
|
||||
[[https://www.doi.org/][Digital Document Identifiers]] (DOIs) are an ISO-standardised way of robustly
|
||||
|
|
@ -35,55 +36,41 @@ linking to a particular online resource. You'll see these a lot with academic
|
|||
papers, for example.
|
||||
|
||||
Thanks to Nicolas Goaziou, when exporting to HTML, LaTeX, Ascii, and texinfo
|
||||
DOIs are turned into links, for example [[doi:10.18637/jss.v046.i03]] becomes:
|
||||
DOIs are turned into links, for example https://doi.org/10.18637/jss.v046.i03 becomes:
|
||||
|
||||
#+begin_src html
|
||||
<a href="https://doi.org/10.18637/jss.v046.i03">doi:10.18637/jss.v046.i03</a>
|
||||
<a href="https://doi.org/10.18637/jss.v046.i03">doi:10.18637/jss.v046.i03</a>
|
||||
#+end_src
|
||||
#+begin_src LaTeX
|
||||
\href{https://doi.org/10.18637/jss.v046.i03}{doi:10.18637/jss.v046.i03}
|
||||
\href{https://doi.org/10.18637/jss.v046.i03}{doi:10.18637/jss.v046.i03}
|
||||
#+end_src
|
||||
#+begin_src text
|
||||
<https://doi.org/10.18637/jss.v046.i03>
|
||||
<https://doi.org/10.18637/jss.v046.i03>
|
||||
#+end_src
|
||||
#+begin_src texinfo
|
||||
@uref{https://doi.org/10.18637/jss.v046.i03}
|
||||
@uref{https://doi.org/10.18637/jss.v046.i03}
|
||||
#+end_src
|
||||
|
||||
This is a minor change, but I think DOIs are great, so I'm highlighting it.
|
||||
|
||||
* Org plot improvements
|
||||
|
||||
Over the past month =org-plot.el= has received some attention, my two favourite
|
||||
changes are:
|
||||
+ You can now call ~org-plot/gnuplot~ with =C-c C-c= on a =#+plot= line _TEC_
|
||||
+ When an image is regenerated, all instances of the image in the buffer are
|
||||
- You can now call ~org-plot/gnuplot~ with =C-c C-c= on a =#+plot= line _TEC_
|
||||
- When an image is regenerated, all instances of the image in the buffer are
|
||||
refreshed _TEC_
|
||||
|
||||
#+begin_export html
|
||||
<figure>
|
||||
<video width="100%" height="auto" autoplay loop muted class="doom-one">
|
||||
<source src="figures/org-plot-refreshing.mp4" type="video/mp4" />
|
||||
</video>
|
||||
<figcaption>
|
||||
<span class="figure-number">Figure 1:</span>
|
||||
Regenerating an org-plot graphic, showing off: the ease of re-plotting,
|
||||
the new radar type, and a style set by a new variable.
|
||||
</figcaption>
|
||||
</figure>
|
||||
#+end_export
|
||||
|
||||
Other than a few minor tweaks and bug fixes, that's it for April. However, over
|
||||
the last year there have been some rather nice improvements that I didn't
|
||||
mention in the initial blog post, so let's go over them now.
|
||||
|
||||
+ The inbuilt plot types have been abstracted out into a new structure: ~org-plot/preset-plot-types~.
|
||||
- The inbuilt plot types have been abstracted out into a new structure: ~org-plot/preset-plot-types~.
|
||||
This means if you have a gnuplot template you find yourself using a lot, you
|
||||
can now turn it into a custom plot type 😀 _TEC_
|
||||
+ A new plot type has been added: a radar / spider plot _TEC_
|
||||
+ Some new plot keywords have arrived too _TEC_
|
||||
- A new plot type has been added: a radar / spider plot _TEC_
|
||||
- Some new plot keywords have arrived too _TEC_
|
||||
- =transpose= (=trans=) --- The plot internally does something very similar to =M-x
|
||||
org-table-transpose-table-at-point= before using the table data.
|
||||
org-table-transpose-table-at-point= before using the table data.
|
||||
- =ymin= (=min=), =ymax= (=max=), =xmin=, =xmax= --- Four new keywords (and two
|
||||
aliases) to set the bounds of a plot. Partially supported by the default types.
|
||||
- =ticks= --- The number of axis ticks to use along the axis. A good value is
|
||||
|
|
@ -103,11 +90,11 @@ Then, if you can specify a certain columns as the independent variable
|
|||
|
||||
You can see these parameters set in the figure above,
|
||||
#+begin_src org
|
||||
,#+plot: type:2d ind:1 deps:(2 3 4)
|
||||
| Xval | Red | Blue | Green |
|
||||
|------+-----+------+-------|
|
||||
| 0 | 1 | 2 | 3 |
|
||||
| 1 | 2 | 3 | 4 |
|
||||
,#+plot: type:2d ind:1 deps:(2 3 4)
|
||||
| Xval | Red | Blue | Green |
|
||||
|------+-----+------+-------|
|
||||
| 0 | 1 | 2 | 3 |
|
||||
| 1 | 2 | 3 | 4 |
|
||||
#+end_src
|
||||
|
||||
This will call gnuplot and a window showing the plot will appear. If you want to
|
||||
|
|
@ -116,7 +103,6 @@ save the plot to a file, just use the =file= parameter, e.g.
|
|||
|
||||
That should get you started, you can see [[https://orgmode.org/manual/Org-Plot.html][the manual]] for the full list of
|
||||
available keywords and find more examples of usage [[https://orgmode.org/worg/org-tutorials/org-plot.html][on worg]].
|
||||
|
||||
* Tweaked ~ox-html~ style
|
||||
|
||||
As displays become more high-res, lines of text which span the whole screen
|
||||
|
|
@ -124,55 +110,36 @@ become ... long. So long that it genuinely makes it harder to read the text. A
|
|||
small tweak to the default style and lines are now capped at =60em= wide and
|
||||
centred in the page --- much better 🙂. _TEC_
|
||||
|
||||
#+begin_export html
|
||||
<figure>
|
||||
<div class="image-slider invertible">
|
||||
<div><img src="figures/org-html-style-tweak-new.png"/></div>
|
||||
<img src="figures/org-html-style-tweak-old.png"/>
|
||||
</div>
|
||||
<figcaption>
|
||||
<span class="figure-number">Figure 2:</span>
|
||||
The new export style (left) compared to the old (right).
|
||||
</figcaption>
|
||||
</figure>
|
||||
#+end_export
|
||||
|
||||
Also, the HTML export now:
|
||||
+ has a slightly nicer source block style
|
||||
+ labels =authinfo= blocks
|
||||
|
||||
- has a slightly nicer source block style
|
||||
- labels =authinfo= blocks
|
||||
* A collection of export improvements
|
||||
|
||||
+ =Verbatim= in headings no longer breaks LaTeX exports _TEC_
|
||||
+ Make the top level class for exported HTML customisable via
|
||||
- =Verbatim= in headings no longer breaks LaTeX exports _TEC_
|
||||
- Make the top level class for exported HTML customisable via
|
||||
~org-html-content-class~ / =#+HTML_CONTENT_CLASS= _Sameer Rahmani_
|
||||
+ Use =<img>= tags for SVGs with =ox-html=, for better behaviour and W3C compliance _TEC_
|
||||
+ Remove redundant ~type="text/javascript"~ from ~<script>~ elements _Bastien Guerry_
|
||||
+ =ox-texinfo= now generates better headlines, menus, and footnotes _Nicolas Goaziou_
|
||||
+ Parsing during exporting no longer aborts as soon as an =#+option= key without
|
||||
- Use =<img>= tags for SVGs with =ox-html=, for better behaviour and W3C compliance _TEC_
|
||||
- Remove redundant ~type="text/javascript"~ from ~<script>~ elements _Bastien Guerry_
|
||||
- =ox-texinfo= now generates better headlines, menus, and footnotes _Nicolas Goaziou_
|
||||
- Parsing during exporting no longer aborts as soon as an =#+option= key without
|
||||
a value is encountered, instead that key is skipped over _Nicolas Goaziou_
|
||||
+ ~org-html-scripts~ and ~org-html-style-default~ have been changed from constants
|
||||
- ~org-html-scripts~ and ~org-html-style-default~ have been changed from constants
|
||||
to configurable values _TEC_
|
||||
+ eval macros =#+macro: ? (eval ...)= are now a little bit faster _Stefan Monnier_
|
||||
|
||||
- eval macros =#+macro: ? (eval ...)= are now a little bit faster _Stefan Monnier_
|
||||
* Miscellaneous changes
|
||||
|
||||
+ ~org-link-descriptive~ is now buffer-local, to avoid interfering with other buffers _Kyle Meyer_
|
||||
+ =org-colview= no longer chokes when a special property is updated _Nicolas Goaziou_
|
||||
+ Now coderefs have their whitespace cleaned up during tangling _Tom Gillespie_
|
||||
+ Allow for multiple =%(expressions)= in ~org-agenda-prefix-format~ _Ihor Radchenko_
|
||||
+ Code cleanup and refactoring _Nicolas Savage, Aaron L. Zeng, Nicolas Goaziou,
|
||||
- ~org-link-descriptive~ is now buffer-local, to avoid interfering with other buffers _Kyle Meyer_
|
||||
- =org-colview= no longer chokes when a special property is updated _Nicolas Goaziou_
|
||||
- Now coderefs have their whitespace cleaned up during tangling _Tom Gillespie_
|
||||
- Allow for multiple =%(expressions)= in ~org-agenda-prefix-format~ _Ihor Radchenko_
|
||||
- Code cleanup and refactoring _Nicolas Savage, Aaron L. Zeng, Nicolas Goaziou,
|
||||
Bastien Guerry, Stefa Monnier, Arne Babenhauserheid_
|
||||
+ Documentation improvements _Jorge Neto, Erik Hetzner, Cheong Yiu Fung, Kyle Meyer_
|
||||
+ New =ob-sqlite= maintainer --- Nick Savage
|
||||
+ Make lilypond header arguments user-configurable _Jamie Bayne_
|
||||
+ Fix =ob-C= regression which mixed up ~int~, ~double~, and ~char*~. Fix another
|
||||
- Documentation improvements _Jorge Neto, Erik Hetzner, Cheong Yiu Fung, Kyle Meyer_
|
||||
- New =ob-sqlite= maintainer --- Nick Savage
|
||||
- Make lilypond header arguments user-configurable _Jamie Bayne_
|
||||
- Fix =ob-C= regression which mixed up ~int~, ~double~, and ~char*~. Fix another
|
||||
regression with table parameters _tbanel_
|
||||
+ Fix indentation of list items and new logbook drawer notes _Bastien Guerry_
|
||||
+ Notice when theme changes with LaTeX previews _Yuri Lensky_
|
||||
+ Iron out a few edge cases in =ol.el= (Org links) _Nicolas Goaziou_
|
||||
+ Some new tests for =org-protocol= _Maxim Nikulin_
|
||||
|
||||
* Footnotes
|
||||
|
||||
[fn:1] Disclosure: this is me.
|
||||
- Fix indentation of list items and new logbook drawer notes _Bastien Guerry_
|
||||
- Notice when theme changes with LaTeX previews _Yuri Lensky_
|
||||
- Iron out a few edge cases in =ol.el= (Org links) _Nicolas Goaziou_
|
||||
- Some new tests for =org-protocol= _Maxim Nikulin_
|
||||
|
|
@ -0,0 +1,299 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>2021-04-30-export-plot.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">April 2021
|
||||
</span><span style="color: #9e9e9e;">#+subtitle:</span> Export /&/ plot in style
|
||||
<span style="color: #9e9e9e;">#+author:</span> TEC
|
||||
<span style="color: #9e9e9e;">#+date:</span> 2021-04-30
|
||||
<span style="color: #b1b1b1;">#+html_head: <link rel="stylesheet" href="img-slider.css"></span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* A discussion on contributor support</span>
|
||||
|
||||
Concerns <span style="color: #3b6ea8; font-weight: 700;">[[https://lists.gnu.org/archive/html/emacs-orgmode/2021-04/msg00291.html][were raised]]</span>[fn:1] about some contributors' patches languishing, and it not
|
||||
being made clear how long it might take to get a response from someone.
|
||||
|
||||
In <span style="color: #3b6ea8; font-weight: 700;">[[https://lists.gnu.org/archive/html/emacs-orgmode/2021-04/msg00549.html][response to this]]</span>, a the new role of <span class="ef-i">/Contributor Steward/</span> has been created to:
|
||||
help ensure contributors get a timely response, help out with preliminary patch
|
||||
feedback, and keep <span style="color: #3b6ea8; font-weight: 700;">[[https://updates.orgmode.org/][updates.orgmode.org]]</span> up to date.
|
||||
|
||||
Org now has three Contributor Stewards to ease the process for patch submitters
|
||||
and core maintainers:
|
||||
+ Timothy / TEC
|
||||
+ Tim Cross
|
||||
+ John Corless
|
||||
|
||||
If you've been thinking about <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/contribute.html][getting involved with Org]]</span>, now is a great time to
|
||||
give it a shot!
|
||||
|
||||
<span class="ef-obb">#+begin_info
|
||||
</span><span class="ef-b">*Ways you can contribute to the project*</span>
|
||||
|
||||
Test patches, improve documentation, translate pages, confirm bugs, feedback on a proposed feature, and more...
|
||||
<span class="ef-obe">#+end_info
|
||||
</span>
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* DOI link exporting</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[https://www.doi.org/][Digital Document Identifiers]]</span> (DOIs) are an ISO-standardised way of robustly
|
||||
linking to a particular online resource. You'll see these a lot with academic
|
||||
papers, for example.
|
||||
|
||||
Thanks to Nicolas Goaziou, when exporting to HTML, LaTeX, Ascii, and texinfo
|
||||
DOIs are turned into links, for example <span style="color: #3b6ea8; font-weight: 700;">[[doi:10.18637/jss.v046.i03]]</span> becomes:
|
||||
|
||||
<span class="ef-obb">#+begin_src html
|
||||
</span><span class="ef-ob"><</span><span style="color: #29838d; background-color: #e0e0e0;">a</span> <span style="color: #cb9aad; background-color: #e0e0e0;">href</span><span class="ef-ob">=</span><span style="color: #4f894c; background-color: #e0e0e0;">"https://doi.org/10.18637/jss.v046.i03"</span><span class="ef-ob">>doi:10.18637/jss.v046.i03</</span><span style="color: #29838d; background-color: #e0e0e0;">a</span><span class="ef-ob">>
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span><span class="ef-obb">#+begin_src LaTeX
|
||||
</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\href</span><span class="ef-ob">{</span><span style="color: #9e9e9e; background-color: #e0e0e0;">https://doi.org/10.18637/jss.v046.i03</span><span class="ef-ob">}{doi:10.18637/jss.v046.i03}
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span><span class="ef-obb">#+begin_src text
|
||||
</span><span class="ef-ob"><https://doi.org/10.18637/jss.v046.i03>
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span><span class="ef-obb">#+begin_src texinfo
|
||||
</span><span class="ef-ob">@</span><span style="color: #3b6ea8; background-color: #e0e0e0;">uref</span><span class="ef-ob">{</span><span style="color: #4f894c; background-color: #e0e0e0;">https://doi.org/10.18637/jss.v046.i03</span><span class="ef-ob">}
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
This is a minor change, but I think DOIs are great, so I'm highlighting it.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Org plot improvements</span>
|
||||
|
||||
Over the past month <span style="color: #9e9e9e;">=org-plot.el=</span> has received some attention, my two favourite
|
||||
changes are:
|
||||
+ You can now call <span style="color: #9e9e9e;">~org-plot/gnuplot~</span> with <span style="color: #9e9e9e;">=C-c C-c=</span> on a <span style="color: #9e9e9e;">=#+plot=</span> line _TEC_
|
||||
+ When an image is regenerated, all instances of the image in the buffer are
|
||||
refreshed _TEC_
|
||||
|
||||
<span class="ef-obb">#+begin_export html
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;"><figure>
|
||||
<video width="100%" height="auto" autoplay loop muted class="doom-one">
|
||||
<source src="figures/org-plot-refreshing.mp4" type="video/mp4" />
|
||||
</video>
|
||||
<figcaption>
|
||||
<span class="figure-number">Figure 1:</span>
|
||||
Regenerating an org-plot graphic, showing off: the ease of re-plotting,
|
||||
the new radar type, and a style set by a new variable.
|
||||
</figcaption>
|
||||
</figure>
|
||||
</span><span class="ef-obe">#+end_export
|
||||
</span>
|
||||
Other than a few minor tweaks and bug fixes, that's it for April. However, over
|
||||
the last year there have been some rather nice improvements that I didn't
|
||||
mention in the initial blog post, so let's go over them now.
|
||||
|
||||
+ The inbuilt plot types have been abstracted out into a new structure: <span style="color: #9e9e9e;">~org-plot/preset-plot-types~</span>.
|
||||
This means if you have a gnuplot template you find yourself using a lot, you
|
||||
can now turn it into a custom plot type 😀 _TEC_
|
||||
+ A new plot type has been added: a radar / spider plot _TEC_
|
||||
+ Some new plot keywords have arrived too _TEC_
|
||||
- <span style="color: #9e9e9e;">=transpose=</span> (<span style="color: #9e9e9e;">=trans=</span>) --- The plot internally does something very similar to <span style="color: #9e9e9e;">=M-x
|
||||
org-table-transpose-table-at-point=</span> before using the table data.
|
||||
- <span style="color: #9e9e9e;">=ymin=</span> (<span style="color: #9e9e9e;">=min=</span>), <span style="color: #9e9e9e;">=ymax=</span> (<span style="color: #9e9e9e;">=max=</span>), <span style="color: #9e9e9e;">=xmin=</span>, <span style="color: #9e9e9e;">=xmax=</span> --- Four new keywords (and two
|
||||
aliases) to set the bounds of a plot. Partially supported by the default types.
|
||||
- <span style="color: #9e9e9e;">=ticks=</span> --- The number of axis ticks to use along the axis. A good value is
|
||||
guessed based on a prime factorisation based heuristic (welcome to
|
||||
improvements).
|
||||
- Some new customisation functions --- The new variables
|
||||
<span style="color: #9e9e9e;">~org-plot/gnuplot-script-preamble~</span>, <span style="color: #9e9e9e;">~org-plot/gnuplot-term-extra~</span>, and
|
||||
<span style="color: #9e9e9e;">~org-plot/gnuplot-script-preamble~</span> open up new ways to tweak plots to your
|
||||
liking. For example, <span style="color: #3b6ea8; font-weight: 700;">[[https://tecosaur.github.io/emacs-config/config.html#org-plot][I use this]]</span> to set line and background colours based on
|
||||
my current Emacs theme.
|
||||
|
||||
If you haven't used Org plot before, I think it's a great way to quickly
|
||||
visualise data in a table. To get started, all you need is a <span style="color: #9e9e9e;">=#+plot=</span> line above
|
||||
the table, with a certain <span style="color: #9e9e9e;">=type=</span> specified (e.g. <span style="color: #9e9e9e;">=type:2d=</span> for a 2d line plot).
|
||||
Then, if you can specify a certain columns as the independent variable
|
||||
(x-values) with <span style="color: #9e9e9e;">=ind=</span>, and list dependant variables (y-values) with <span style="color: #9e9e9e;">=deps=</span>.
|
||||
|
||||
You can see these parameters set in the figure above,
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+plot: type:2d ind:1 deps:(2 3 4)
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;">| Xval | Red | Blue | Green |</span>
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">|------+-----+------+-------|</span>
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">| 0 | 1 | 2 | 3 |</span>
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">| 1 | 2 | 3 | 4 |</span>
|
||||
<span class="ef-obe">#+end_src
|
||||
</span>
|
||||
This will call gnuplot and a window showing the plot will appear. If you want to
|
||||
save the plot to a file, just use the <span style="color: #9e9e9e;">=file=</span> parameter, e.g.
|
||||
<span style="color: #9e9e9e;">=</span><span style="color: #9e9e9e; font-weight: 700;">file:"demoplot.svg</span><span style="color: #9e9e9e;">"=</span> (note the quotes).
|
||||
|
||||
That should get you started, you can see <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/manual/Org-Plot.html][the manual]]</span> for the full list of
|
||||
available keywords and find more examples of usage <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/worg/org-tutorials/org-plot.html][on worg]]</span>.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Tweaked </span><span style="color: #9e9e9e; font-weight: nil; font-size: 1.25em">~ox-html~</span><span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em"> style</span>
|
||||
|
||||
As displays become more high-res, lines of text which span the whole screen
|
||||
become ... long. So long that it genuinely makes it harder to read the text. A
|
||||
small tweak to the default style and lines are now capped at <span style="color: #9e9e9e;">=60em=</span> wide and
|
||||
centred in the page --- much better 🙂. _TEC_
|
||||
|
||||
<span class="ef-obb">#+begin_export html
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;"><figure>
|
||||
<div class="image-slider invertible">
|
||||
<div><img src="figures/org-html-style-tweak-new.png"/></div>
|
||||
<img src="figures/org-html-style-tweak-old.png"/>
|
||||
</div>
|
||||
<figcaption>
|
||||
<span class="figure-number">Figure 2:</span>
|
||||
The new export style (left) compared to the old (right).
|
||||
</figcaption>
|
||||
</figure>
|
||||
</span><span class="ef-obe">#+end_export
|
||||
</span>
|
||||
Also, the HTML export now:
|
||||
+ has a slightly nicer source block style
|
||||
+ labels <span style="color: #9e9e9e;">=authinfo=</span> blocks
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* A collection of export improvements</span>
|
||||
|
||||
+ <span style="color: #9e9e9e;">=Verbatim=</span> in headings no longer breaks LaTeX exports _TEC_
|
||||
+ Make the top level class for exported HTML customisable via
|
||||
<span style="color: #9e9e9e;">~org-html-content-class~</span> / <span style="color: #9e9e9e;">=#+HTML_CONTENT_CLASS=</span> _Sameer Rahmani_
|
||||
+ Use <span style="color: #9e9e9e;">=<img>=</span> tags for SVGs with <span style="color: #9e9e9e;">=ox-html=</span>, for better behaviour and W3C compliance _TEC_
|
||||
+ Remove redundant <span style="color: #9e9e9e;">~type="text/javascript"~</span> from <span style="color: #9e9e9e;">~<script>~</span> elements _Bastien Guerry_
|
||||
+ <span style="color: #9e9e9e;">=ox-texinfo=</span> now generates better headlines, menus, and footnotes _Nicolas Goaziou_
|
||||
+ Parsing during exporting no longer aborts as soon as an <span style="color: #9e9e9e;">=#+option=</span> key without
|
||||
a value is encountered, instead that key is skipped over _Nicolas Goaziou_
|
||||
+ <span style="color: #9e9e9e;">~org-html-scripts~</span> and <span style="color: #9e9e9e;">~org-html-style-default~</span> have been changed from constants
|
||||
to configurable values _TEC_
|
||||
+ eval macros <span style="color: #9e9e9e;">=#+macro: ? (eval ...)=</span> are now a little bit faster _Stefan Monnier_
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Miscellaneous changes</span>
|
||||
|
||||
+ <span style="color: #9e9e9e;">~org-link-descriptive~</span> is now buffer-local, to avoid interfering with other buffers _Kyle Meyer_
|
||||
+ <span style="color: #9e9e9e;">=org-colview=</span> no longer chokes when a special property is updated _Nicolas Goaziou_
|
||||
+ Now coderefs have their whitespace cleaned up during tangling _Tom Gillespie_
|
||||
+ Allow for multiple <span style="color: #9e9e9e;">=%(expressions)=</span> in <span style="color: #9e9e9e;">~org-agenda-prefix-format~</span> _Ihor Radchenko_
|
||||
+ Code cleanup and refactoring _Nicolas Savage, Aaron L. Zeng, Nicolas Goaziou,
|
||||
Bastien Guerry, Stefa Monnier, Arne Babenhauserheid_
|
||||
+ Documentation improvements _Jorge Neto, Erik Hetzner, Cheong Yiu Fung, Kyle Meyer_
|
||||
+ New <span style="color: #9e9e9e;">=ob-sqlite=</span> maintainer --- Nick Savage
|
||||
+ Make lilypond header arguments user-configurable _Jamie Bayne_
|
||||
+ Fix <span style="color: #9e9e9e;">=ob-C=</span> regression which mixed up <span style="color: #9e9e9e;">~int~</span>, <span style="color: #9e9e9e;">~double~</span>, and <span style="color: #9e9e9e;">~char*~</span>. Fix another
|
||||
regression with table parameters _tbanel_
|
||||
+ Fix indentation of list items and new logbook drawer notes _Bastien Guerry_
|
||||
+ Notice when theme changes with LaTeX previews _Yuri Lensky_
|
||||
+ Iron out a few edge cases in <span style="color: #9e9e9e;">=ol.el=</span> (Org links) _Nicolas Goaziou_
|
||||
+ Some new tests for <span style="color: #9e9e9e;">=org-protocol=</span> _Maxim Nikulin_
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Footnotes</span>
|
||||
|
||||
[fn:1] Disclosure: this is me.
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,213 @@
|
|||
━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
APRIL 2021
|
||||
Export /&/ plot in style
|
||||
|
||||
TEC
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
|
||||
2021-04-30
|
||||
|
||||
|
||||
A discussion on contributor support
|
||||
═══════════════════════════════════
|
||||
|
||||
Concerns [were raised][1] about some contributors’ patches
|
||||
languishing, and it not being made clear how long it might take to get
|
||||
a response from someone.
|
||||
|
||||
In [response to this], a the new role of /Contributor Steward/ has
|
||||
been created to: help ensure contributors get a timely response, help
|
||||
out with preliminary patch feedback, and keep [updates.orgmode.org] up
|
||||
to date.
|
||||
|
||||
Org now has three Contributor Stewards to ease the process for patch
|
||||
submitters and core maintainers:
|
||||
⁃ Timothy / TEC
|
||||
⁃ Tim Cross
|
||||
⁃ John Corless
|
||||
|
||||
If you’ve been thinking about [getting involved with Org], now is a
|
||||
great time to give it a shot!
|
||||
|
||||
*Ways you can contribute to the project*
|
||||
|
||||
Test patches, improve documentation, translate pages, confirm bugs,
|
||||
feedback on a proposed feature, and more…
|
||||
|
||||
|
||||
[were raised]
|
||||
<https://lists.gnu.org/archive/html/emacs-orgmode/2021-04/msg00291.html>
|
||||
|
||||
[response to this]
|
||||
<https://lists.gnu.org/archive/html/emacs-orgmode/2021-04/msg00549.html>
|
||||
|
||||
[updates.orgmode.org] <https://updates.orgmode.org/>
|
||||
|
||||
[getting involved with Org] <https://orgmode.org/contribute.html>
|
||||
|
||||
|
||||
DOI link exporting
|
||||
══════════════════
|
||||
|
||||
[Digital Document Identifiers] (DOIs) are an ISO-standardised way of
|
||||
robustly linking to a particular online resource. You’ll see these a
|
||||
lot with academic papers, for example.
|
||||
|
||||
Thanks to Nicolas Goaziou, when exporting to HTML, LaTeX, Ascii, and
|
||||
texinfo DOIs are turned into links, for example
|
||||
<https://doi.org/10.18637/jss.v046.i03> becomes:
|
||||
|
||||
┌────
|
||||
│ <a href="https://doi.org/10.18637/jss.v046.i03">doi:10.18637/jss.v046.i03</a>
|
||||
└────
|
||||
┌────
|
||||
│ \href{https://doi.org/10.18637/jss.v046.i03}{doi:10.18637/jss.v046.i03}
|
||||
└────
|
||||
┌────
|
||||
│ <https://doi.org/10.18637/jss.v046.i03>
|
||||
└────
|
||||
┌────
|
||||
│ @uref{https://doi.org/10.18637/jss.v046.i03}
|
||||
└────
|
||||
|
||||
This is a minor change, but I think DOIs are great, so I’m
|
||||
highlighting it.
|
||||
|
||||
|
||||
[Digital Document Identifiers] <https://www.doi.org/>
|
||||
|
||||
|
||||
Org plot improvements
|
||||
═════════════════════
|
||||
|
||||
Over the past month `org-plot.el' has received some attention, my two
|
||||
favourite changes are:
|
||||
⁃ You can now call `org-plot/gnuplot' with `C-c C-c' on a `#+plot'
|
||||
line _TEC_
|
||||
⁃ When an image is regenerated, all instances of the image in the
|
||||
buffer are refreshed _TEC_
|
||||
|
||||
Other than a few minor tweaks and bug fixes, that’s it for
|
||||
April. However, over the last year there have been some rather nice
|
||||
improvements that I didn’t mention in the initial blog post, so let’s
|
||||
go over them now.
|
||||
|
||||
⁃ The inbuilt plot types have been abstracted out into a new
|
||||
structure: `org-plot/preset-plot-types'. This means if you have a
|
||||
gnuplot template you find yourself using a lot, you can now turn it
|
||||
into a custom plot type 😀 _TEC_
|
||||
⁃ A new plot type has been added: a radar / spider plot _TEC_
|
||||
⁃ Some new plot keywords have arrived too _TEC_
|
||||
• `transpose' (`trans') — The plot internally does something very
|
||||
similar to `M-x org-table-transpose-table-at-point' before
|
||||
using the table data.
|
||||
• `ymin' (`min'), `ymax' (`max'), `xmin', `xmax' — Four new keywords
|
||||
(and two aliases) to set the bounds of a plot. Partially supported
|
||||
by the default types.
|
||||
• `ticks' — The number of axis ticks to use along the axis. A good
|
||||
value is guessed based on a prime factorisation based heuristic
|
||||
(welcome to improvements).
|
||||
• Some new customisation functions — The new variables
|
||||
`org-plot/gnuplot-script-preamble', `org-plot/gnuplot-term-extra',
|
||||
and `org-plot/gnuplot-script-preamble' open up new ways to tweak
|
||||
plots to your liking. For example, [I use this] to set line and
|
||||
background colours based on my current Emacs theme.
|
||||
|
||||
If you haven’t used Org plot before, I think it’s a great way to
|
||||
quickly visualise data in a table. To get started, all you need is a
|
||||
`#+plot' line above the table, with a certain `type' specified
|
||||
(e.g. `type:2d' for a 2d line plot). Then, if you can specify a
|
||||
certain columns as the independent variable (x-values) with `ind', and
|
||||
list dependant variables (y-values) with `deps'.
|
||||
|
||||
You can see these parameters set in the figure above,
|
||||
┌────
|
||||
│ #+plot: type:2d ind:1 deps:(2 3 4)
|
||||
│ | Xval | Red | Blue | Green |
|
||||
│ |------+-----+------+-------|
|
||||
│ | 0 | 1 | 2 | 3 |
|
||||
│ | 1 | 2 | 3 | 4 |
|
||||
└────
|
||||
|
||||
This will call gnuplot and a window showing the plot will appear. If
|
||||
you want to save the plot to a file, just use the `file' parameter,
|
||||
e.g. `file:"demoplot.svg"' (note the quotes).
|
||||
|
||||
That should get you started, you can see [the manual] for the full
|
||||
list of available keywords and find more examples of usage [on worg].
|
||||
|
||||
|
||||
[I use this]
|
||||
<https://tecosaur.github.io/emacs-config/config.html#org-plot>
|
||||
|
||||
[the manual] <https://orgmode.org/manual/Org-Plot.html>
|
||||
|
||||
[on worg] <https://orgmode.org/worg/org-tutorials/org-plot.html>
|
||||
|
||||
|
||||
Tweaked `ox-html' style
|
||||
═══════════════════════
|
||||
|
||||
As displays become more high-res, lines of text which span the whole
|
||||
screen become … long. So long that it genuinely makes it harder to
|
||||
read the text. A small tweak to the default style and lines are now
|
||||
capped at `60em' wide and centred in the page — much better 🙂. _TEC_
|
||||
|
||||
Also, the HTML export now:
|
||||
⁃ has a slightly nicer source block style
|
||||
⁃ labels `authinfo' blocks
|
||||
|
||||
|
||||
A collection of export improvements
|
||||
═══════════════════════════════════
|
||||
|
||||
⁃ `Verbatim' in headings no longer breaks LaTeX exports _TEC_
|
||||
⁃ Make the top level class for exported HTML customisable via
|
||||
`org-html-content-class' / `#+HTML_CONTENT_CLASS' _Sameer Rahmani_
|
||||
⁃ Use `<img>' tags for SVGs with `ox-html', for better behaviour and
|
||||
W3C compliance _TEC_
|
||||
⁃ Remove redundant `type="text/javascript"' from `<script>' elements
|
||||
_Bastien Guerry_
|
||||
⁃ `ox-texinfo' now generates better headlines, menus, and footnotes
|
||||
_Nicolas Goaziou_
|
||||
⁃ Parsing during exporting no longer aborts as soon as an `#+option'
|
||||
key without a value is encountered, instead that key is skipped over
|
||||
_Nicolas Goaziou_
|
||||
⁃ `org-html-scripts' and `org-html-style-default' have been changed
|
||||
from constants to configurable values _TEC_
|
||||
⁃ eval macros `#+macro: ? (eval ...)' are now a little bit faster
|
||||
_Stefan Monnier_
|
||||
|
||||
|
||||
Miscellaneous changes
|
||||
═════════════════════
|
||||
|
||||
⁃ `org-link-descriptive' is now buffer-local, to avoid interfering
|
||||
with other buffers _Kyle Meyer_
|
||||
⁃ `org-colview' no longer chokes when a special property is updated
|
||||
_Nicolas Goaziou_
|
||||
⁃ Now coderefs have their whitespace cleaned up during tangling _Tom
|
||||
Gillespie_
|
||||
⁃ Allow for multiple `%(expressions)' in `org-agenda-prefix-format'
|
||||
_Ihor Radchenko_
|
||||
⁃ Code cleanup and refactoring _Nicolas Savage, Aaron L. Zeng, Nicolas
|
||||
Goaziou, Bastien Guerry, Stefa Monnier, Arne Babenhauserheid_
|
||||
⁃ Documentation improvements _Jorge Neto, Erik Hetzner, Cheong Yiu
|
||||
Fung, Kyle Meyer_
|
||||
⁃ New `ob-sqlite' maintainer — Nick Savage
|
||||
⁃ Make lilypond header arguments user-configurable _Jamie Bayne_
|
||||
⁃ Fix `ob-C' regression which mixed up `int', `double', and
|
||||
`char*'. Fix another regression with table parameters _tbanel_
|
||||
⁃ Fix indentation of list items and new logbook drawer notes _Bastien
|
||||
Guerry_
|
||||
⁃ Notice when theme changes with LaTeX previews _Yuri Lensky_
|
||||
⁃ Iron out a few edge cases in `ol.el' (Org links) _Nicolas Goaziou_
|
||||
⁃ Some new tests for `org-protocol' _Maxim Nikulin_
|
||||
|
||||
|
||||
|
||||
Footnotes
|
||||
─────────
|
||||
|
||||
[1] Disclosure: this is me.
|
||||
|
|
@ -0,0 +1,424 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-12 Fri 13:39 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>May 2021</title>
|
||||
<meta name="author" content="TEC" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="May 2021" />
|
||||
<meta property="og:description" content="Asynchronous code execution" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="TEC" />
|
||||
<meta property="og:article:published_time" content="2021-05-31T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2021-12-01T17:35:20+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2021-05-31, <span class='acr'>TEC</span></div>
|
||||
|
||||
<h1 class="title">May 2021</h1>
|
||||
<p class="subtitle" role="doc-subtitle">Asynchronous code execution</p>
|
||||
</header><div id="outline-container-async-babel-sessions" class="outline-2">
|
||||
<h2 id="async-babel-sessions">Async Babel sessions have landed<a aria-hidden="true" href="#async-babel-sessions">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-async-babel-sessions">
|
||||
<p>
|
||||
Jack Kamm has made a fantastic contribution to Org: <kbd>ob-comint.el</kbd> now supports
|
||||
asynchronous output from source blocks <i>with full support for sessions</i> 🎉.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
If you haven’t used sessions before, you’re in for a treat! By simply assigning
|
||||
a named session to a source code block, e.g. <kbd>:session foo</kbd>, the same process will
|
||||
be reused for any other code blocks that specify the <kbd>foo</kbd> session. To do this for
|
||||
a certain language across the entire document, you can set the header argument
|
||||
property, i.e.
|
||||
</p>
|
||||
<details id='async-babel-sessions,code--1' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#async-babel-sessions,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-meta-line">#+property: header-args:lang :session foo</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
Along with the asynchronous process communication in <kbd>ob-comint.el</kbd>, we have an
|
||||
implementation for <b>Python</b>, and we should see support for <b>R</b> and <b>Ruby</b> in the
|
||||
not-too-distant future 😍.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
To use this, just add the <kbd>:async</kbd> parameter to a python block. Instead of Emacs
|
||||
freezing until it completes execution, you’ll see a placeholder inserted which is
|
||||
replaced by the result when it is ready.
|
||||
</p>
|
||||
|
||||
<figure>
|
||||
<video width="100%" height="auto" autoplay loop muted class="doom-one">
|
||||
<source src="figures/org-async-python-demo.mp4" type="video/mp4" />
|
||||
</video>
|
||||
<figcaption>
|
||||
<span class="figure-number">Figure 0:</span>
|
||||
A demonstration of the new asyncronous Python execution capabilities.
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
<a href="https://github.com/nnicandro/emacs-jupyter">emacs-jupyter</a> allowed for asynchronous code execution (with sessions), but it’s
|
||||
great to have a solution that doesn’t require Jupyter kernels, and is part of
|
||||
Org.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-font-lock-inline" class="outline-2">
|
||||
<h2 id="font-lock-inline">Font lock for inline export snippets<a aria-hidden="true" href="#font-lock-inline">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-font-lock-inline">
|
||||
<p>
|
||||
Now, this isn’t necessarily a significant change, but I don’t think many people
|
||||
know about this feature so I’ll take the opportunity to go over it 🙂.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
If you want to include a snippet of <span class='acr'>HTML</span>/LaTeX etc. when exporting to that
|
||||
format, you can use a <kbd>#+begin_export html</kbd> block which simply includes the
|
||||
enclosed content verbatim. This doesn’t really work for small inline snippets
|
||||
though — but never fear, Org has <i>inline</i> export snippets which simply follow the
|
||||
form <code class="src src-org"><span class="org-comment">@@</span><span class="org-org-tag">format:</span>content<span class="org-comment">@@</span></code>. For example:
|
||||
</p>
|
||||
|
||||
<details id='font-lock-inline,code--1' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#font-lock-inline,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org">I love using Org to export to <span class="org-comment">@@</span><span class="org-org-tag">html:</span><abbr title="Hyper Text Markup Language">HTML</abbr><span class="org-comment">@@</span> <span class="org-comment">@@</span><span class="org-org-tag">latex:</span>\LaTeX{}<span class="org-comment">@@</span> documents.
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
<p>
|
||||
which will export to <span class='acr'>HTML</span> as,
|
||||
</p>
|
||||
<details id='font-lock-inline,code--2' class='code' open><summary><span class="lang">HTML</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#font-lock-inline,code--2'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-html">I love using Org to export to <<span class="org-function-name">abbr</span> <span class="org-variable-name">title</span>=<span class="org-string">"Hyper Text Markup Language"</span>>HTML</<span class="org-function-name">abbr</span>> documents.
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
<p>
|
||||
and then in LaTeX will be,
|
||||
</p>
|
||||
<details id='font-lock-inline,code--3' class='code' open><summary><span class="lang">LaTeX</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#font-lock-inline,code--3'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-LaTeX">I love using Org to export to <span class="org-keyword">\LaTeX</span>{} documents.
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
<p>
|
||||
isn’t that neat!
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Now you’ll find the <kbd>@@</kbd> parts using the comment face and the <kbd>format:</kbd> bit using the
|
||||
Org tag’s face. It’s a small change, but it makes it easier to see what’s going on.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
No mode-specific syntax highlighting yet, but that may come in the future 😉.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-plot-your-results" class="outline-2">
|
||||
<h2 id="plot-your-results"><kbd>#+plot</kbd> your <kbd>#+results</kbd><a aria-hidden="true" href="#plot-your-results">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-plot-your-results">
|
||||
<p>
|
||||
Org-plot has been getting some more love as of late (see <a href="2021-04-30-export-plot.html">last month’s post</a>), and
|
||||
that hasn’t stopped yet. This month there’s been a fairly minor change that I’m
|
||||
quite a fan of. If you have a source block that produces a table of <kbd>#+results</kbd>, you
|
||||
can now put a <kbd>#+plot</kbd> statement immediately above to get a visualisation of those
|
||||
results!
|
||||
</p>
|
||||
|
||||
<details id='plot-your-results,code--1' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#plot-your-results,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-block-begin-line">#+begin_src python</span>
|
||||
<span class="org-org-block"><span class="org-comment-delimiter"># </span></span><span class="org-org-block"><span class="org-comment">pretend this is some profound source of information</span></span>
|
||||
<span class="org-org-block"><span class="org-keyword">return</span></span><span class="org-org-block"> [[i, i</span><span class="org-org-block"><span class="org-operator">^</span></span><span class="org-org-block">3 </span><span class="org-org-block"><span class="org-operator">-</span></span><span class="org-org-block"> 4</span><span class="org-org-block"><span class="org-operator">*</span></span><span class="org-org-block">i</span><span class="org-org-block"><span class="org-operator">^</span></span><span class="org-org-block">2 </span><span class="org-org-block"><span class="org-operator">-</span></span><span class="org-org-block"> 2</span><span class="org-org-block"><span class="org-operator">*</span></span><span class="org-org-block">i] </span><span class="org-org-block"><span class="org-keyword">for</span></span><span class="org-org-block"> i </span><span class="org-org-block"><span class="org-keyword">in</span></span><span class="org-org-block"> </span><span class="org-org-block"><span class="org-builtin">range</span></span><span class="org-org-block">(5)]</span>
|
||||
<span class="org-org-block-end-line">#+end_src</span>
|
||||
|
||||
<span class="org-org-meta-line">#+plot: ind:1</span>
|
||||
<span class="org-org-meta-line">#+RESULTS:</span>
|
||||
<span class="org-org-table">| 0 | 1 |</span>
|
||||
<span class="org-org-table">| 1 | -2 |</span>
|
||||
<span class="org-org-table">| 2 | 7 |</span>
|
||||
<span class="org-org-table">| 3 | 8 |</span>
|
||||
<span class="org-org-table">| 4 | 13 |</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
As usual, this relies on <kbd>gnuplot</kbd> being present. You can read more
|
||||
about it in the <a href="https://orgmode.org/manual/Org-Plot.html">manual</a>.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-fancier-latex-verses" class="outline-2">
|
||||
<h2 id="fancier-latex-verses">Fancier LaTeX verses<a aria-hidden="true" href="#fancier-latex-verses">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-fancier-latex-verses">
|
||||
<p>
|
||||
With the use of <kbd>verse.sty</kbd> you can now export fancier verses from Org, as verse
|
||||
blocks now support four new attributes:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li><kbd>:lines</kbd> for the numbering interval.</li>
|
||||
<li><kbd>:center</kbd> which can be set to <kbd>t</kbd> and works as long as,
|
||||
<ul class="org-ul">
|
||||
<li><kbd>:versewidth</kbd>, the longest line in the verse as a text string is set.</li>
|
||||
</ul></li>
|
||||
<li>You can also easily add arbitrary LaTeX code to be included with <kbd>:latexcode</kbd>.</li>
|
||||
</ul>
|
||||
|
||||
<details id='fancier-latex-verses,code--1' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#fancier-latex-verses,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-meta-line">#+latex_header: \usepackage{verse}</span>
|
||||
|
||||
<span class="org-org-meta-line">#+latex: \poemtitle{A Dream Within a Dream}</span>
|
||||
<span class="org-org-meta-line">#+attr_latex: :lines 3 :center t</span>
|
||||
<span class="org-org-meta-line">#+attr_latex: :versewidth Through my fingers to the deep,</span>
|
||||
<span class="org-org-block-begin-line">#+begin_verse</span>
|
||||
Take this kiss upon the brow!
|
||||
And, in parting from you now,
|
||||
Thus much let me avow —
|
||||
You are not wrong, who deem
|
||||
That my days have been a dream;
|
||||
Yet if hope has flown away
|
||||
In a night, or in a day,
|
||||
In a vision, or in none,
|
||||
Is it therefore the less <span class="org-italic">/gone?/</span>
|
||||
<span class="org-italic">/All/</span> that we see or seem
|
||||
Is but a dream within a dream.
|
||||
|
||||
I stand amid the roar
|
||||
Of a surf-tormented shore,
|
||||
And I hold within my hand
|
||||
Grains of the golden sand —
|
||||
How few! yet how they creep
|
||||
Through my fingers to the deep,
|
||||
While I weep — while I weep!
|
||||
O God! Can I not grasp
|
||||
Them with a tighter clasp?
|
||||
O God! can I not save
|
||||
<span class="org-italic">/One/</span> from the pitiless wave?
|
||||
Is <span class="org-italic">/all/</span> that we see or seem
|
||||
But a dream within a dream?
|
||||
<span class="org-org-block-end-line">#+end_verse</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
|
||||
<figure id="org4ac285e">
|
||||
<img src="figures/org-verses-example-poem-dream-within-dream.png" alt="org-verses-example-poem-dream-within-dream.png" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 1: </span>A short Poe-em</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-easy-zero-width" class="outline-2">
|
||||
<h2 id="easy-zero-width">Easy zero-width spaces with Org<a aria-hidden="true" href="#easy-zero-width">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-easy-zero-width">
|
||||
<p>
|
||||
Occasionally you may run into annoyances when you wish to have two different Org
|
||||
elements right next to each other (no space) — for example, <b>emph</b>asising part of
|
||||
a word or putting a currency symbol immediately before an inline source block.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The best solution to this in Org is zero-width spaces. As such, I’ve found it
|
||||
rather nice adding insertion of a zero-width space to the <code>org-mode-map</code> in my
|
||||
config. Perhaps some of you might find this solution useful too 🙂.
|
||||
</p>
|
||||
|
||||
<details id='easy-zero-width,code--1' class='code' open><summary><span class="lang">Emacs Lisp</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#easy-zero-width,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-emacs-lisp">(define-key org-mode-map (kbd <span class="org-string">"M-SPC M-SPC"</span>)
|
||||
(<span class="org-keyword">lambda</span> () (<span class="org-keyword">interactive</span>) (insert <span class="org-string">"\u200b"</span>)))
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
Should you want to keep zero-width spaces out of exports, that’s easy enough to
|
||||
accomplish with an <a href="https://orgmode.org/manual/Advanced-Export-Configuration.html">export filter</a>.
|
||||
</p>
|
||||
|
||||
<details id='easy-zero-width,code--2' class='code' open><summary><span class="lang">Emacs Lisp</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#easy-zero-width,code--2'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-emacs-lisp">(<span class="org-keyword">defun</span> <span class="org-function-name">+org-export-remove-zero-width-space</span> (text _backend _info)
|
||||
<span class="org-doc">"Remove zero width spaces from TEXT."</span>
|
||||
(<span class="org-keyword">unless</span> (org-export-derived-backend-p 'org)
|
||||
(replace-regexp-in-string <span class="org-string">"\u200b"</span> <span class="org-string">""</span> text)))
|
||||
|
||||
(add-to-list 'org-export-filter-final-output-functions #'+org-export-remove-zero-width-space t)
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-orgs-repos-have" class="outline-2">
|
||||
<h2 id="orgs-repos-have">Org’s repos have moved<a aria-hidden="true" href="#orgs-repos-have">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-orgs-repos-have">
|
||||
<ul class="org-ul">
|
||||
<li><kbd>contrib/</kbd> is now at <a href="https://git.sr.ht/~bzg/org-contrib">https://git.sr.ht/~bzg/org-contrib</a> for Org 9.5, and it will
|
||||
be available on Non-<span class='acr'>GNU</span> <span class='acr'>ELPA</span>.</li>
|
||||
<li>Worg is now at <a href="https://git.sr.ht/~bzg/worg">https://git.sr.ht/~bzg/worg</a></li>
|
||||
<li>Org itself is moving to Savannah</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-other-improvements" class="outline-2">
|
||||
<h2 id="other-improvements">Other improvements<a aria-hidden="true" href="#other-improvements">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-other-improvements">
|
||||
<ul class="org-ul">
|
||||
<li>Add support for <kbd>HHhMM</kbd> date formats (e.g. <kbd>13h20</kbd>) <span class="underline">Gustavo Barros</span></li>
|
||||
<li>Make tangling faster <i>and</i> more robust <span class="underline">Sébastien Miquel</span></li>
|
||||
<li>Allow importing tables from files that <i>don’t</i> end in <kbd>.txt</kbd>, <kbd>.tsv</kbd>, or <kbd>.csv</kbd>
|
||||
<span class="underline">Utkarsh Singh</span></li>
|
||||
<li>Add an <span class='acr'>SVG</span>-specific post-export <kbd>ob-plantuml</kbd> step:
|
||||
<code>org-babel-plantuml-svg-text-to-path</code> for running Inkscape text-to-path
|
||||
replacement <span class="underline">Nick Daly</span></li>
|
||||
<li>Refactor JavaScript in <kbd>ox-html</kbd> <span class="underline">Anthony Carrico</span></li>
|
||||
<li>Set <code>org-html-head-include-scripts</code> to <code>nil</code> by default (was <code>t</code>) <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Remove LaTeX-environment type <kbd>#+results</kbd> <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>New capture templates parameter, <kbd>:refile-targets</kbd> <span class="underline">Richard Garner</span></li>
|
||||
<li>Merge <code>org-speed-commands-default</code> and <code>org-speed-commands-user</code> into a new
|
||||
variable, <code>org-speed-commands</code> <span class="underline">Bastien Guerry</span></li>
|
||||
<li><span class='acr'>URL</span> recognition regex now handles up to two levels of nested brackets, and is
|
||||
tested <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>Cache parent heading positions for faster movement up buffers. Significantly
|
||||
improves Org queries involving inheritance (~15-50x improvement) <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>New command <code>org-refile-reverse</code> bound to <kbd>C-c C-M-w</kbd> <span class="underline">Adam Spiers</span></li>
|
||||
<li>Allow inline tasks to be dragged up/down <span class="underline">Bastien Guerry</span></li>
|
||||
<li>LaTeX export, allow arbitrary <kbd>:float</kbd> values <span class="underline">Thomas S. Dye</span></li>
|
||||
<li>Org attach git, new option <code>org-attach-git-dir</code> to use the attachment dir as a
|
||||
git repository <span class="underline">Juan Manuel Macías</span></li>
|
||||
<li>Use a write-back buffer in Org src <span class="underline">Sébastien Miquel</span></li>
|
||||
<li>Add the <kbd>:environment</kbd> and <kbd>:options</kbd> LaTeX attributes to Quote blocks <span class="underline">Juan Manuel Macias</span></li>
|
||||
<li>Surround LaTeX <kbd>:options</kbd> attribute with curly braces when it contains square
|
||||
braces <span class="underline">Markus Huber</span></li>
|
||||
<li>Recognise the specific contributions of Kyle Meyer, Ihor Radchenko, and <span class='acr'>TEC</span> in
|
||||
the manual <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Improve test coverage <span class="underline">Ihor Radchenko, Kévin Le Gouguec</span></li>
|
||||
<li>A bikeshed of new maintainers
|
||||
<ul class="org-ul">
|
||||
<li>New maintainer for <kbd>ox-html</kbd> — <span class='acr'>TEC</span></li>
|
||||
<li>New <kbd>ob-ledger</kbd> maintainer — Eric S Fraga</li>
|
||||
<li>New <kbd>ob-awk</kbd> maintainer — Tyler Smith</li>
|
||||
<li>New <kbd>ob-calc</kbd> maintainer — Tom Gillespie</li>
|
||||
<li>New <kbd>ob-asymptote</kbd> and <kbd>ob-coq</kbd> maintainer — Luc Pellissier</li>
|
||||
</ul></li>
|
||||
<li>General code cleanup <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Documentation improvements <span class="underline">Bastien Guerry, Eric S Fraga, Samim Pezeshki,
|
||||
Nicolar Goaziou</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-bugfixes" class="outline-2">
|
||||
<h2 id="bugfixes">Bugfixes<a aria-hidden="true" href="#bugfixes">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-bugfixes">
|
||||
<ul class="org-ul">
|
||||
<li>Make <kbd>ob-gnuplot</kbd> work on remote systems <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>Stop <kbd>M-x org-toggle-link-display</kbd> from affecting emphasis markers <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Inserting a heading before a headline <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Perform <code>org-entry-put</code> in a read-only buffer <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>Emacs 24 compatibility for <kbd>ob-C</kbd> and <code>org-agenda-show-new-time</code> <span class="underline">Kyle Meyer</span></li>
|
||||
<li>Maintain Org’s keybindings when <code>visual-line-mode</code> active <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Keep track of start of region beginning in <code>org-table-wrap-region</code> <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Ensure correct visibility when unfolding subtree <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Corner case in <code>org--backwards-paragaph-once</code> <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Some byte compiler silencing <span class="underline">Kyle Meyer</span></li>
|
||||
<li>Make tags filtering case-sensitive <span class="underline">Bastien Guerry</span></li>
|
||||
<li><kbd>C-c C-c</kbd> on a <kbd>#+plot</kbd> line can no longer cause an error <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Ensure consistent position-translation in <kbd>org-src</kbd> by using point for position
|
||||
instead of column <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>Prevent <kbd>ob-sql</kbd> from getting stuck on an error <span class="underline">Ivan Sokolov</span></li>
|
||||
<li>Make <kbd>org-columns</kbd> respect <code>global-visual-line-mode</code>, and simplify tag scanning
|
||||
<span class="underline">Nick Savage</span></li>
|
||||
<li>Don’t fontify <kbd>::</kbd> in headlines as description item <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>Handle a few corner-cases in <kbd>ob-R</kbd> <span class="underline">Jeremie Juste</span></li>
|
||||
<li>Many fixes to <code>org-indent-line</code> <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Make headline numbering consistent with <span class='acr'>TOC</span> <span class="underline">Mingkai Dong</span></li>
|
||||
<li>Allow read-only tangling again, and ensure the correct filename is used <span class="underline">Sébastien Miquel</span></li>
|
||||
<li>Fix edge case when converting durations to minutes <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Make org-refile work in non-file-visiting buffers <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Be more rigorous in <code>org-sort-remove-invisible</code> <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Don’t update checkbox stats when heading has <kbd>todo</kbd> <kbd>COOKIE_DATA</kbd> <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Don’t recognise a lone <kbd>:END:</kbd> to be forming a drawer <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Allow new footnotes in empty table cells <span class="underline">Nicolas Goaziou</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,228 @@
|
|||
# Created 2024-01-12 Fri 13:39
|
||||
#+title: May 2021
|
||||
#+date: 2021-05-31
|
||||
#+author: TEC
|
||||
#+subtitle: Asynchronous code execution
|
||||
* Async Babel sessions have landed
|
||||
|
||||
Jack Kamm has made a fantastic contribution to Org: =ob-comint.el= now supports
|
||||
asynchronous output from source blocks /with full support for sessions/ 🎉.
|
||||
|
||||
If you haven't used sessions before, you're in for a treat! By simply assigning
|
||||
a named session to a source code block, e.g. =:session foo=, the same process will
|
||||
be reused for any other code blocks that specify the =foo= session. To do this for
|
||||
a certain language across the entire document, you can set the header argument
|
||||
property, i.e.
|
||||
#+begin_src org
|
||||
,#+property: header-args:lang :session foo
|
||||
#+end_src
|
||||
|
||||
Along with the asynchronous process communication in =ob-comint.el=, we have an
|
||||
implementation for *Python*, and we should see support for *R* and *Ruby* in the
|
||||
not-too-distant future 😍.
|
||||
|
||||
To use this, just add the =:async= parameter to a python block. Instead of Emacs
|
||||
freezing until it completes execution, you'll see a placeholder inserted which is
|
||||
replaced by the result when it is ready.
|
||||
|
||||
[[https://github.com/nnicandro/emacs-jupyter][emacs-jupyter]] allowed for asynchronous code execution (with sessions), but it's
|
||||
great to have a solution that doesn't require Jupyter kernels, and is part of
|
||||
Org.
|
||||
* Font lock for inline export snippets
|
||||
|
||||
Now, this isn't necessarily a significant change, but I don't think many people
|
||||
know about this feature so I'll take the opportunity to go over it 🙂.
|
||||
|
||||
If you want to include a snippet of HTML/LaTeX etc. when exporting to that
|
||||
format, you can use a =#+begin_export html= block which simply includes the
|
||||
enclosed content verbatim. This doesn't really work for small inline snippets
|
||||
though --- but never fear, Org has /inline/ export snippets which simply follow the
|
||||
form src_org{@@format:content@@}. For example:
|
||||
|
||||
#+begin_src org
|
||||
I love using Org to export to @@html:<abbr title="Hyper Text Markup Language">HTML</abbr>@@ @@latex:\LaTeX{}@@ documents.
|
||||
#+end_src
|
||||
which will export to HTML as,
|
||||
#+begin_src html
|
||||
I love using Org to export to <abbr title="Hyper Text Markup Language">HTML</abbr> documents.
|
||||
#+end_src
|
||||
and then in LaTeX will be,
|
||||
#+begin_src LaTeX
|
||||
I love using Org to export to \LaTeX{} documents.
|
||||
#+end_src
|
||||
isn't that neat!
|
||||
|
||||
Now you'll find the =@@= parts using the comment face and the =format:= bit using the
|
||||
Org tag's face. It's a small change, but it makes it easier to see what's going on.
|
||||
|
||||
No mode-specific syntax highlighting yet, but that may come in the future 😉.
|
||||
* =#+plot= your =#+results=
|
||||
|
||||
Org-plot has been getting some more love as of late (see [[file:2021-04-30-export-plot.org][last month's post]]), and
|
||||
that hasn't stopped yet. This month there's been a fairly minor change that I'm
|
||||
quite a fan of. If you have a source block that produces a table of =#+results=, you
|
||||
can now put a =#+plot= statement immediately above to get a visualisation of those
|
||||
results!
|
||||
|
||||
#+begin_src org
|
||||
,#+begin_src python
|
||||
# pretend this is some profound source of information
|
||||
return [[i, i^3 - 4*i^2 - 2*i] for i in range(5)]
|
||||
,#+end_src
|
||||
|
||||
,#+plot: ind:1
|
||||
,#+RESULTS:
|
||||
| 0 | 1 |
|
||||
| 1 | -2 |
|
||||
| 2 | 7 |
|
||||
| 3 | 8 |
|
||||
| 4 | 13 |
|
||||
#+end_src
|
||||
|
||||
As usual, this relies on =gnuplot= being present. You can read more
|
||||
about it in the [[https://orgmode.org/manual/Org-Plot.html][manual]].
|
||||
* Fancier LaTeX verses
|
||||
|
||||
With the use of =verse.sty= you can now export fancier verses from Org, as verse
|
||||
blocks now support four new attributes:
|
||||
- =:lines= for the numbering interval.
|
||||
- =:center= which can be set to =t= and works as long as,
|
||||
- =:versewidth=, the longest line in the verse as a text string is set.
|
||||
- You can also easily add arbitrary LaTeX code to be included with =:latexcode=.
|
||||
|
||||
#+begin_src org
|
||||
,#+latex_header: \usepackage{verse}
|
||||
|
||||
,#+latex: \poemtitle{A Dream Within a Dream}
|
||||
,#+attr_latex: :lines 3 :center t
|
||||
,#+attr_latex: :versewidth Through my fingers to the deep,
|
||||
,#+begin_verse
|
||||
Take this kiss upon the brow!
|
||||
And, in parting from you now,
|
||||
Thus much let me avow —
|
||||
You are not wrong, who deem
|
||||
That my days have been a dream;
|
||||
Yet if hope has flown away
|
||||
In a night, or in a day,
|
||||
In a vision, or in none,
|
||||
Is it therefore the less /gone?/
|
||||
/All/ that we see or seem
|
||||
Is but a dream within a dream.
|
||||
|
||||
I stand amid the roar
|
||||
Of a surf-tormented shore,
|
||||
And I hold within my hand
|
||||
Grains of the golden sand —
|
||||
How few! yet how they creep
|
||||
Through my fingers to the deep,
|
||||
While I weep — while I weep!
|
||||
O God! Can I not grasp
|
||||
Them with a tighter clasp?
|
||||
O God! can I not save
|
||||
/One/ from the pitiless wave?
|
||||
Is /all/ that we see or seem
|
||||
But a dream within a dream?
|
||||
,#+end_verse
|
||||
#+end_src
|
||||
|
||||
#+caption: A short Poe-em
|
||||
[[file:figures/org-verses-example-poem-dream-within-dream.png]]
|
||||
* Easy zero-width spaces with Org
|
||||
|
||||
Occasionally you may run into annoyances when you wish to have two different Org
|
||||
elements right next to each other (no space) --- for example, *emph*asising part of
|
||||
a word or putting a currency symbol immediately before an inline source block.
|
||||
|
||||
The best solution to this in Org is zero-width spaces. As such, I've found it
|
||||
rather nice adding insertion of a zero-width space to the ~org-mode-map~ in my
|
||||
config. Perhaps some of you might find this solution useful too 🙂.
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(define-key org-mode-map (kbd "M-SPC M-SPC")
|
||||
(lambda () (interactive) (insert "\u200b")))
|
||||
#+end_src
|
||||
|
||||
Should you want to keep zero-width spaces out of exports, that's easy enough to
|
||||
accomplish with an [[https://orgmode.org/manual/Advanced-Export-Configuration.html][export filter]].
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(defun +org-export-remove-zero-width-space (text _backend _info)
|
||||
"Remove zero width spaces from TEXT."
|
||||
(unless (org-export-derived-backend-p 'org)
|
||||
(replace-regexp-in-string "\u200b" "" text)))
|
||||
|
||||
(add-to-list 'org-export-filter-final-output-functions #'+org-export-remove-zero-width-space t)
|
||||
#+end_src
|
||||
* Org's repos have moved
|
||||
- =contrib/= is now at https://git.sr.ht/~bzg/org-contrib for Org 9.5, and it will
|
||||
be available on Non-GNU ELPA.
|
||||
- Worg is now at https://git.sr.ht/~bzg/worg
|
||||
- Org itself is moving to Savannah
|
||||
* Other improvements
|
||||
- Add support for =HHhMM= date formats (e.g. =13h20=) _Gustavo Barros_
|
||||
- Make tangling faster /and/ more robust _Sébastien Miquel_
|
||||
- Allow importing tables from files that /don't/ end in =.txt=, =.tsv=, or =.csv=
|
||||
_Utkarsh Singh_
|
||||
- Add an SVG-specific post-export =ob-plantuml= step:
|
||||
~org-babel-plantuml-svg-text-to-path~ for running Inkscape text-to-path
|
||||
replacement _Nick Daly_
|
||||
- Refactor JavaScript in =ox-html= _Anthony Carrico_
|
||||
- Set ~org-html-head-include-scripts~ to ~nil~ by default (was ~t~) _Bastien Guerry_
|
||||
- Remove LaTeX-environment type =#+results= _TEC_
|
||||
- New capture templates parameter, =:refile-targets= _Richard Garner_
|
||||
- Merge ~org-speed-commands-default~ and ~org-speed-commands-user~ into a new
|
||||
variable, ~org-speed-commands~ _Bastien Guerry_
|
||||
- URL recognition regex now handles up to two levels of nested brackets, and is
|
||||
tested _Ihor Radchenko_
|
||||
- Cache parent heading positions for faster movement up buffers. Significantly
|
||||
improves Org queries involving inheritance (~15-50x improvement) _Ihor Radchenko_
|
||||
- New command ~org-refile-reverse~ bound to =C-c C-M-w= _Adam Spiers_
|
||||
- Allow inline tasks to be dragged up/down _Bastien Guerry_
|
||||
- LaTeX export, allow arbitrary =:float= values _Thomas S. Dye_
|
||||
- Org attach git, new option ~org-attach-git-dir~ to use the attachment dir as a
|
||||
git repository _Juan Manuel Macías_
|
||||
- Use a write-back buffer in Org src _Sébastien Miquel_
|
||||
- Add the =:environment= and =:options= LaTeX attributes to Quote blocks _Juan Manuel Macias_
|
||||
- Surround LaTeX =:options= attribute with curly braces when it contains square
|
||||
braces _Markus Huber_
|
||||
- Recognise the specific contributions of Kyle Meyer, Ihor Radchenko, and TEC in
|
||||
the manual _Bastien Guerry_
|
||||
- Improve test coverage _Ihor Radchenko, Kévin Le Gouguec_
|
||||
- A bikeshed of new maintainers
|
||||
- New maintainer for =ox-html= --- TEC
|
||||
- New =ob-ledger= maintainer --- Eric S Fraga
|
||||
- New =ob-awk= maintainer --- Tyler Smith
|
||||
- New =ob-calc= maintainer --- Tom Gillespie
|
||||
- New =ob-asymptote= and =ob-coq= maintainer --- Luc Pellissier
|
||||
- General code cleanup _Bastien Guerry_
|
||||
- Documentation improvements _Bastien Guerry, Eric S Fraga, Samim Pezeshki,
|
||||
Nicolar Goaziou_
|
||||
* Bugfixes
|
||||
- Make =ob-gnuplot= work on remote systems _Ihor Radchenko_
|
||||
- Stop =M-x org-toggle-link-display= from affecting emphasis markers _Bastien Guerry_
|
||||
- Inserting a heading before a headline _Bastien Guerry_
|
||||
- Perform ~org-entry-put~ in a read-only buffer _Ihor Radchenko_
|
||||
- Emacs 24 compatibility for =ob-C= and ~org-agenda-show-new-time~ _Kyle Meyer_
|
||||
- Maintain Org's keybindings when ~visual-line-mode~ active _Bastien Guerry_
|
||||
- Keep track of start of region beginning in ~org-table-wrap-region~ _Bastien Guerry_
|
||||
- Ensure correct visibility when unfolding subtree _Bastien Guerry_
|
||||
- Corner case in ~org--backwards-paragaph-once~ _Bastien Guerry_
|
||||
- Some byte compiler silencing _Kyle Meyer_
|
||||
- Make tags filtering case-sensitive _Bastien Guerry_
|
||||
- =C-c C-c= on a =#+plot= line can no longer cause an error _Bastien Guerry_
|
||||
- Ensure consistent position-translation in =org-src= by using point for position
|
||||
instead of column _TEC_
|
||||
- Prevent =ob-sql= from getting stuck on an error _Ivan Sokolov_
|
||||
- Make =org-columns= respect ~global-visual-line-mode~, and simplify tag scanning
|
||||
_Nick Savage_
|
||||
- Don't fontify =::= in headlines as description item _Ihor Radchenko_
|
||||
- Handle a few corner-cases in =ob-R= _Jeremie Juste_
|
||||
- Many fixes to ~org-indent-line~ _Bastien Guerry_
|
||||
- Make headline numbering consistent with TOC _Mingkai Dong_
|
||||
- Allow read-only tangling again, and ensure the correct filename is used _Sébastien Miquel_
|
||||
- Fix edge case when converting durations to minutes _Nicolas Goaziou_
|
||||
- Make org-refile work in non-file-visiting buffers _Bastien Guerry_
|
||||
- Be more rigorous in ~org-sort-remove-invisible~ _Nicolas Goaziou_
|
||||
- Don't update checkbox stats when heading has =todo= =COOKIE_DATA= _Bastien Guerry_
|
||||
- Don't recognise a lone =:END:= to be forming a drawer _Nicolas Goaziou_
|
||||
- Allow new footnotes in empty table cells _Nicolas Goaziou_
|
||||
|
|
@ -0,0 +1,369 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>2021-05-31-async.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">May 2021
|
||||
</span><span style="color: #9e9e9e;">#+subtitle:</span> Asynchronous code execution
|
||||
<span style="color: #9e9e9e;">#+author:</span> TEC
|
||||
<span style="color: #9e9e9e;">#+date:</span> 2021-05-31
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Async Babel sessions have landed</span>
|
||||
|
||||
Jack Kamm has made a fantastic contribution to Org: <span style="color: #9e9e9e;">=ob-comint.el=</span> now supports
|
||||
asynchronous output from source blocks <span class="ef-i">/with full support for sessions/</span> 🎉.
|
||||
|
||||
If you haven't used sessions before, you're in for a treat! By simply assigning
|
||||
a named session to a source code block, e.g. <span style="color: #9e9e9e;">=:session foo=</span>, the same process will
|
||||
be reused for any other code blocks that specify the <span style="color: #9e9e9e;">=foo=</span> session. To do this for
|
||||
a certain language across the entire document, you can set the header argument
|
||||
property, i.e.
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+property: header-args:lang :session foo
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
Along with the asynchronous process communication in <span style="color: #9e9e9e;">=ob-comint.el=</span>, we have an
|
||||
implementation for <span class="ef-b">*Python*</span>, and we should see support for <span class="ef-b">*R*</span> and <span class="ef-b">*Ruby*</span> in the
|
||||
not-too-distant future 😍.
|
||||
|
||||
To use this, just add the <span style="color: #9e9e9e;">=:async=</span> parameter to a python block. Instead of Emacs
|
||||
freezing until it completes execution, you'll see a placeholder inserted which is
|
||||
replaced by the result when it is ready.
|
||||
|
||||
<span class="ef-obb">#+begin_export html
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;"><figure>
|
||||
<video width="100%" height="auto" autoplay loop muted class="doom-one">
|
||||
<source src="figures/org-async-python-demo.mp4" type="video/mp4" />
|
||||
</video>
|
||||
<figcaption>
|
||||
<span class="figure-number">Figure 0:</span>
|
||||
A demonstration of the new asyncronous Python execution capabilities.
|
||||
</figcaption>
|
||||
</figure>
|
||||
</span><span class="ef-obe">#+end_export
|
||||
</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/nnicandro/emacs-jupyter][emacs-jupyter]]</span> allowed for asynchronous code execution (with sessions), but it's
|
||||
great to have a solution that doesn't require Jupyter kernels, and is part of
|
||||
Org.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Font lock for inline export snippets</span>
|
||||
|
||||
Now, this isn't necessarily a significant change, but I don't think many people
|
||||
know about this feature so I'll take the opportunity to go over it 🙂.
|
||||
|
||||
If you want to include a snippet of HTML/LaTeX etc. when exporting to that
|
||||
format, you can use a <span style="color: #9e9e9e;">=#+begin_export html=</span> block which simply includes the
|
||||
enclosed content verbatim. This doesn't really work for small inline snippets
|
||||
though --- but never fear, Org has <span class="ef-i">/inline/</span> export snippets which simply follow the
|
||||
form <span style="color: #9e9e9e; background-color: #e0e0e0;">src_</span><span style="color: #b1b1b1; background-color: #e0e0e0;">org</span><span style="color: #9e9e9e; background-color: #e0e0e0;">{</span><span style="color: #b1b1b1; background-color: #e0e0e0;">@@</span><span style="color: #9e9e9e; background-color: #e0e0e0; font-weight: 700;">format:</span><span class="ef-ob">content</span><span style="color: #b1b1b1; background-color: #e0e0e0;">@@</span><span style="color: #9e9e9e; background-color: #e0e0e0;">}</span>. For example:
|
||||
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">I love using Org to export to </span><span style="color: #b1b1b1; background-color: #e0e0e0;">@@</span><span style="color: #9e9e9e; background-color: #e0e0e0; font-weight: 700;">html:</span><span class="ef-ob"><abbr title="Hyper Text Markup Language">HTML</abbr></span><span style="color: #b1b1b1; background-color: #e0e0e0;">@@</span> <span style="color: #b1b1b1; background-color: #e0e0e0;">@@</span><span style="color: #9e9e9e; background-color: #e0e0e0; font-weight: 700;">latex:</span><span class="ef-ob">\LaTeX{}</span><span style="color: #b1b1b1; background-color: #e0e0e0;">@@</span><span class="ef-ob"> documents.
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>which will export to HTML as,
|
||||
<span class="ef-obb">#+begin_src html
|
||||
</span><span class="ef-ob">I love using Org to export to <</span><span style="color: #29838d; background-color: #e0e0e0;">abbr</span> <span style="color: #cb9aad; background-color: #e0e0e0;">title</span><span class="ef-ob">=</span><span style="color: #4f894c; background-color: #e0e0e0;">"Hyper Text Markup Language"</span><span class="ef-ob">>HTML</</span><span style="color: #29838d; background-color: #e0e0e0;">abbr</span><span class="ef-ob">> documents.
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>and then in LaTeX will be,
|
||||
<span class="ef-obb">#+begin_src LaTeX
|
||||
</span><span class="ef-ob">I love using Org to export to </span><span style="color: #3b6ea8; background-color: #e0e0e0;">\LaTeX</span><span class="ef-ob">{} documents.
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>isn't that neat!
|
||||
|
||||
Now you'll find the <span style="color: #9e9e9e;">=@@=</span> parts using the comment face and the <span style="color: #9e9e9e;">=format:=</span> bit using the
|
||||
Org tag's face. It's a small change, but it makes it easier to see what's going on.
|
||||
|
||||
No mode-specific syntax highlighting yet, but that may come in the future 😉.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* </span><span style="color: #9e9e9e; font-weight: nil; font-size: 1.25em">=#+plot=</span><span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em"> your </span><span style="color: #9e9e9e; font-weight: nil; font-size: 1.25em">=#+results=</span>
|
||||
|
||||
Org-plot has been getting some more love as of late (see <span style="color: #3b6ea8; font-weight: 700;">[[file:2021-04-30-export-plot.org][last month's post]]</span>), and
|
||||
that hasn't stopped yet. This month there's been a fairly minor change that I'm
|
||||
quite a fan of. If you have a source block that produces a table of <span style="color: #9e9e9e;">=#+results=</span>, you
|
||||
can now put a <span style="color: #9e9e9e;">=#+plot=</span> statement immediately above to get a visualisation of those
|
||||
results!
|
||||
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+begin_src python
|
||||
</span><span style="color: #b1b1b1; background-color: #e0e0e0;"># pretend this is some profound source of information</span><span class="ef-ob">
|
||||
return [[i, i^3 - 4*i^2 - 2*i] for i in range(5)]
|
||||
,#+end_src
|
||||
|
||||
,#+plot: ind:1
|
||||
,#+RESULTS:
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;">| 0 | 1 |</span>
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">| 1 | -2 |</span>
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">| 2 | 7 |</span>
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">| 3 | 8 |</span>
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">| 4 | 13 |</span>
|
||||
<span class="ef-obe">#+end_src
|
||||
</span>
|
||||
As usual, this relies on <span style="color: #9e9e9e;">=gnuplot=</span> being present. You can read more
|
||||
about it in the <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/manual/Org-Plot.html][manual]]</span>.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Fancier LaTeX verses</span>
|
||||
|
||||
With the use of <span style="color: #9e9e9e;">=verse.sty=</span> you can now export fancier verses from Org, as verse
|
||||
blocks now support four new attributes:
|
||||
+ <span style="color: #9e9e9e;">=:lines=</span> for the numbering interval.
|
||||
+ <span style="color: #9e9e9e;">=:center=</span> which can be set to <span style="color: #9e9e9e;">=t=</span> and works as long as,
|
||||
- <span style="color: #9e9e9e;">=:versewidth=</span>, the longest line in the verse as a text string is set.
|
||||
+ You can also easily add arbitrary LaTeX code to be included with <span style="color: #9e9e9e;">=:latexcode=</span>.
|
||||
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+latex_header: \usepackage{verse}
|
||||
|
||||
,#+latex: \poemtitle{A Dream Within a Dream}
|
||||
,#+attr_latex: :lines 3 :center t
|
||||
,#+attr_latex: :versewidth Through my fingers to the deep,
|
||||
,#+begin_verse
|
||||
Take this kiss upon the brow!
|
||||
And, in parting from you now,
|
||||
Thus much let me avow —
|
||||
You are not wrong, who deem
|
||||
That my days have been a dream;
|
||||
Yet if hope has flown away
|
||||
In a night, or in a day,
|
||||
In a vision, or in none,
|
||||
Is it therefore the less </span><span style="color: #9e9e9e; background-color: #e0e0e0; text-decoration: italic;">/gone?/</span>
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0; text-decoration: italic;">/All/</span><span class="ef-ob"> that we see or seem
|
||||
Is but a dream within a dream.
|
||||
|
||||
I stand amid the roar
|
||||
Of a surf-tormented shore,
|
||||
And I hold within my hand
|
||||
Grains of the golden sand —
|
||||
How few! yet how they creep
|
||||
Through my fingers to the deep,
|
||||
While I weep — while I weep!
|
||||
O God! Can I not grasp
|
||||
Them with a tighter clasp?
|
||||
O God! can I not save
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0; text-decoration: italic;">/One/</span><span class="ef-ob"> from the pitiless wave?
|
||||
Is </span><span style="color: #9e9e9e; background-color: #e0e0e0; text-decoration: italic;">/all/</span><span class="ef-ob"> that we see or seem
|
||||
But a dream within a dream?
|
||||
,#+end_verse
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">A short Poe-em</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/org-verses-example-poem-dream-within-dream.png]]</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Easy zero-width spaces with Org</span>
|
||||
|
||||
Occasionally you may run into annoyances when you wish to have two different Org
|
||||
elements right next to each other (no space) --- for example, <span class="ef-b">*emph*</span>asising part of
|
||||
a word or putting a currency symbol immediately before an inline source block.
|
||||
|
||||
The best solution to this in Org is zero-width spaces. As such, I've found it
|
||||
rather nice adding insertion of a zero-width space to the <span style="color: #9e9e9e;">~org-mode-map~</span> in my
|
||||
config. Perhaps some of you might find this solution useful too 🙂.
|
||||
|
||||
<span class="ef-obb">#+begin_src emacs-lisp
|
||||
</span><span class="ef-ob">(define-key org-mode-map (kbd </span><span style="color: #4f894c; background-color: #e0e0e0;">"M-SPC M-SPC"</span><span class="ef-ob">)
|
||||
(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">lambda</span><span class="ef-ob"> () (</span><span style="color: #3b6ea8; background-color: #e0e0e0;">interactive</span><span class="ef-ob">) (insert </span><span style="color: #4f894c; background-color: #e0e0e0;">"\u200b"</span><span class="ef-ob">)))
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
Should you want to keep zero-width spaces out of exports, that's easy enough to
|
||||
accomplish with an <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/manual/Advanced-Export-Configuration.html][export filter]]</span>.
|
||||
|
||||
<span class="ef-obb">#+begin_src emacs-lisp
|
||||
</span><span class="ef-ob">(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">defun</span> <span style="color: #29838d; background-color: #e0e0e0;">+org-export-remove-zero-width-space</span><span class="ef-ob"> (text _backend _info)
|
||||
</span><span style="color: #b6b6b6; background-color: #e0e0e0;">"Remove zero width spaces from TEXT."</span><span class="ef-ob">
|
||||
(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">unless</span><span class="ef-ob"> (org-export-derived-backend-p 'org)
|
||||
(replace-regexp-in-string </span><span style="color: #4f894c; background-color: #e0e0e0;">"\u200b"</span> <span style="color: #4f894c; background-color: #e0e0e0;">""</span><span class="ef-ob"> text)))
|
||||
|
||||
(add-to-list 'org-export-filter-final-output-functions #'+org-export-remove-zero-width-space t)
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Org's repos have moved</span>
|
||||
+ <span style="color: #9e9e9e;">=contrib/=</span> is now at <span style="color: #3b6ea8; font-weight: 700;">https://git.sr.ht/~bzg/org-contrib</span> for Org 9.5, and it will
|
||||
be available on Non-GNU ELPA.
|
||||
+ Worg is now at <span style="color: #3b6ea8; font-weight: 700;">https://git.sr.ht/~bzg/worg</span>
|
||||
+ Org itself is moving to Savannah
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Other improvements</span>
|
||||
+ Add support for <span style="color: #9e9e9e;">=HHhMM=</span> date formats (e.g. <span style="color: #9e9e9e;">=13h20=</span>) _Gustavo Barros_
|
||||
+ Make tangling faster <span class="ef-i">/and/</span> more robust _Sébastien Miquel_
|
||||
+ Allow importing tables from files that <span class="ef-i">/don't/</span> end in <span style="color: #9e9e9e;">=.txt=</span>, <span style="color: #9e9e9e;">=.tsv=</span>, or <span style="color: #9e9e9e;">=.csv=</span>
|
||||
_Utkarsh Singh_
|
||||
+ Add an SVG-specific post-export <span style="color: #9e9e9e;">=ob-plantuml=</span> step:
|
||||
<span style="color: #9e9e9e;">~org-babel-plantuml-svg-text-to-path~</span> for running Inkscape text-to-path
|
||||
replacement _Nick Daly_
|
||||
+ Refactor JavaScript in <span style="color: #9e9e9e;">=ox-html=</span> _Anthony Carrico_
|
||||
+ Set <span style="color: #9e9e9e;">~org-html-head-include-scripts~</span> to <span style="color: #9e9e9e;">~nil~</span> by default (was <span style="color: #9e9e9e;">~t~</span>) _Bastien Guerry_
|
||||
+ Remove LaTeX-environment type <span style="color: #9e9e9e;">=#+results=</span> _TEC_
|
||||
+ New capture templates parameter, <span style="color: #9e9e9e;">=:refile-targets=</span> _Richard Garner_
|
||||
+ Merge <span style="color: #9e9e9e;">~org-speed-commands-default~</span> and <span style="color: #9e9e9e;">~org-speed-commands-user~</span> into a new
|
||||
variable, <span style="color: #9e9e9e;">~org-speed-commands~</span> _Bastien Guerry_
|
||||
+ URL recognition regex now handles up to two levels of nested brackets, and is
|
||||
tested _Ihor Radchenko_
|
||||
+ Cache parent heading positions for faster movement up buffers. Significantly
|
||||
improves Org queries involving inheritance (~15-50x improvement) _Ihor Radchenko_
|
||||
+ New command <span style="color: #9e9e9e;">~org-refile-reverse~</span> bound to <span style="color: #9e9e9e;">=C-c C-M-w=</span> _Adam Spiers_
|
||||
+ Allow inline tasks to be dragged up/down _Bastien Guerry_
|
||||
+ LaTeX export, allow arbitrary <span style="color: #9e9e9e;">=:float=</span> values _Thomas S. Dye_
|
||||
+ Org attach git, new option <span style="color: #9e9e9e;">~org-attach-git-dir~</span> to use the attachment dir as a
|
||||
git repository _Juan Manuel Macías_
|
||||
+ Use a write-back buffer in Org src _Sébastien Miquel_
|
||||
+ Add the <span style="color: #9e9e9e;">=:environment=</span> and <span style="color: #9e9e9e;">=:options=</span> LaTeX attributes to Quote blocks _Juan Manuel Macias_
|
||||
+ Surround LaTeX <span style="color: #9e9e9e;">=:options=</span> attribute with curly braces when it contains square
|
||||
braces _Markus Huber_
|
||||
+ Recognise the specific contributions of Kyle Meyer, Ihor Radchenko, and TEC in
|
||||
the manual _Bastien Guerry_
|
||||
+ Improve test coverage _Ihor Radchenko, Kévin Le Gouguec_
|
||||
+ A bikeshed of new maintainers
|
||||
- New maintainer for <span style="color: #9e9e9e;">=ox-html=</span> --- TEC
|
||||
- New <span style="color: #9e9e9e;">=ob-ledger=</span> maintainer --- Eric S Fraga
|
||||
- New <span style="color: #9e9e9e;">=ob-awk=</span> maintainer --- Tyler Smith
|
||||
- New <span style="color: #9e9e9e;">=ob-calc=</span> maintainer --- Tom Gillespie
|
||||
- New <span style="color: #9e9e9e;">=ob-asymptote=</span> and <span style="color: #9e9e9e;">=ob-coq=</span> maintainer --- Luc Pellissier
|
||||
+ General code cleanup _Bastien Guerry_
|
||||
+ Documentation improvements _Bastien Guerry, Eric S Fraga, Samim Pezeshki,
|
||||
Nicolar Goaziou_
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Bugfixes</span>
|
||||
+ Make <span style="color: #9e9e9e;">=ob-gnuplot=</span> work on remote systems _Ihor Radchenko_
|
||||
+ Stop <span style="color: #9e9e9e;">=M-x org-toggle-link-display=</span> from affecting emphasis markers _Bastien Guerry_
|
||||
+ Inserting a heading before a headline _Bastien Guerry_
|
||||
+ Perform <span style="color: #9e9e9e;">~org-entry-put~</span> in a read-only buffer _Ihor Radchenko_
|
||||
+ Emacs 24 compatibility for <span style="color: #9e9e9e;">=ob-C=</span> and <span style="color: #9e9e9e;">~org-agenda-show-new-time~</span> _Kyle Meyer_
|
||||
+ Maintain Org's keybindings when <span style="color: #9e9e9e;">~visual-line-mode~</span> active _Bastien Guerry_
|
||||
+ Keep track of start of region beginning in <span style="color: #9e9e9e;">~org-table-wrap-region~</span> _Bastien Guerry_
|
||||
+ Ensure correct visibility when unfolding subtree _Bastien Guerry_
|
||||
+ Corner case in <span style="color: #9e9e9e;">~org--backwards-paragaph-once~</span> _Bastien Guerry_
|
||||
+ Some byte compiler silencing _Kyle Meyer_
|
||||
+ Make tags filtering case-sensitive _Bastien Guerry_
|
||||
+ <span style="color: #9e9e9e;">=C-c C-c=</span> on a <span style="color: #9e9e9e;">=#+plot=</span> line can no longer cause an error _Bastien Guerry_
|
||||
+ Ensure consistent position-translation in <span style="color: #9e9e9e;">=org-src=</span> by using point for position
|
||||
instead of column _TEC_
|
||||
+ Prevent <span style="color: #9e9e9e;">=ob-sql=</span> from getting stuck on an error _Ivan Sokolov_
|
||||
+ Make <span style="color: #9e9e9e;">=org-columns=</span> respect <span style="color: #9e9e9e;">~global-visual-line-mode~</span>, and simplify tag scanning
|
||||
_Nick Savage_
|
||||
+ Don't fontify <span style="color: #9e9e9e;">=::=</span> in headlines as description item _Ihor Radchenko_
|
||||
+ Handle a few corner-cases in <span style="color: #9e9e9e;">=ob-R=</span> _Jeremie Juste_
|
||||
+ Many fixes to <span style="color: #9e9e9e;">~org-indent-line~</span> _Bastien Guerry_
|
||||
+ Make headline numbering consistent with TOC _Mingkai Dong_
|
||||
+ Allow read-only tangling again, and ensure the correct filename is used _Sébastien Miquel_
|
||||
+ Fix edge case when converting durations to minutes _Nicolas Goaziou_
|
||||
+ Make org-refile work in non-file-visiting buffers _Bastien Guerry_
|
||||
+ Be more rigorous in <span style="color: #9e9e9e;">~org-sort-remove-invisible~</span> _Nicolas Goaziou_
|
||||
+ Don't update checkbox stats when heading has <span style="color: #9e9e9e;">=todo=</span> <span style="color: #9e9e9e;">=COOKIE_DATA=</span> _Bastien Guerry_
|
||||
+ Don't recognise a lone <span style="color: #9e9e9e;">=:END:=</span> to be forming a drawer _Nicolas Goaziou_
|
||||
+ Allow new footnotes in empty table cells _Nicolas Goaziou_
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,291 @@
|
|||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
MAY 2021
|
||||
Asynchronous code execution
|
||||
|
||||
TEC
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
|
||||
2021-05-31
|
||||
|
||||
|
||||
Async Babel sessions have landed
|
||||
════════════════════════════════
|
||||
|
||||
Jack Kamm has made a fantastic contribution to Org: `ob-comint.el' now
|
||||
supports asynchronous output from source blocks /with full support for
|
||||
sessions/ 🎉.
|
||||
|
||||
If you haven’t used sessions before, you’re in for a treat! By simply
|
||||
assigning a named session to a source code block, e.g. `:session foo',
|
||||
the same process will be reused for any other code blocks that specify
|
||||
the `foo' session. To do this for a certain language across the entire
|
||||
document, you can set the header argument property, i.e.
|
||||
┌────
|
||||
│ #+property: header-args:lang :session foo
|
||||
└────
|
||||
|
||||
Along with the asynchronous process communication in `ob-comint.el',
|
||||
we have an implementation for *Python*, and we should see support for
|
||||
*R* and *Ruby* in the not-too-distant future 😍.
|
||||
|
||||
To use this, just add the `:async' parameter to a python
|
||||
block. Instead of Emacs freezing until it completes execution, you’ll
|
||||
see a placeholder inserted which is replaced by the result when it is
|
||||
ready.
|
||||
|
||||
[emacs-jupyter] allowed for asynchronous code execution (with
|
||||
sessions), but it’s great to have a solution that doesn’t require
|
||||
Jupyter kernels, and is part of Org.
|
||||
|
||||
|
||||
[emacs-jupyter] <https://github.com/nnicandro/emacs-jupyter>
|
||||
|
||||
|
||||
Font lock for inline export snippets
|
||||
════════════════════════════════════
|
||||
|
||||
Now, this isn’t necessarily a significant change, but I don’t think
|
||||
many people know about this feature so I’ll take the opportunity to go
|
||||
over it 🙂.
|
||||
|
||||
If you want to include a snippet of HTML/LaTeX etc. when exporting to
|
||||
that format, you can use a `#+begin_export html' block which simply
|
||||
includes the enclosed content verbatim. This doesn’t really work for
|
||||
small inline snippets though — but never fear, Org has /inline/ export
|
||||
snippets which simply follow the form `@@format:content@@'. For
|
||||
example:
|
||||
|
||||
┌────
|
||||
│ I love using Org to export to @@html:<abbr title="Hyper Text Markup Language">HTML</abbr>@@ @@latex:\LaTeX{}@@ documents.
|
||||
└────
|
||||
which will export to HTML as,
|
||||
┌────
|
||||
│ I love using Org to export to <abbr title="Hyper Text Markup Language">HTML</abbr> documents.
|
||||
└────
|
||||
and then in LaTeX will be,
|
||||
┌────
|
||||
│ I love using Org to export to \LaTeX{} documents.
|
||||
└────
|
||||
isn’t that neat!
|
||||
|
||||
Now you’ll find the `@@' parts using the comment face and the
|
||||
`format:' bit using the Org tag’s face. It’s a small change, but it
|
||||
makes it easier to see what’s going on.
|
||||
|
||||
No mode-specific syntax highlighting yet, but that may come in the
|
||||
future 😉.
|
||||
|
||||
|
||||
`#+plot' your `#+results'
|
||||
═════════════════════════
|
||||
|
||||
Org-plot has been getting some more love as of late (see [last month’s
|
||||
post]), and that hasn’t stopped yet. This month there’s been a fairly
|
||||
minor change that I’m quite a fan of. If you have a source block that
|
||||
produces a table of `#+results', you can now put a `#+plot' statement
|
||||
immediately above to get a visualisation of those results!
|
||||
|
||||
┌────
|
||||
│ #+begin_src python
|
||||
│ # pretend this is some profound source of information
|
||||
│ return [[i, i^3 - 4*i^2 - 2*i] for i in range(5)]
|
||||
│ #+end_src
|
||||
│
|
||||
│ #+plot: ind:1
|
||||
│ #+RESULTS:
|
||||
│ | 0 | 1 |
|
||||
│ | 1 | -2 |
|
||||
│ | 2 | 7 |
|
||||
│ | 3 | 8 |
|
||||
│ | 4 | 13 |
|
||||
└────
|
||||
|
||||
As usual, this relies on `gnuplot' being present. You can read more
|
||||
about it in the [manual].
|
||||
|
||||
|
||||
[last month’s post] <file:2021-04-30-export-plot.org>
|
||||
|
||||
[manual] <https://orgmode.org/manual/Org-Plot.html>
|
||||
|
||||
|
||||
Fancier LaTeX verses
|
||||
════════════════════
|
||||
|
||||
With the use of `verse.sty' you can now export fancier verses from
|
||||
Org, as verse blocks now support four new attributes:
|
||||
⁃ `:lines' for the numbering interval.
|
||||
⁃ `:center' which can be set to `t' and works as long as,
|
||||
• `:versewidth', the longest line in the verse as a text string is
|
||||
set.
|
||||
⁃ You can also easily add arbitrary LaTeX code to be included with
|
||||
`:latexcode'.
|
||||
|
||||
┌────
|
||||
│ #+latex_header: \usepackage{verse}
|
||||
│
|
||||
│ #+latex: \poemtitle{A Dream Within a Dream}
|
||||
│ #+attr_latex: :lines 3 :center t
|
||||
│ #+attr_latex: :versewidth Through my fingers to the deep,
|
||||
│ #+begin_verse
|
||||
│ Take this kiss upon the brow!
|
||||
│ And, in parting from you now,
|
||||
│ Thus much let me avow —
|
||||
│ You are not wrong, who deem
|
||||
│ That my days have been a dream;
|
||||
│ Yet if hope has flown away
|
||||
│ In a night, or in a day,
|
||||
│ In a vision, or in none,
|
||||
│ Is it therefore the less /gone?/
|
||||
│ /All/ that we see or seem
|
||||
│ Is but a dream within a dream.
|
||||
│
|
||||
│ I stand amid the roar
|
||||
│ Of a surf-tormented shore,
|
||||
│ And I hold within my hand
|
||||
│ Grains of the golden sand —
|
||||
│ How few! yet how they creep
|
||||
│ Through my fingers to the deep,
|
||||
│ While I weep — while I weep!
|
||||
│ O God! Can I not grasp
|
||||
│ Them with a tighter clasp?
|
||||
│ O God! can I not save
|
||||
│ /One/ from the pitiless wave?
|
||||
│ Is /all/ that we see or seem
|
||||
│ But a dream within a dream?
|
||||
│ #+end_verse
|
||||
└────
|
||||
|
||||
<file:figures/org-verses-example-poem-dream-within-dream.png>
|
||||
|
||||
|
||||
Easy zero-width spaces with Org
|
||||
═══════════════════════════════
|
||||
|
||||
Occasionally you may run into annoyances when you wish to have two
|
||||
different Org elements right next to each other (no space) — for
|
||||
example, *emph*asising part of a word or putting a currency symbol
|
||||
immediately before an inline source block.
|
||||
|
||||
The best solution to this in Org is zero-width spaces. As such, I’ve
|
||||
found it rather nice adding insertion of a zero-width space to the
|
||||
`org-mode-map' in my config. Perhaps some of you might find this
|
||||
solution useful too 🙂.
|
||||
|
||||
┌────
|
||||
│ (define-key org-mode-map (kbd "M-SPC M-SPC")
|
||||
│ (lambda () (interactive) (insert "\u200b")))
|
||||
└────
|
||||
|
||||
Should you want to keep zero-width spaces out of exports, that’s easy
|
||||
enough to accomplish with an [export filter].
|
||||
|
||||
┌────
|
||||
│ (defun +org-export-remove-zero-width-space (text _backend _info)
|
||||
│ "Remove zero width spaces from TEXT."
|
||||
│ (unless (org-export-derived-backend-p 'org)
|
||||
│ (replace-regexp-in-string "\u200b" "" text)))
|
||||
│
|
||||
│ (add-to-list 'org-export-filter-final-output-functions #'+org-export-remove-zero-width-space t)
|
||||
└────
|
||||
|
||||
|
||||
[export filter]
|
||||
<https://orgmode.org/manual/Advanced-Export-Configuration.html>
|
||||
|
||||
|
||||
Org’s repos have moved
|
||||
══════════════════════
|
||||
|
||||
⁃ `contrib/' is now at <https://git.sr.ht/~bzg/org-contrib> for Org
|
||||
9.5, and it will be available on Non-GNU ELPA.
|
||||
⁃ Worg is now at <https://git.sr.ht/~bzg/worg>
|
||||
⁃ Org itself is moving to Savannah
|
||||
|
||||
|
||||
Other improvements
|
||||
══════════════════
|
||||
|
||||
⁃ Add support for `HHhMM' date formats (e.g. `13h20') _Gustavo Barros_
|
||||
⁃ Make tangling faster /and/ more robust _Sébastien Miquel_
|
||||
⁃ Allow importing tables from files that /don’t/ end in `.txt',
|
||||
`.tsv', or `.csv' _Utkarsh Singh_
|
||||
⁃ Add an SVG-specific post-export `ob-plantuml' step:
|
||||
`org-babel-plantuml-svg-text-to-path' for running Inkscape
|
||||
text-to-path replacement _Nick Daly_
|
||||
⁃ Refactor JavaScript in `ox-html' _Anthony Carrico_
|
||||
⁃ Set `org-html-head-include-scripts' to `nil' by default (was `t')
|
||||
_Bastien Guerry_
|
||||
⁃ Remove LaTeX-environment type `#+results' _TEC_
|
||||
⁃ New capture templates parameter, `:refile-targets' _Richard Garner_
|
||||
⁃ Merge `org-speed-commands-default' and `org-speed-commands-user'
|
||||
into a new variable, `org-speed-commands' _Bastien Guerry_
|
||||
⁃ URL recognition regex now handles up to two levels of nested
|
||||
brackets, and is tested _Ihor Radchenko_
|
||||
⁃ Cache parent heading positions for faster movement up
|
||||
buffers. Significantly improves Org queries involving inheritance
|
||||
(~15-50x improvement) _Ihor Radchenko_
|
||||
⁃ New command `org-refile-reverse' bound to `C-c C-M-w' _Adam Spiers_
|
||||
⁃ Allow inline tasks to be dragged up/down _Bastien Guerry_
|
||||
⁃ LaTeX export, allow arbitrary `:float' values _Thomas S. Dye_
|
||||
⁃ Org attach git, new option `org-attach-git-dir' to use the
|
||||
attachment dir as a git repository _Juan Manuel Macías_
|
||||
⁃ Use a write-back buffer in Org src _Sébastien Miquel_
|
||||
⁃ Add the `:environment' and `:options' LaTeX attributes to Quote
|
||||
blocks _Juan Manuel Macias_
|
||||
⁃ Surround LaTeX `:options' attribute with curly braces when it
|
||||
contains square braces _Markus Huber_
|
||||
⁃ Recognise the specific contributions of Kyle Meyer, Ihor Radchenko,
|
||||
and TEC in the manual _Bastien Guerry_
|
||||
⁃ Improve test coverage _Ihor Radchenko, Kévin Le Gouguec_
|
||||
⁃ A bikeshed of new maintainers
|
||||
• New maintainer for `ox-html' — TEC
|
||||
• New `ob-ledger' maintainer — Eric S Fraga
|
||||
• New `ob-awk' maintainer — Tyler Smith
|
||||
• New `ob-calc' maintainer — Tom Gillespie
|
||||
• New `ob-asymptote' and `ob-coq' maintainer — Luc Pellissier
|
||||
⁃ General code cleanup _Bastien Guerry_
|
||||
⁃ Documentation improvements _Bastien Guerry, Eric S Fraga, Samim
|
||||
Pezeshki, Nicolar Goaziou_
|
||||
|
||||
|
||||
Bugfixes
|
||||
════════
|
||||
|
||||
⁃ Make `ob-gnuplot' work on remote systems _Ihor Radchenko_
|
||||
⁃ Stop `M-x org-toggle-link-display' from affecting emphasis markers
|
||||
_Bastien Guerry_
|
||||
⁃ Inserting a heading before a headline _Bastien Guerry_
|
||||
⁃ Perform `org-entry-put' in a read-only buffer _Ihor Radchenko_
|
||||
⁃ Emacs 24 compatibility for `ob-C' and `org-agenda-show-new-time'
|
||||
_Kyle Meyer_
|
||||
⁃ Maintain Org’s keybindings when `visual-line-mode' active _Bastien
|
||||
Guerry_
|
||||
⁃ Keep track of start of region beginning in `org-table-wrap-region'
|
||||
_Bastien Guerry_
|
||||
⁃ Ensure correct visibility when unfolding subtree _Bastien Guerry_
|
||||
⁃ Corner case in `org--backwards-paragaph-once' _Bastien Guerry_
|
||||
⁃ Some byte compiler silencing _Kyle Meyer_
|
||||
⁃ Make tags filtering case-sensitive _Bastien Guerry_
|
||||
⁃ `C-c C-c' on a `#+plot' line can no longer cause an error _Bastien
|
||||
Guerry_
|
||||
⁃ Ensure consistent position-translation in `org-src' by using point
|
||||
for position instead of column _TEC_
|
||||
⁃ Prevent `ob-sql' from getting stuck on an error _Ivan Sokolov_
|
||||
⁃ Make `org-columns' respect `global-visual-line-mode', and simplify
|
||||
tag scanning _Nick Savage_
|
||||
⁃ Don’t fontify `::' in headlines as description item _Ihor Radchenko_
|
||||
⁃ Handle a few corner-cases in `ob-R' _Jeremie Juste_
|
||||
⁃ Many fixes to `org-indent-line' _Bastien Guerry_
|
||||
⁃ Make headline numbering consistent with TOC _Mingkai Dong_
|
||||
⁃ Allow read-only tangling again, and ensure the correct filename is
|
||||
used _Sébastien Miquel_
|
||||
⁃ Fix edge case when converting durations to minutes _Nicolas Goaziou_
|
||||
⁃ Make org-refile work in non-file-visiting buffers _Bastien Guerry_
|
||||
⁃ Be more rigorous in `org-sort-remove-invisible' _Nicolas Goaziou_
|
||||
⁃ Don’t update checkbox stats when heading has `todo' `COOKIE_DATA'
|
||||
_Bastien Guerry_
|
||||
⁃ Don’t recognise a lone `:END:' to be forming a drawer _Nicolas
|
||||
Goaziou_
|
||||
⁃ Allow new footnotes in empty table cells _Nicolas Goaziou_
|
||||
|
|
@ -0,0 +1,536 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-12 Fri 13:39 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>June 2021</title>
|
||||
<meta name="author" content="TEC" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="June 2021" />
|
||||
<meta property="og:description" content="A relaxed month" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="TEC" />
|
||||
<meta property="og:article:published_time" content="2021-07-04T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2021-08-02T13:36:45+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2021-06-34, <span class='acr'>TEC</span></div>
|
||||
|
||||
<h1 class="title">June 2021</h1>
|
||||
<p class="subtitle" role="doc-subtitle">A relaxed month</p>
|
||||
</header><p>
|
||||
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<sup><a id="fnr.1" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>, 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<sup><a id="fnr.2" class="footref" href="#fn.2" role="doc-backlink">2</a></sup> is getting very close to merging 😀.
|
||||
You’ll just have to stick around to hear about those in a future edition of <span class='acr'>TMIO</span> 😉.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="orgb975711">
|
||||
<img src="figures/dilbert-zenos-paradox.jpg" alt="dilbert-zenos-paradox.jpg" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 1: </span>It’s right around the corner, I swear!</figcaption>
|
||||
</figure>
|
||||
<div id="outline-container-customise-reference-command" class="outline-2">
|
||||
<h2 id="customise-reference-command">Customise the reference command used in LaTeX<a aria-hidden="true" href="#customise-reference-command">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-customise-reference-command">
|
||||
<p>
|
||||
Previously, whenever you linked to another part of your document (with or
|
||||
without giving it a name) — for example with <kbd>[[Profound section]]</kbd> or similar
|
||||
— when exporting to LaTeX Org would <i>always</i> use the <kbd>\ref</kbd> command.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="orgd059838">
|
||||
<img src="figures/org-latex-default-reference-to-sec.png" alt="org-latex-default-reference-to-sec.png" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 2: </span>A LaTeX export of a simple document with a reference to both the first and second section. “2” what? Section 2, Table 2, Figure 2, …</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
You can now set the format string <code>org-latex-reference-command</code> (<kbd>\\ref{%s}</kbd> by
|
||||
default) to anything you’d like. For example, making use of the <a href="https://ctan.org/pkg/cleveref">cleveref</a> package
|
||||
I can set this to <kbd>\\cref{%s}</kbd> and then add <code class="src src-elisp">(<span class="org-string">"capitalize"</span> <span class="org-string">"cleveref"</span> nil)</code><sup><a id="fnr.3" class="footref" href="#fn.3" role="doc-backlink">3</a></sup> to <code>org-latex-packages-alist</code>.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="orgcfb6619">
|
||||
<img src="figures/org-latex-cref-reference-to-sec.png" alt="org-latex-cref-reference-to-sec.png" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 3: </span>A LaTeX export of the same document, but now using <code>cleveref</code>. Note the change from “1” and “2” to “Section 1” and “Section 2”.</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-diversion-into-writing" class="outline-2">
|
||||
<h2 id="diversion-into-writing">A diversion into writing Org for LaTeX<a aria-hidden="true" href="#diversion-into-writing">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-diversion-into-writing">
|
||||
<p>
|
||||
Speaking of LaTeX exports, a member of the Org mailing list recently told us
|
||||
about <a href="https://arxiv.org/abs/2106.05096">a paper</a> pushed to <a href="https://arxiv.org/">arXiv</a> which was written <i>entirely</i> in Org. Why don’t we
|
||||
use that as a prompt to talk a bit about generating LaTeX documents from Org?
|
||||
</p>
|
||||
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
</div>
|
||||
<div id="outline-container-simple-elements" class="outline-3">
|
||||
<h3 id="simple-elements">Simple elements<a aria-hidden="true" href="#simple-elements">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-simple-elements">
|
||||
<p>
|
||||
The “basic” Org elements are simply translated to their LaTeX counterparts.
|
||||
Markup like <b>bold</b>, <i>italic</i>, etc. are simply translated through
|
||||
<code>org-latex-text-markup-alist</code>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For those of us who dabble with equations, Org is <a href="https://orgmode.org/manual/LaTeX-fragments.html">very accomodating</a>. You can
|
||||
type (LaTeX-style) inline and display equations in exactly the same way (<kbd>\( \)</kbd>
|
||||
and <kbd>\[ \]</kbd>), and what’s more, if you have a LaTeX environment statement
|
||||
<kbd>\begin{...}</kbd> on its own line, Org will recognise it and pass it into the
|
||||
generated LaTeX.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-figures-tables" class="outline-3">
|
||||
<h3 id="figures-tables">Figures and tables<a aria-hidden="true" href="#figures-tables">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-figures-tables">
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
<details id='figures-tables,code--1' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#figures-tables,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-link"><a href="file:figures/salvador-dali-persistence-of-memory.jpg">file:figures/salvador-dali-persistence-of-memory.jpg</a></span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
<p>
|
||||
When exported to LaTeX this will be expanded to
|
||||
</p>
|
||||
<details id='figures-tables,code--2' class='code' open><summary><span class="lang">LaTeX</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#figures-tables,code--2'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-LaTeX"><span class="org-keyword">\includegraphics</span>[width=.9<span class="org-keyword">\linewidth</span>]{<span class="org-builtin">figures/salvador-dali-persistence-of-memory.jpg</span>}
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
As soon as you add a <kbd>#+caption</kbd>, though, Org knows you mean business and
|
||||
generates a <i>proper</i> figure.
|
||||
</p>
|
||||
<details id='figures-tables,code--3' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#figures-tables,code--3'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-meta-line">#+caption:</span> <span class="org-org-block">A famous surrealist painting</span>
|
||||
<span class="org-org-link"><a href="file:figures/salvador-dali-persistence-of-memory.jpg">file:figures/salvador-dali-persistence-of-memory.jpg</a></span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
<details id='figures-tables,code--4' class='code' open><summary><span class="lang">LaTeX</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#figures-tables,code--4'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-LaTeX"><span class="org-keyword">\begin</span>{<span class="org-function-name">figure</span>}[htbp]
|
||||
<span class="org-keyword">\centering</span>
|
||||
<span class="org-keyword">\includegraphics</span>[width=.9<span class="org-keyword">\linewidth</span>]{<span class="org-builtin">figures/salvador-dali-persistence-of-memory.jpg</span>}
|
||||
<span class="org-keyword">\caption</span>{A famous surrealist painting}
|
||||
<span class="org-keyword">\end</span>{<span class="org-function-name">figure</span>}
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
As you may have guessed from the fact this works without a LaTeX-specific
|
||||
keyword, this works nicely in <span class='acr'>HTML</span> too 🙂.
|
||||
</p>
|
||||
|
||||
<figure id="orgaebbf1c">
|
||||
<img src="figures/salvador-dali-persistence-of-memory.jpg" alt="salvador-dali-persistence-of-memory.jpg">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 4: </span>A famous surrealist painting</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
The LaTeX backend also accepts additional image attributes (<a href="https://orgmode.org/manual/Images-in-LaTeX-export.html">manual page</a>). For
|
||||
example, to set the image width I can simply add
|
||||
</p>
|
||||
<details id='figures-tables,code--5' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#figures-tables,code--5'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-meta-line">#+attr_latex: :width 0.4\linewidth</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
<p>
|
||||
above the image link.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
You can do the same with tables:
|
||||
</p>
|
||||
<details id='figures-tables,code--6' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#figures-tables,code--6'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-meta-line">#+caption:</span> <span class="org-org-block">A selection of famous paintings by Salvador Dalí</span>
|
||||
<span class="org-org-table">| Year | Painting |</span>
|
||||
<span class="org-org-table">|------+----------------------------|</span>
|
||||
<span class="org-org-table">| 1931 | The persistence of memory |</span>
|
||||
<span class="org-org-table">| 1937 | Swans reflecting elephants |</span>
|
||||
<span class="org-org-table">| 1837 | Metamorphosis of narcissus |</span>
|
||||
<span class="org-org-table">| 1952 | Galatea of the spheres |</span>
|
||||
<span class="org-org-table">| 1966 | Tuna fishing |</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
I like to set <code class="src src-elisp">(<span class="org-keyword">setq</span> org-latex-tables-booktabs t)</code> to use the nice
|
||||
<kbd>booktabs</kbd> rules in the generated tables. Just remember to ensure the <kbd>booktabs</kbd>
|
||||
package is loaded.
|
||||
</p>
|
||||
|
||||
<details id='figures-tables,code--7' class='code' open><summary><span class="lang">LaTeX</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#figures-tables,code--7'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-LaTeX"><span class="org-keyword">\begin</span>{<span class="org-function-name">table</span>}[htbp]
|
||||
<span class="org-keyword">\caption</span>{A selection of famous paintings by Salvador Dalí}
|
||||
<span class="org-keyword">\centering</span>
|
||||
<span class="org-keyword">\begin</span>{<span class="org-function-name">tabular</span>}{rl}
|
||||
<span class="org-keyword">\toprule</span>
|
||||
Year & Painting<span class="org-warning">\\</span>
|
||||
<span class="org-keyword">\midrule</span>
|
||||
1931 & The persistence of memory<span class="org-warning">\\</span>
|
||||
1937 & Swans reflecting elephants<span class="org-warning">\\</span>
|
||||
1837 & Metamorphosis of narcissus<span class="org-warning">\\</span>
|
||||
1952 & Galatea of the spheres<span class="org-warning">\\</span>
|
||||
1966 & Tuna fishing<span class="org-warning">\\</span>
|
||||
<span class="org-keyword">\bottomrule</span>
|
||||
<span class="org-keyword">\end</span>{<span class="org-function-name">tabular</span>}
|
||||
<span class="org-keyword">\end</span>{<span class="org-function-name">table</span>}
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
Org is nice and does the right thing<sup><span class='acr'>TM</span></sup> by including the caption at the top.
|
||||
</p>
|
||||
|
||||
<figure id="orgf70273a">
|
||||
<img src="figures/org-table-to-latex-example.png" alt="org-table-to-latex-example.png" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 5: </span>Look ma, I put the caption in the right place.</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
There are also some <a href="https://orgmode.org/manual/Images-in-LaTeX-export.html">more attributes</a> you can supply to tables. Should I want the
|
||||
table to spread out I could use <kbd>#+attr_latex: :environment tabularx</kbd> (as long as
|
||||
I’ve loaded the <kbd>tabularx</kbd> package) and then set the columns with <kbd>:align lX</kbd>.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-code-blocks" class="outline-3">
|
||||
<h3 id="code-blocks">Code blocks<a aria-hidden="true" href="#code-blocks">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-code-blocks">
|
||||
<p>
|
||||
By default, source code blocks are translated verbatim. We can do better than
|
||||
that however. We can tell Org to use <a href="https://ctan.org/pkg/listings">listings</a>, but I’d recommend going one step
|
||||
further and using <a href="https://ctan.org/pkg/minted">minted</a>. For this to work we need to perform three actions:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li>Tell Org we want to use <kbd>minted</kbd> environments for source code</li>
|
||||
<li>Load the <kbd>minted</kbd> package by default</li>
|
||||
<li>Add <kbd>-shell-escape</kbd> to our LaTeX compiler flags, so <kbd>minted</kbd> may call <a href="https://pygments.org/">pygments</a>.</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
This can easily be accomplished via the following snippet:
|
||||
</p>
|
||||
<details id='code-blocks,code--1' class='code' open><summary><span class="lang">Emacs Lisp</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#code-blocks,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-emacs-lisp">(<span class="org-keyword">setq</span> org-latex-listings 'minted
|
||||
<span class="org-comment-delimiter">;; </span><span class="org-comment">as long as you have latexmk installed</span>
|
||||
org-latex-pdf-process
|
||||
'(<span class="org-string">"latexmk -f -pdf -%latex -shell-escape -interaction=nonstopmode -output-directory=%o %f"</span>))
|
||||
(add-to-list 'org-latex-packages-alist '(<span class="org-string">""</span> <span class="org-string">"minted"</span>))
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
To customise <kbd>minted</kbd>, as well as inserting content into the <a href="#preamble-content">preamble</a>, one can
|
||||
also customise <code>org-latex-minted-options</code> to control what options are applied to
|
||||
each <kbd>minted</kbd> environment.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-custom-environments" class="outline-3">
|
||||
<h3 id="custom-environments">Custom environments<a aria-hidden="true" href="#custom-environments">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-custom-environments">
|
||||
<p>
|
||||
Org has a number of <a href="https://orgmode.org/manual/Blocks.html">blocks</a> which are treated specially, like <kbd>#+begin_src</kbd> for
|
||||
source code, and <kbd>#+begin_centre</kbd> 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).
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For example, if you wrote a <kbd>warning</kbd> environment in LaTeX to box and emphasise
|
||||
text, to wrap some Org content in it one simply needs to write:
|
||||
</p>
|
||||
<details id='custom-environments,code--1' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#custom-environments,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-block-begin-line">#+begin_warning</span>
|
||||
Pay close attention! This is very important.
|
||||
<span class="org-org-block-end-line">#+end_warning</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
<p>
|
||||
and the content will be wrapped in <kbd>\begin{warning} ... \end{warning}</kbd>.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-latex-escape-hatches" class="outline-3">
|
||||
<h3 id="latex-escape-hatches">The LaTeX escape hatches<a aria-hidden="true" href="#latex-escape-hatches">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-latex-escape-hatches">
|
||||
<p>
|
||||
Should there be a particular LaTeX command you wish to insert somewhere, you
|
||||
simply need to put it on its own line with <kbd>#+latex:</kbd> in front and it will be
|
||||
transferred to the generated LaTeX (this works with other formats too).
|
||||
</p>
|
||||
<details id='latex-escape-hatches,code--1' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#latex-escape-hatches,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-meta-line">#+latex: \newpage</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
For larger snippets of LaTeX, there’s always the export block.
|
||||
</p>
|
||||
<details id='latex-escape-hatches,code--2' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#latex-escape-hatches,code--2'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-block-begin-line">#+begin_export latex</span>
|
||||
<span class="custom">\cleardoublepage</span>
|
||||
<span class="custom">\vfil</span>
|
||||
<span class="custom">\hfil This page is intentionally left blank \hfil</span>
|
||||
<span class="custom">\vfil</span>
|
||||
<span class="custom">\newpage</span>
|
||||
<span class="org-org-block-end-line">#+end_export</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-preamble-content" class="outline-3">
|
||||
<h3 id="preamble-content">Preamble content<a aria-hidden="true" href="#preamble-content">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-preamble-content">
|
||||
<p>
|
||||
Should you wish to include the line in the preamble (before <kbd>\begin{document}</kbd>),
|
||||
then all you need to do is use <kbd>#+latex_header:</kbd>.
|
||||
</p>
|
||||
<details id='preamble-content,code--1' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#preamble-content,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-meta-line">#+latex_header: \newcommand{\RR}{\mathbb{R}}</span>
|
||||
<span class="org-org-meta-line">#+latex_header: \usepackage{svg} % so that <a href="file:*.svg">file:*.svg</a> works nicely</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
<p>
|
||||
This is great for adding one-off <kbd>\usepackage</kbd> commands, but what if you find
|
||||
yourself wanting a package (like <a href="https://ctan.org/pkg/svg">svg</a>) to be always included? Well the we have
|
||||
the aforementioned <code>org-latex-packages-alist</code> which will include the packages
|
||||
set when exporting; you can even set some packages to only be included when
|
||||
using a certain LaTeX compiler.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Should you want to use a certain preset preamble, you can make use of the
|
||||
<kbd>#+latex_class</kbd> keyword. This is used to set the base preamble template used when
|
||||
generating the LaTeX. See <code>org-latex-classes</code> for what’s available by default. You
|
||||
should see entries for:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li>article</li>
|
||||
<li>report</li>
|
||||
<li>book</li>
|
||||
<li>beamer</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
One of these is always used when generating LaTeX; when no <kbd>#+latex_class</kbd> is set
|
||||
in the document, the template named by <code>org-latex-default-class</code> will be used.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
What’s great about this is that is makes it really easy to add your own
|
||||
templates. Each template simply takes three components:
|
||||
</p>
|
||||
<ol class="org-ol">
|
||||
<li>A name</li>
|
||||
<li>A preamble template</li>
|
||||
<li>A series of format strings to translate headings to LaTeX, with and without numbering</li>
|
||||
</ol>
|
||||
|
||||
<p>
|
||||
For example, I’m quite a fan of the <a href="https://ctan.org/pkg/koma-script"><span class='acr'>KOMA</span>-script</a> family. Should I want to add a
|
||||
<kbd>kart</kbd> class (for: <b>k</b>oma <b>art</b>icle), I simply need to do something like the
|
||||
following:
|
||||
</p>
|
||||
<details id='preamble-content,code--2' class='code' open><summary><span class="lang">Emacs Lisp</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#preamble-content,code--2'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-emacs-lisp">(add-to-list 'org-latex-classes
|
||||
'(<span class="org-string">"kart"</span> <span class="org-comment-delimiter">; </span><span class="org-comment">class name</span>
|
||||
<span class="org-string">"\\documentclass{scrartcl}"</span> <span class="org-comment-delimiter">; </span><span class="org-comment">preamble template</span>
|
||||
(<span class="org-string">"\\section{%s}"</span> . <span class="org-string">"\\section*{%s}"</span>) <span class="org-comment-delimiter">; </span><span class="org-comment">H1 translation</span>
|
||||
(<span class="org-string">"\\subsection{%s}"</span> . <span class="org-string">"\\subsection*{%s}"</span>) <span class="org-comment-delimiter">; </span><span class="org-comment">H2 translation</span>
|
||||
(<span class="org-string">"\\subsubsection{%s}"</span> . <span class="org-string">"\\subsubsection*{%s}"</span>) <span class="org-comment-delimiter">; </span><span class="org-comment">H3...</span>
|
||||
(<span class="org-string">"\\paragraph{%s}"</span> . <span class="org-string">"\\paragraph*{%s}"</span>)
|
||||
(<span class="org-string">"\\subparagraph{%s}"</span> . <span class="org-string">"\\subparagraph*{%s}"</span>)))
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
See the documentation for <code>org-latex-classes</code> for more information on how the
|
||||
preamble template in handled.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-other-improvements" class="outline-2">
|
||||
<h2 id="other-improvements">Other improvements<a aria-hidden="true" href="#other-improvements">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-other-improvements">
|
||||
<ul class="org-ul">
|
||||
<li><kbd>ox-koma-letter.el</kbd> has been brought into Org’s main directory from the ) <kbd>contrib/</kbd> repo <span class="underline">Bastien Guerry</span></li>
|
||||
<li>Speed up publishing by using delayed hooks and temp buffers instead of finding
|
||||
files <span class="underline">Gustav Wikström</span></li>
|
||||
<li>Improve generated <span class='acr'>HTML</span> quality: prevent W3C warning and add some accessibility
|
||||
labels <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>Make the behaviour of the “goto variant” of <code>org-refile</code> (<code>org-speed-commands</code>)
|
||||
less confusing <span class="underline">Marco Wahl</span></li>
|
||||
<li>Backport an update to the OpenDocument schema <span class="underline">Kyle Meyer</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-bugfixes" class="outline-2">
|
||||
<h2 id="bugfixes">Bugfixes<a aria-hidden="true" href="#bugfixes">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-bugfixes">
|
||||
<ul class="org-ul">
|
||||
<li>Off by one error in texinfo menu generation <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Error in entry/conversion of non-24h times in the agenda <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Only use <code>replace-buffer-contents</code> with Emacs 27+ when saving src blocks, as the
|
||||
behaviour isn’t consistent until then <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Prevent “before first headline” error in <kbd>org-clock</kbd> when clocking out <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Avoid setting the global agenda name when following a timestamp link <span class="underline">Ingo Lohmar</span></li>
|
||||
<li>Don’t bind <kbd><tab></kbd> in <code>org-mode-map</code> <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Erroneous tangling of source block with <kbd>:tangle no</kbd> to a file <kbd>no</kbd> when the
|
||||
tangle command is called with a single universal argument <span class="underline">Jacopo De Simoi</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="footnotes">
|
||||
<h2 class="footnotes">Footnotes: </h2>
|
||||
<div id="text-footnotes">
|
||||
|
||||
<div class="footdef"><sup><a id="fn.1" class="footnum" href="#fnr.1" role="doc-backlink">1</a></sup> <div class="footpara" role="doc-footnote"><p class="footpara">
|
||||
As has been the writing of this blog post 😜
|
||||
</p></div></div>
|
||||
|
||||
<div class="footdef"><sup><a id="fn.2" class="footnum" href="#fnr.2" role="doc-backlink">2</a></sup> <div class="footpara" role="doc-footnote"><p class="footpara">
|
||||
First-class support for citations is coming to Org! With support for <a href="https://citationstyles.org/"><span class='acr'>CSL</span></a>
|
||||
and <a href="https://en.wikipedia.org/wiki/BibTeX">BibTeX</a>, with a number of citation processors 🙌. Soon<sup><span class='acr'>TM</span></sup>
|
||||
</p></div></div>
|
||||
|
||||
<div class="footdef"><sup><a id="fn.3" class="footnum" href="#fnr.3" role="doc-backlink">3</a></sup> <div class="footpara" role="doc-footnote"><p class="footpara">
|
||||
I’m rather a fan of the <kbd>capitalize</kbd> 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.
|
||||
</p></div></div>
|
||||
|
||||
|
||||
</div>
|
||||
</div></div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
# Created 2024-01-12 Fri 13:39
|
||||
#+title: June 2021
|
||||
#+subtitle: A relaxed month
|
||||
#+author: TEC
|
||||
#+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
|
||||
|
|
@ -11,9 +11,7 @@ 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!
|
||||
#+attr_html: :class invertible
|
||||
[[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
|
||||
|
|
@ -22,18 +20,19 @@ without giving it a name) --- for example with =[[Profound section]]= or similar
|
|||
|
||||
#+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, ...
|
||||
#+attr_html: :class invertible
|
||||
[[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~.
|
||||
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".
|
||||
#+attr_html: :class invertible
|
||||
[[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
|
||||
|
|
@ -43,7 +42,6 @@ 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.
|
||||
|
|
@ -55,32 +53,31 @@ 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]]
|
||||
[[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}
|
||||
\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]]
|
||||
,#+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}
|
||||
\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
|
||||
|
|
@ -91,20 +88,20 @@ keyword, this works nicely in HTML too 🙂.
|
|||
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
|
||||
,#+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 |
|
||||
,#+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
|
||||
|
|
@ -112,54 +109,51 @@ I like to set src_elisp{(setq org-latex-tables-booktabs t)} to use the nice
|
|||
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}
|
||||
\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.
|
||||
#+attr_html: :class invertible
|
||||
[[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]].
|
||||
- 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"))
|
||||
(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
|
||||
|
|
@ -170,39 +164,37 @@ 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
|
||||
,#+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
|
||||
,#+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
|
||||
,#+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
|
||||
,#+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
|
||||
|
|
@ -214,10 +206,10 @@ 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
|
||||
- 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.
|
||||
|
|
@ -229,51 +221,37 @@ templates. Each template simply takes three components:
|
|||
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
|
||||
=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}")))
|
||||
(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
|
||||
- =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
|
||||
- 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~)
|
||||
- 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_
|
||||
|
||||
- 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
|
||||
- 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
|
||||
- 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
|
||||
|
||||
[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}
|
||||
|
||||
[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.
|
||||
|
|
@ -0,0 +1,400 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>2021-06-34-relaxed.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">June 2021
|
||||
</span><span style="color: #9e9e9e;">#+subtitle:</span> A relaxed month
|
||||
<span style="color: #9e9e9e;">#+author:</span> TEC
|
||||
<span style="color: #9e9e9e;">#+date:</span> 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[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 😉.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">It's right around the corner, I swear!</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/dilbert-zenos-paradox.jpg]]</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Customise the reference command used in LaTeX</span>
|
||||
|
||||
Previously, whenever you linked to another part of your document (with or
|
||||
without giving it a name) --- for example with <span style="color: #9e9e9e;">=</span><span style="color: #9e9e9e; font-weight: 700;">[[Profound section]]</span><span style="color: #9e9e9e;">=</span> or similar
|
||||
--- when exporting to LaTeX Org would <span class="ef-i">/always/</span> use the <span style="color: #9e9e9e;">=\ref=</span> command.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">A LaTeX export of a simple document with a reference to both the first and second section.</span>
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">"2" what? Section 2, Table 2, Figure 2, ...</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/org-latex-default-reference-to-sec.png]]</span>
|
||||
|
||||
You can now set the format string <span style="color: #9e9e9e;">~org-latex-reference-command~</span> (<span style="color: #9e9e9e;">=\\ref{%s}=</span> by
|
||||
default) to anything you'd like. For example, making use of the <span style="color: #3b6ea8; font-weight: 700;">[[https://ctan.org/pkg/cleveref][cleveref]]</span> package
|
||||
I can set this to <span style="color: #9e9e9e;">=\\cref{%s}=</span> and then add <span style="color: #9e9e9e; background-color: #e0e0e0;">src_</span><span style="color: #b1b1b1; background-color: #e0e0e0;">elisp</span><span style="color: #9e9e9e; background-color: #e0e0e0;">{</span><span class="ef-ob">(</span><span style="color: #4f894c; background-color: #e0e0e0;">"capitalize"</span> <span style="color: #4f894c; background-color: #e0e0e0;">"cleveref"</span><span class="ef-ob">
|
||||
nil)</span><span style="color: #9e9e9e; background-color: #e0e0e0;">}</span>[fn:3] to <span style="color: #9e9e9e;">~org-latex-packages-alist~</span>.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">A LaTeX export of the same document, but now using ~cleveref~. Note the change from "1" and "2" to "Section 1" and "Section 2".</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/org-latex-cref-reference-to-sec.png]]</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* A diversion into writing Org for LaTeX</span>
|
||||
|
||||
Speaking of LaTeX exports, a member of the Org mailing list recently told us
|
||||
about <span style="color: #3b6ea8; font-weight: 700;">[[https://arxiv.org/abs/2106.05096][a paper]]</span> pushed to <span style="color: #3b6ea8; font-weight: 700;">[[https://arxiv.org/][arXiv]]</span> which was written <span class="ef-i">/entirely/</span> 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.
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Simple elements</span>
|
||||
|
||||
The "basic" Org elements are simply translated to their LaTeX counterparts.
|
||||
Markup like <span class="ef-b">*bold*</span>, <span class="ef-i">/italic/</span>, etc. are simply translated through
|
||||
<span style="color: #9e9e9e;">~org-latex-text-markup-alist~</span>.
|
||||
|
||||
For those of us who dabble with equations, Org is <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/manual/LaTeX-fragments.html][very accomodating]]</span>. You can
|
||||
type (LaTeX-style) inline and display equations in exactly the same way (<span style="color: #9e9e9e;">=\( \)=</span>
|
||||
and <span style="color: #9e9e9e;">=\[ \]=</span>), and what's more, if you have a LaTeX environment statement
|
||||
<span style="color: #9e9e9e;">=\begin{...}=</span> on its own line, Org will recognise it and pass it into the
|
||||
generated LaTeX.
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Figures and tables</span>
|
||||
|
||||
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.
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span style="color: #3b6ea8; background-color: #e0e0e0; font-weight: 700;">[[file:figures/salvador-dali-persistence-of-memory.jpg]]</span>
|
||||
<span class="ef-obe">#+end_src
|
||||
</span>When exported to LaTeX this will be expanded to
|
||||
<span class="ef-obb">#+begin_src LaTeX
|
||||
</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\includegraphics</span><span class="ef-ob">[width=.9</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\linewidth</span><span class="ef-ob">]{</span><span style="color: #29838d; background-color: #e0e0e0;">figures/salvador-dali-persistence-of-memory.jpg</span><span class="ef-ob">}
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
As soon as you add a <span style="color: #9e9e9e;">=#+caption=</span>, though, Org knows you mean business and
|
||||
generates a <span class="ef-i">/proper/</span> figure.
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+caption: A famous surrealist painting
|
||||
</span><span style="color: #3b6ea8; background-color: #e0e0e0; font-weight: 700;">[[file:figures/salvador-dali-persistence-of-memory.jpg]]</span>
|
||||
<span class="ef-obe">#+end_src
|
||||
</span><span class="ef-obb">#+begin_src LaTeX
|
||||
</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\begin</span><span class="ef-ob">{</span><span style="color: #29838d; background-color: #e0e0e0;">figure</span><span class="ef-ob">}[htbp]
|
||||
</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\centering</span>
|
||||
<span style="color: #3b6ea8; background-color: #e0e0e0;">\includegraphics</span><span class="ef-ob">[width=.9</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\linewidth</span><span class="ef-ob">]{</span><span style="color: #29838d; background-color: #e0e0e0;">figures/salvador-dali-persistence-of-memory.jpg</span><span class="ef-ob">}
|
||||
</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\caption</span><span class="ef-ob">{A famous surrealist painting}
|
||||
</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\end</span><span class="ef-ob">{</span><span style="color: #29838d; background-color: #e0e0e0;">figure</span><span class="ef-ob">}
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
As you may have guessed from the fact this works without a LaTeX-specific
|
||||
keyword, this works nicely in HTML too 🙂.
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">A famous surrealist painting</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/salvador-dali-persistence-of-memory.jpg]]</span>
|
||||
|
||||
The LaTeX backend also accepts additional image attributes (<span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/manual/Images-in-LaTeX-export.html][manual page]]</span>). For
|
||||
example, to set the image width I can simply add
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+attr_latex: :width 0.4\linewidth
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>above the image link.
|
||||
|
||||
You can do the same with tables:
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+caption: A selection of famous paintings by Salvador Dalí
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;">| Year | Painting |</span>
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">|------+----------------------------|</span>
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">| 1931 | The persistence of memory |</span>
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">| 1937 | Swans reflecting elephants |</span>
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">| 1837 | Metamorphosis of narcissus |</span>
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">| 1952 | Galatea of the spheres |</span>
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">| 1966 | Tuna fishing |</span>
|
||||
<span class="ef-obe">#+end_src
|
||||
</span>
|
||||
I like to set <span style="color: #9e9e9e; background-color: #e0e0e0;">src_</span><span style="color: #b1b1b1; background-color: #e0e0e0;">elisp</span><span style="color: #9e9e9e; background-color: #e0e0e0;">{</span><span class="ef-ob">(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">setq</span><span class="ef-ob"> org-latex-tables-booktabs t)</span><span style="color: #9e9e9e; background-color: #e0e0e0;">}</span> to use the nice
|
||||
<span style="color: #9e9e9e;">=booktabs=</span> rules in the generated tables. Just remember to ensure the <span style="color: #9e9e9e;">=booktabs=</span>
|
||||
package is loaded.
|
||||
|
||||
<span class="ef-obb">#+begin_src LaTeX
|
||||
</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\begin</span><span class="ef-ob">{</span><span style="color: #29838d; background-color: #e0e0e0;">table</span><span class="ef-ob">}[htbp]
|
||||
</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\caption</span><span class="ef-ob">{A selection of famous paintings by Salvador Dalí}
|
||||
</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\centering</span>
|
||||
<span style="color: #3b6ea8; background-color: #e0e0e0;">\begin</span><span class="ef-ob">{</span><span style="color: #29838d; background-color: #e0e0e0;">tabular</span><span class="ef-ob">}{rl}
|
||||
</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\toprule</span><span class="ef-ob">
|
||||
Year & Painting</span><span style="color: #9a7500; background-color: #e0e0e0;">\\</span>
|
||||
<span style="color: #3b6ea8; background-color: #e0e0e0;">\midrule</span><span class="ef-ob">
|
||||
1931 & The persistence of memory</span><span style="color: #9a7500; background-color: #e0e0e0;">\\</span><span class="ef-ob">
|
||||
1937 & Swans reflecting elephants</span><span style="color: #9a7500; background-color: #e0e0e0;">\\</span><span class="ef-ob">
|
||||
1837 & Metamorphosis of narcissus</span><span style="color: #9a7500; background-color: #e0e0e0;">\\</span><span class="ef-ob">
|
||||
1952 & Galatea of the spheres</span><span style="color: #9a7500; background-color: #e0e0e0;">\\</span><span class="ef-ob">
|
||||
1966 & Tuna fishing</span><span style="color: #9a7500; background-color: #e0e0e0;">\\</span>
|
||||
<span style="color: #3b6ea8; background-color: #e0e0e0;">\bottomrule</span>
|
||||
<span style="color: #3b6ea8; background-color: #e0e0e0;">\end</span><span class="ef-ob">{</span><span style="color: #29838d; background-color: #e0e0e0;">tabular</span><span class="ef-ob">}
|
||||
</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\end</span><span class="ef-ob">{</span><span style="color: #29838d; background-color: #e0e0e0;">table</span><span class="ef-ob">}
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
Org is nice and does the right thing^{TM} by including the caption at the top.
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Look ma, I put the caption in the right place.</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/org-table-to-latex-example.png]]</span>
|
||||
|
||||
There are also some <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/manual/Images-in-LaTeX-export.html][more attributes]]</span> you can supply to tables. Should I want the
|
||||
table to spread out I could use <span style="color: #9e9e9e;">=#+attr_latex: :environment tabularx=</span> (as long as
|
||||
I've loaded the <span style="color: #9e9e9e;">=tabularx=</span> package) and then set the columns with <span style="color: #9e9e9e;">=:align lX=</span>.
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Code blocks</span>
|
||||
|
||||
By default, source code blocks are translated verbatim. We can do better than
|
||||
that however. We can tell Org to use <span style="color: #3b6ea8; font-weight: 700;">[[https://ctan.org/pkg/listings][listings]]</span>, but I'd recommend going one step
|
||||
further and using <span style="color: #3b6ea8; font-weight: 700;">[[https://ctan.org/pkg/minted][minted]]</span>. For this to work we need to perform three actions:
|
||||
+ Tell Org we want to use <span style="color: #9e9e9e;">=minted=</span> environments for source code
|
||||
+ Load the <span style="color: #9e9e9e;">=minted=</span> package by default
|
||||
+ Add <span style="color: #9e9e9e;">=-shell-escape=</span> to our LaTeX compiler flags, so <span style="color: #9e9e9e;">=minted=</span> may call <span style="color: #3b6ea8; font-weight: 700;">[[https://pygments.org/][pygments]]</span>.
|
||||
|
||||
This can easily be accomplished via the following snippet:
|
||||
<span class="ef-obb">#+begin_src emacs-lisp
|
||||
</span><span class="ef-ob">(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">setq</span><span class="ef-ob"> org-latex-listings 'minted
|
||||
</span><span style="color: #b1b1b1; background-color: #e0e0e0;">;; </span><span style="color: #b1b1b1; background-color: #e0e0e0;">as long as you have latexmk installed
|
||||
</span><span class="ef-ob"> org-latex-pdf-process
|
||||
'(</span><span style="color: #4f894c; background-color: #e0e0e0;">"latexmk -f -pdf -%latex -shell-escape -interaction=nonstopmode -output-directory=%o %f"</span><span class="ef-ob">))
|
||||
(add-to-list 'org-latex-packages-alist '(</span><span style="color: #4f894c; background-color: #e0e0e0;">""</span> <span style="color: #4f894c; background-color: #e0e0e0;">"minted"</span><span class="ef-ob">))
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
To customise <span style="color: #9e9e9e;">=minted=</span>, as well as inserting content into the <span style="color: #3b6ea8; font-weight: 700;">[[Preamble content][preamble]]</span>, one can
|
||||
also customise <span style="color: #9e9e9e;">~org-latex-minted-options~</span> to control what options are applied to
|
||||
each <span style="color: #9e9e9e;">=minted=</span> environment.
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Custom environments</span>
|
||||
|
||||
Org has a number of <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/manual/Blocks.html][blocks]]</span> which are treated specially, like <span style="color: #9e9e9e;">=#+begin_src=</span> for
|
||||
source code, and <span style="color: #9e9e9e;">=#+begin_centre=</span> 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 <span style="color: #9e9e9e;">=warning=</span> environment in LaTeX to box and emphasise
|
||||
text, to wrap some Org content in it one simply needs to write:
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+begin_warning
|
||||
Pay close attention! This is very important.
|
||||
,#+end_warning
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>and the content will be wrapped in <span style="color: #9e9e9e;">=\begin{warning} ... \end{warning}=</span>.
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** The LaTeX escape hatches</span>
|
||||
|
||||
Should there be a particular LaTeX command you wish to insert somewhere, you
|
||||
simply need to put it on its own line with <span style="color: #9e9e9e;">=#+latex:=</span> in front and it will be
|
||||
transferred to the generated LaTeX (this works with other formats too).
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+latex: \newpage
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
For larger snippets of LaTeX, there's always the export block.
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+begin_export latex
|
||||
\cleardoublepage
|
||||
\vfil
|
||||
\hfil This page is intentionally left blank \hfil
|
||||
\vfil
|
||||
\newpage
|
||||
,#+end_export
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Preamble content</span>
|
||||
|
||||
Should you wish to include the line in the preamble (before <span style="color: #9e9e9e;">=\begin{document}=</span>),
|
||||
then all you need to do is use <span style="color: #9e9e9e;">=#+latex_header:=</span>.
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+latex_header: \newcommand{\RR}{\mathbb{R}}
|
||||
,#+latex_header: \usepackage{svg} % so that </span><span style="color: #3b6ea8; background-color: #e0e0e0; font-weight: 700;">[[file:*.svg]]</span><span class="ef-ob"> works nicely
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>This is great for adding one-off <span style="color: #9e9e9e;">=\usepackage=</span> commands, but what if you find
|
||||
yourself wanting a package (like <span style="color: #3b6ea8; font-weight: 700;">[[https://ctan.org/pkg/svg][svg]]</span>) to be always included? Well the we have
|
||||
the aforementioned <span style="color: #9e9e9e;">~org-latex-packages-alist~</span> 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
|
||||
<span style="color: #9e9e9e;">=#+latex_class=</span> keyword. This is used to set the base preamble template used when
|
||||
generating the LaTeX. See <span style="color: #9e9e9e;">~org-latex-classes~</span> 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 <span style="color: #9e9e9e;">=#+latex_class=</span> is set
|
||||
in the document, the template named by <span style="color: #9e9e9e;">~org-latex-default-class~</span> 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 <span style="color: #3b6ea8; font-weight: 700;">[[https://ctan.org/pkg/koma-script][KOMA-script]]</span> family. Should I want to add a
|
||||
<span style="color: #9e9e9e;">=kart=</span> class (for: <span class="ef-b">*k*</span>oma <span class="ef-b">*art*</span>icle), I simply need to do something like the
|
||||
following:
|
||||
<span class="ef-obb">#+begin_src emacs-lisp
|
||||
</span><span class="ef-ob">(add-to-list 'org-latex-classes
|
||||
'(</span><span style="color: #4f894c; background-color: #e0e0e0;">"kart"</span> <span style="color: #b1b1b1; background-color: #e0e0e0;">; </span><span style="color: #b1b1b1; background-color: #e0e0e0;">class name
|
||||
</span> <span style="color: #4f894c; background-color: #e0e0e0;">"\\documentclass{scrartcl}"</span> <span style="color: #b1b1b1; background-color: #e0e0e0;">; </span><span style="color: #b1b1b1; background-color: #e0e0e0;">preamble template
|
||||
</span><span class="ef-ob"> (</span><span style="color: #4f894c; background-color: #e0e0e0;">"\\section{%s}"</span><span class="ef-ob"> . </span><span style="color: #4f894c; background-color: #e0e0e0;">"\\section*{%s}"</span><span class="ef-ob">) </span><span style="color: #b1b1b1; background-color: #e0e0e0;">; </span><span style="color: #b1b1b1; background-color: #e0e0e0;">H1 translation
|
||||
</span><span class="ef-ob"> (</span><span style="color: #4f894c; background-color: #e0e0e0;">"\\subsection{%s}"</span><span class="ef-ob"> . </span><span style="color: #4f894c; background-color: #e0e0e0;">"\\subsection*{%s}"</span><span class="ef-ob">) </span><span style="color: #b1b1b1; background-color: #e0e0e0;">; </span><span style="color: #b1b1b1; background-color: #e0e0e0;">H2 translation
|
||||
</span><span class="ef-ob"> (</span><span style="color: #4f894c; background-color: #e0e0e0;">"\\subsubsection{%s}"</span><span class="ef-ob"> . </span><span style="color: #4f894c; background-color: #e0e0e0;">"\\subsubsection*{%s}"</span><span class="ef-ob">) </span><span style="color: #b1b1b1; background-color: #e0e0e0;">; </span><span style="color: #b1b1b1; background-color: #e0e0e0;">H3...
|
||||
</span><span class="ef-ob"> (</span><span style="color: #4f894c; background-color: #e0e0e0;">"\\paragraph{%s}"</span><span class="ef-ob"> . </span><span style="color: #4f894c; background-color: #e0e0e0;">"\\paragraph*{%s}"</span><span class="ef-ob">)
|
||||
(</span><span style="color: #4f894c; background-color: #e0e0e0;">"\\subparagraph{%s}"</span><span class="ef-ob"> . </span><span style="color: #4f894c; background-color: #e0e0e0;">"\\subparagraph*{%s}"</span><span class="ef-ob">)))
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
See the documentation for <span style="color: #9e9e9e;">~org-latex-classes~</span> for more information on how the
|
||||
preamble template in handled.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Other improvements</span>
|
||||
+ <span style="color: #9e9e9e;">=ox-koma-letter.el=</span> has been brought into Org's main directory from the ) <span style="color: #9e9e9e;">=contrib/=</span> 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 <span style="color: #9e9e9e;">~org-refile~</span> (<span style="color: #9e9e9e;">~org-speed-commands~</span>)
|
||||
less confusing _Marco Wahl_
|
||||
+ Backport an update to the OpenDocument schema _Kyle Meyer_
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Bugfixes</span>
|
||||
+ 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 <span style="color: #9e9e9e;">~replace-buffer-contents~</span> with Emacs 27+ when saving src blocks, as the
|
||||
behaviour isn't consistent until then _Nicolas Goaziou_
|
||||
+ Prevent "before first headline" error in <span style="color: #9e9e9e;">=org-clock=</span> when clocking out _Nicolas Goaziou_
|
||||
+ Avoid setting the global agenda name when following a timestamp link _Ingo Lohmar_
|
||||
+ Don't bind <span style="color: #9e9e9e;">=<tab>=</span> in <span style="color: #9e9e9e;">~org-mode-map~</span> _Nicolas Goaziou_
|
||||
+ Erroneous tangling of source block with <span style="color: #9e9e9e;">=:tangle no=</span> to a file <span style="color: #9e9e9e;">=no=</span> when the
|
||||
tangle command is called with a single universal argument _Jacopo De Simoi_
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Footnotes</span>
|
||||
|
||||
[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 <span style="color: #3b6ea8; font-weight: 700;">[[https://citationstyles.org/][CSL]]</span>
|
||||
and <span style="color: #3b6ea8; font-weight: 700;">[[https://en.wikipedia.org/wiki/BibTeX][BibTeX]]</span>, with a number of citation processors 🙌. Soon^{TM}
|
||||
|
||||
[fn:3] I'm rather a fan of the <span style="color: #9e9e9e;">=capitalize=</span> 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.
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,355 @@
|
|||
━━━━━━━━━━━━━━━━━
|
||||
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.
|
||||
|
|
@ -0,0 +1,791 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-12 Fri 13:39 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>July 2021</title>
|
||||
<meta name="author" content="TEC" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="July 2021" />
|
||||
<meta property="og:description" content="Introducing citations!" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="TEC" />
|
||||
<meta property="og:article:published_time" content="2021-07-31T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2021-09-27T03:44:41+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2021-07-31, <span class='acr'>TEC</span></div>
|
||||
|
||||
<h1 class="title">July 2021</h1>
|
||||
<p class="subtitle" role="doc-subtitle">Introducing citations!</p>
|
||||
</header><p>
|
||||
Last month I not-at-all-subtly hinted that a certain long-awaited feature was
|
||||
arriving imminently. At this point, I think it’s a good idea to set the tone for the rest of
|
||||
this post.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org0b07091">
|
||||
<img src="figures/celebrate-citations.svg" alt="celebrate-citations.svg" class="org-svg">
|
||||
|
||||
</figure>
|
||||
<div id="outline-container-citations" class="outline-2">
|
||||
<h2 id="citations">Citations<a aria-hidden="true" href="#citations">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-citations">
|
||||
<p>
|
||||
After <i>years</i> of (on and off) discussion<sup><a id="fnr.1" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>, I am elated to be able to present
|
||||
Org’s new native citation syntax. Org has grown a thoroughly designed, modular,
|
||||
capable citation system. At last you can refer to Org for all your attribution
|
||||
needs. Special thanks must go to Nicolas Goaziou for leading the charge, John
|
||||
Kitchin for paving the way with the <kbd>org-ref</kbd> package, Bruce D’Arcus for driving a
|
||||
lot of careful consideration of design decisions and starting to document some
|
||||
of the details — and the many other denizens of the mailing list who have
|
||||
contributed to the discussion over the years.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
András Simonyi’s also deserves a special mention for his work creating the Elisp
|
||||
<span class='acr'>CSL</span> library <code>Citeproc.el</code>, which while not directly included in Org is crucial to
|
||||
providing robust <span class='acr'>CSL</span> support, and integrates with <kbd>oc-csl.el</kbd>.
|
||||
</p>
|
||||
</div>
|
||||
<div id="outline-container-outline" class="outline-3">
|
||||
<h3 id="outline">Outline<a aria-hidden="true" href="#outline">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-outline">
|
||||
<p>
|
||||
Citations have been carefully designed in such a way that users and Elisp
|
||||
tinkerers will be able to easily adapt and extend it to fit their needs.
|
||||
To that end, Org Cite (or <span class='acr'>OC</span> for short) has been split into two halves:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li><kbd>oc.el</kbd> which defines the syntax and provides some machinery to interact with
|
||||
citations</li>
|
||||
<li>Citation processors which interface with <kbd>oc.el</kbd> to produce nicely-formatted
|
||||
citations to be inserted in your bibliography, within the text, and even
|
||||
rendered in the buffer<sup><a id="fnr.2" class="footref" href="#fn.2" role="doc-backlink">2</a></sup></li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
There are four capabilities that Org Cite uses the processors for
|
||||
</p>
|
||||
<ol class="org-ol">
|
||||
<li>Inserting and editing citations</li>
|
||||
<li>Following citations to their definition</li>
|
||||
<li>Fontifying the citations in the buffer</li>
|
||||
<li>Exporting the citations</li>
|
||||
</ol>
|
||||
|
||||
<p>
|
||||
Each capability can have a particular citation processor assigned, independently
|
||||
of the others. Out of the box, Org uses the <kbd>basic</kbd> processor for all of these tasks.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The <kbd>basic</kbd> citation processor is one of four currently bundled with Org:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li><kbd>basic</kbd>, which has no dependencies and provides all four capabilities. It export
|
||||
to all formats, but only provides very simple citations.</li>
|
||||
<li><kbd>biblatex</kbd> and <kbd>natbib</kbd>, which provide the export capability to create citations
|
||||
via <a href="http://biblatex-biber.sourceforge.net/">Biber</a> and (to a lesser extent) <a href="https://ctan.org/pkg/natbib">natbib</a>, but only for LaTeX.</li>
|
||||
<li><kbd>csl</kbd>, which provides the export capability using the <a href="https://citationstyles.org/">Citation Style Language</a>,
|
||||
and exports to <span class='acr'>HTML</span>, LaTeX, Org, and plain text (with an <a href="https://github.com/andras-simonyi/citeproc-el/issues/23">open issue</a> for <span class='acr'>ODT</span>)
|
||||
— but depends on <a href="https://github.com/andras-simonyi/citeproc-el">citeproc.el</a>.</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
This provides a solid foundation for other packages to build off, and despite
|
||||
Org Cite being yet to be released or documented in the manual we are already
|
||||
seeing the development of packages like <a href="https://github.com/jkitchin/org-ref-cite">org-ref-cite</a> (by John Kitchin).
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-basic-usage" class="outline-3">
|
||||
<h3 id="basic-usage">Basic usage<a aria-hidden="true" href="#basic-usage">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-basic-usage">
|
||||
<p>
|
||||
To get started with Org Cite, we must have some form of bibliography.
|
||||
This can either be a BibTeX file or a <span class='acr'>CSL</span>-<span class='acr'>JSON</span> file.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
As an example, say we have a file <kbd>orgcite.bib</kbd> containing the following
|
||||
</p>
|
||||
<details id='basic-usage,code--1' class='code' open><summary><span class="lang">bibtex</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#basic-usage,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-bibtex"><span class="org-function-name">@article</span>{<span class="org-constant">OrgCitations</span>,
|
||||
<span class="org-variable-name">author</span>={org, mode and Syntax, Citation and List, Mailing and Effort, Time},
|
||||
<span class="org-variable-name">journal</span>={Journal of Plain Text Formats},
|
||||
<span class="org-variable-name">title</span>={Elegant Citations with Org-Mode},
|
||||
<span class="org-variable-name">year</span>={2021},
|
||||
<span class="org-variable-name">month</span>={7},
|
||||
<span class="org-variable-name">volume</span>={42},
|
||||
<span class="org-variable-name">number</span>={1},
|
||||
<span class="org-variable-name">pages</span>={2-3}}
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
First we need to let Org know about this bibliography file (which must have a
|
||||
<kbd>.bib</kbd>, <kbd>.bibtex</kbd>, or <kbd>.json</kbd> extension), which we do either via the <kbd>#+bibliography</kbd>
|
||||
keyword, or the variable <code>org-cite-global-bibliography</code>.
|
||||
</p>
|
||||
<details id='org4ae6a8f' class='code' open>
|
||||
<summary></summary>
|
||||
<div class='gutter'><a href='#org4ae6a8f'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<pre class="example" id="org4ae6a8f">
|
||||
#+bibliography: orgcite.bib
|
||||
</pre>
|
||||
|
||||
</details>
|
||||
|
||||
<p>
|
||||
Once you have a bibliography source, you can start referencing to your heart’s
|
||||
content! The basic citation syntax is as follows:
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org721f3f8">
|
||||
<img src="figures/citation-structure-basic.svg" alt="citation-structure-basic.svg" class="org-svg">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 1: </span>The new citation syntax, for simple citations</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
Using the default style <kbd>[cite:@OrgCitations]</kbd> produces (<a href="#citeproc_bib_item_1">org et al. 2021</a>). For
|
||||
more information on the styles currently available, see <a href="#cite-styles">1</a>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Finally, to insert a bibliography somewhere, we just need to insert the
|
||||
<kbd>#+print_bibliography</kbd> keyword, like so:
|
||||
</p>
|
||||
|
||||
<details id='org9df92d6' class='code' open>
|
||||
<summary></summary>
|
||||
<div class='gutter'><a href='#org9df92d6'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<pre class="example" id="org9df92d6">
|
||||
#+print_bibliography:
|
||||
</pre>
|
||||
|
||||
</details>
|
||||
|
||||
<div class="info" id="org5a6bfbe">
|
||||
<style>.csl-entry{text-indent: -1.5em; margin-left: 1.5em;}</style><div class="csl-bib-body">
|
||||
<div class="csl-entry"><a id="citeproc_bib_item_1"></a>org, mode, Citation Syntax, Mailing List, and Time Effort. 2021. “Elegant Citations with Org-Mode.” <i>Journal of Plain Text Formats</i> 42 (1): 2–3.</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<p>
|
||||
So, to summarise, all one needs to get started is:
|
||||
</p>
|
||||
<details id='org125df34' class='code' open>
|
||||
<summary></summary>
|
||||
<div class='gutter'><a href='#org125df34'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<pre class="example" id="org125df34">
|
||||
#+bibliography: references.bib
|
||||
[cite:@key]
|
||||
#+print_bibliography:
|
||||
</pre>
|
||||
|
||||
</details>
|
||||
<p>
|
||||
That’s it! 🎉
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-cite-syntax" class="outline-3">
|
||||
<h3 id="cite-syntax">The cite syntax<a aria-hidden="true" href="#cite-syntax">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-cite-syntax">
|
||||
<p>
|
||||
Don’t let the simplicity in the examples above fool you, the new syntax is quite
|
||||
capable of expressing more complex forms. Here’s the <i>full</i> version of the new
|
||||
cite syntax:
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org1074ca2">
|
||||
<img src="figures/citation-structure-full.svg" alt="citation-structure-full.svg" class="org-svg">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 2: </span>The new citations syntax, in full</figcaption>
|
||||
</figure>
|
||||
|
||||
<ul class="org-ul">
|
||||
<li>The <b>style</b> and <b>variant</b> determine what form the exported citation takes</li>
|
||||
<li>The <b>common prefix</b> and <b>suffix</b> and put at the start and end of the generated
|
||||
citation, respectively</li>
|
||||
<li>The citation <b>key</b> refers to a Bib(La)TeX or <span class='acr'>CSL</span>-<span class='acr'>JSON</span> key
|
||||
<ul class="org-ul">
|
||||
<li>The citation <b>prefix</b> and <b>suffix</b> are put before and after the reference to the
|
||||
key</li>
|
||||
<li>Some citation processors recognise locators, which refer to a particular
|
||||
part of the work, for example: <kbd>p. 7</kbd> to refer to page 7.</li>
|
||||
</ul></li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
Using the default <span class='acr'>CSL</span> citation style (Chicago author-name) <kbd>[cite/l/b:see
|
||||
@OrgCitations pp. 7 for fun]</kbd> becomes see <a href="#citeproc_bib_item_1">7</a> for fun.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The citation styles and variants, and recognised locators are handled by the
|
||||
citation processors. Org cite’s bundled processors currently supports the
|
||||
following citation styles.
|
||||
</p>
|
||||
|
||||
<div id='cite-styles' class='table'>
|
||||
<div class='gutter'><a href='#cite-styles'>#</a></div>
|
||||
<div class='tabular'>
|
||||
<table>
|
||||
<caption class="t-above"><span class="table-number">Table 1:</span> The current set of supported citation styles with variants, with samples generated by <code>oc-csl.el</code> and <code>citeproc.el</code>.</caption>
|
||||
|
||||
<colgroup>
|
||||
<col class="org-left">
|
||||
|
||||
<col class="org-left">
|
||||
|
||||
<col class="org-left">
|
||||
|
||||
<col class="org-left">
|
||||
|
||||
<col class="org-left">
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr>
|
||||
<th scope="col" class="org-left">Style</th>
|
||||
<th scope="col" class="org-left">Variant</th>
|
||||
<th scope="col" class="org-left">Sample</th>
|
||||
<th scope="col" class="org-left">Bib(La)TeX</th>
|
||||
<th scope="col" class="org-left">NatBib</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td class="org-left"><kbd>a</kbd> author</td>
|
||||
<td class="org-left"><kbd>cf</kbd> caps-full</td>
|
||||
<td class="org-left">(<a href="#citeproc_bib_item_1">Org, Syntax, List, and Effort</a>)</td>
|
||||
<td class="org-left">Citeauthor</td>
|
||||
<td class="org-left"> </td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left"><kbd>a</kbd> author</td>
|
||||
<td class="org-left"><kbd>f</kbd> full</td>
|
||||
<td class="org-left">(<a href="#citeproc_bib_item_1">org, Syntax, List, and Effort</a>)</td>
|
||||
<td class="org-left">citeauthor</td>
|
||||
<td class="org-left">citeauthor*</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left"><kbd>a</kbd> author</td>
|
||||
<td class="org-left"><kbd>c</kbd> caps</td>
|
||||
<td class="org-left">(<a href="#citeproc_bib_item_1">Org et al.</a>)</td>
|
||||
<td class="org-left">Citeauthor*</td>
|
||||
<td class="org-left">Citeauthor</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left"><kbd>a</kbd> author</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">(<a href="#citeproc_bib_item_1">org et al.</a>)</td>
|
||||
<td class="org-left">citeauthor*</td>
|
||||
<td class="org-left">citeauthor</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td class="org-left"><kbd>na</kbd> noauthor</td>
|
||||
<td class="org-left"><kbd>b</kbd> bare</td>
|
||||
<td class="org-left"><a href="#citeproc_bib_item_1">2021</a></td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">citeyear</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left"><kbd>na</kbd> noauthor</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">(<a href="#citeproc_bib_item_1">2021</a>)</td>
|
||||
<td class="org-left">autocite*</td>
|
||||
<td class="org-left">citeyearpar</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td class="org-left"><kbd>l</kbd> locators</td>
|
||||
<td class="org-left"><kbd>bc</kbd> bare-caps</td>
|
||||
<td class="org-left">(<a href="#citeproc_bib_item_1">2</a>)</td>
|
||||
<td class="org-left">Notecite</td>
|
||||
<td class="org-left"> </td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left"><kbd>l</kbd> locators</td>
|
||||
<td class="org-left"><kbd>b</kbd> bare</td>
|
||||
<td class="org-left"><a href="#citeproc_bib_item_1">2</a></td>
|
||||
<td class="org-left">notecite</td>
|
||||
<td class="org-left"> </td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left"><kbd>l</kbd> locators</td>
|
||||
<td class="org-left"><kbd>bc</kbd> caps</td>
|
||||
<td class="org-left">(, <a href="#citeproc_bib_item_1">2</a>)</td>
|
||||
<td class="org-left">Pnotecite</td>
|
||||
<td class="org-left"> </td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left"><kbd>l</kbd> locators</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">(, <a href="#citeproc_bib_item_1">2</a>)</td>
|
||||
<td class="org-left">pnotecite</td>
|
||||
<td class="org-left"> </td>
|
||||
</tr>
|
||||
</tbody>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td class="org-left"><kbd>n</kbd> nocite</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">nocite</td>
|
||||
<td class="org-left">nocite</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td class="org-left"><kbd>t</kbd> text</td>
|
||||
<td class="org-left"><kbd>b</kbd> bare</td>
|
||||
<td class="org-left">org et al. (<a href="#citeproc_bib_item_1">2021</a>)</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">citealp</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left"><kbd>t</kbd> text</td>
|
||||
<td class="org-left"><kbd>c</kbd> caps</td>
|
||||
<td class="org-left">Org et al. (<a href="#citeproc_bib_item_1">2021</a>)</td>
|
||||
<td class="org-left">Textcite</td>
|
||||
<td class="org-left">Citep</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left"><kbd>t</kbd> text</td>
|
||||
<td class="org-left"><kbd>f</kbd> full</td>
|
||||
<td class="org-left">org, Syntax, List, and Effort (<a href="#citeproc_bib_item_1">2021</a>)</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">citep*</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left"><kbd>t</kbd> text</td>
|
||||
<td class="org-left"><kbd>bc</kbd> bare-caps</td>
|
||||
<td class="org-left">org et al. (<a href="#citeproc_bib_item_1">2021</a>)</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">Citealp</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left"><kbd>t</kbd> text</td>
|
||||
<td class="org-left"><kbd>bf</kbd> bare-full</td>
|
||||
<td class="org-left">org et al. (<a href="#citeproc_bib_item_1">2021</a>)</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">citealp*</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left"><kbd>t</kbd> text</td>
|
||||
<td class="org-left"><kbd>cf</kbd> caps-full</td>
|
||||
<td class="org-left">Org, Syntax, List, and Effort (<a href="#citeproc_bib_item_1">2021</a>)</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">Citep*</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left"><kbd>t</kbd> text</td>
|
||||
<td class="org-left"><kbd>bcf</kbd> bare-caps-full</td>
|
||||
<td class="org-left">org et al. (<a href="#citeproc_bib_item_1">2021</a>)</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">Citealp*</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left"><kbd>t</kbd> text</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">org et al. (<a href="#citeproc_bib_item_1">2021</a>)</td>
|
||||
<td class="org-left">textcite</td>
|
||||
<td class="org-left"> </td>
|
||||
</tr>
|
||||
</tbody>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td class="org-left">(default)</td>
|
||||
<td class="org-left"><kbd>b</kbd> bare</td>
|
||||
<td class="org-left"><a href="#citeproc_bib_item_1">org et al. 2021</a></td>
|
||||
<td class="org-left">cite</td>
|
||||
<td class="org-left">citealp</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left">(default)</td>
|
||||
<td class="org-left"><kbd>bc</kbd> bare-caps</td>
|
||||
<td class="org-left"><a href="#citeproc_bib_item_1">Org et al. 2021</a></td>
|
||||
<td class="org-left">Cite</td>
|
||||
<td class="org-left">Citealp</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left">(default)</td>
|
||||
<td class="org-left"><kbd>f</kbd> full</td>
|
||||
<td class="org-left">(<a href="#citeproc_bib_item_1">org et al. 2021</a>)</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">citep*</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left">(default)</td>
|
||||
<td class="org-left"><kbd>bf</kbd> bare-full</td>
|
||||
<td class="org-left">(<a href="#citeproc_bib_item_1">org et al. 2021</a>)</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">citealp</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left">(default)</td>
|
||||
<td class="org-left"><kbd>cf</kbd> caps-full</td>
|
||||
<td class="org-left">(<a href="#citeproc_bib_item_1">org et al. 2021</a>)</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">Citep*</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left">(default)</td>
|
||||
<td class="org-left"><kbd>bcf</kbd> bare-caps-full</td>
|
||||
<td class="org-left">(<a href="#citeproc_bib_item_1">org et al. 2021</a>)</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">Citealp*</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-left">(default)</td>
|
||||
<td class="org-left"> </td>
|
||||
<td class="org-left">(<a href="#citeproc_bib_item_1">org et al. 2021</a>)</td>
|
||||
<td class="org-left">autocite</td>
|
||||
<td class="org-left">citep</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div></div>
|
||||
|
||||
<p>
|
||||
The <span class='acr'>CSL</span> processor supports the following locators:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li><b><kbd>book</kbd></b>, <kbd>bk.</kbd>, <kbd>bks.</kbd></li>
|
||||
<li><b><kbd>chapter</kbd></b>, <kbd>chap.</kbd>, <kbd>chaps.</kbd></li>
|
||||
<li><b><kbd>column</kbd></b>, <kbd>col.</kbd>, <kbd>cols.</kbd></li>
|
||||
<li><b><kbd>figure</kbd></b>, <kbd>fig.</kbd>, <kbd>figs.</kbd></li>
|
||||
<li><b><kbd>folio</kbd></b>, <kbd>fol.</kbd>, <kbd>fols.</kbd></li>
|
||||
<li><b><kbd>number</kbd></b>, <kbd>no.</kbd>, <kbd>Os.</kbd></li>
|
||||
<li><b><kbd>line</kbd></b>, <kbd>l.</kbd>, <kbd>ll.</kbd></li>
|
||||
<li><b><kbd>note</kbd></b>, <kbd>n.</kbd>, <kbd>nn.</kbd></li>
|
||||
<li><b><kbd>opus</kbd></b>, <kbd>op.</kbd>, <kbd>opp.</kbd></li>
|
||||
<li><b><kbd>page</kbd></b>, <kbd>p</kbd>, <kbd>p.</kbd>, <kbd>pp.</kbd></li>
|
||||
<li><b><kbd>paragraph</kbd></b>, <kbd>para.</kbd>, <kbd>paras.</kbd>, <kbd>¶</kbd>, <kbd>¶¶</kbd>, <kbd>§</kbd>, <kbd>§§</kbd></li>
|
||||
<li><b><kbd>part</kbd></b>, <kbd>pt.</kbd>, <kbd>pts.</kbd></li>
|
||||
<li><b><kbd>section</kbd></b>, <kbd>sec.</kbd>, <kbd>secs.</kbd></li>
|
||||
<li><b><kbd>sub verbo</kbd></b>, <kbd>s.v.</kbd>, <kbd>s.vv.</kbd></li>
|
||||
<li><b><kbd>verse</kbd></b>, <kbd>v.</kbd>, <kbd>vv.</kbd></li>
|
||||
<li><b><kbd>volume</kbd></b>, <kbd>vol.</kbd>, <kbd>vols.</kbd></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-more-exporting" class="outline-3">
|
||||
<h3 id="more-exporting">More on exporting<a aria-hidden="true" href="#more-exporting">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-more-exporting">
|
||||
<p>
|
||||
The style of the citations and the bibliography depend on three things:
|
||||
</p>
|
||||
<ol class="org-ol">
|
||||
<li>The citation processor used</li>
|
||||
<li>The citation style</li>
|
||||
<li>The bibliography style</li>
|
||||
</ol>
|
||||
|
||||
<p>
|
||||
The citation processor is automatically selected based on
|
||||
<code>org-cite-export-processors</code> based on the export format being used, but can be set
|
||||
on a per-document basis via the <kbd>#+cite_export</kbd> keyword. Here, I shall use the <kbd>csl</kbd>
|
||||
processor,
|
||||
</p>
|
||||
<details id='org60a54b9' class='code' open>
|
||||
<summary></summary>
|
||||
<div class='gutter'><a href='#org60a54b9'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<pre class="example" id="org60a54b9">
|
||||
#+cite_export: csl
|
||||
</pre>
|
||||
|
||||
</details>
|
||||
|
||||
<p>
|
||||
With <code>org-cite-export-processors</code>, you can also set the bibliography and citation
|
||||
style by giving a triplet of parameters <code class="src src-elisp">(PROCESSOR BIBLIOGRAPHY-STYLE CITATION-STYLE)</code> instead of just the processor. You can also use this triplet of
|
||||
values with the <kbd>#+cite_export</kbd> keyword
|
||||
</p>
|
||||
<details id='org65a9b55' class='code' open>
|
||||
<summary></summary>
|
||||
<div class='gutter'><a href='#org65a9b55'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<pre class="example" id="org65a9b55">
|
||||
#+cite_export: processor bibliography-style citation-style
|
||||
</pre>
|
||||
|
||||
</details>
|
||||
|
||||
<p>
|
||||
There are also some more options about how the bibliography is produced. These
|
||||
options are handled by the active citation processor. For example, while the <span class='acr'>CSL</span>
|
||||
processor does not currently support any options, the BibLaTeX processor passes
|
||||
options to a <code class="src src-LaTeX"><span class="org-keyword">\printbibliography</span></code> command, allowing for the
|
||||
following:
|
||||
</p>
|
||||
<details id='org62f4f7e' class='code' open>
|
||||
<summary></summary>
|
||||
<div class='gutter'><a href='#org62f4f7e'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<pre class="example" id="org62f4f7e">
|
||||
#+print_bibliography: :section 2 :heading subbibliography
|
||||
#+print_bibliography: :keyword abc,xyz :title "Primary Sources"
|
||||
</pre>
|
||||
|
||||
</details>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-using-csl" class="outline-3">
|
||||
<h3 id="using-csl">Using <span class='acr'><span class='acr'>CSL</span></span><a aria-hidden="true" href="#using-csl">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-using-csl">
|
||||
<p>
|
||||
<a href="https://github.com/andras-simonyi/citeproc-el">Citeproc</a> is currently available on <a href="https://melpa.org/#/citeproc"><span class='acr'>MELPA</span></a>, and so can be installed via your
|
||||
package manager of choice so long as <span class='acr'>MELPA</span> is included in your
|
||||
<code>package-archives</code>. When available, it will be automatically loaded by
|
||||
<kbd>oc-csl.el</kbd>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
It currently supports exporting to:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li><span class='acr'>HTML</span></li>
|
||||
<li>LaTeX</li>
|
||||
<li>Org</li>
|
||||
<li>Plain text</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
Should you be interested in other formats, know that Citeproc is designed to
|
||||
easily support adding new formats (see <kbd>citeproc-formatters.el</kbd> for examples).
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Citeproc can currently retrieve bibliographic information from the following
|
||||
formats:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li><span class='acr'>CSL</span>-<span class='acr'>JSON</span></li>
|
||||
<li>Bib(La)TeX</li>
|
||||
<li>org-bibtex</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
Though support for Bib(La)TeX and <a href="https://gewhere.github.io/org-bibtex">org-bibtex</a> is rudimentary compared to <span class='acr'>CSL</span>-<span class='acr'>JSON</span>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
When exporting, you can set the style by providing a path to <span class='acr'>CSL</span> style files,
|
||||
either absolute or relative to <code>org-cite-csl-styles-dir</code>. For example, if I
|
||||
download <kbd>apa.csl</kbd> I can use it like so:
|
||||
</p>
|
||||
<details id='org4d92789' class='code' open>
|
||||
<summary></summary>
|
||||
<div class='gutter'><a href='#org4d92789'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<pre class="example" id="org4d92789">
|
||||
#+cite_export: csl ~/Downloads/apa.csl
|
||||
</pre>
|
||||
|
||||
</details>
|
||||
|
||||
<p>
|
||||
When no style is given <code>org-cite-csl--fallback-style-file</code> will be used, which
|
||||
defaults to a bundled Chicago author-date style.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-working-with-zotero" class="outline-3">
|
||||
<h3 id="working-with-zotero">Working with Zotero<a aria-hidden="true" href="#working-with-zotero">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-working-with-zotero">
|
||||
<p>
|
||||
There are quite a few reference managers available, however, the list rapidly
|
||||
shrinks if you restrict yourself to applications which are:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li>somewhat feature-rich</li>
|
||||
<li>open source software</li>
|
||||
<li>not owned by a parasitic company<sup><a id="fnr.3" class="footref" href="#fn.3" role="doc-backlink">3</a></sup></li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
<a href="https://www.zotero.org/">Zotero</a> is a good option, and if you’re using it it’s quite easy to use it with
|
||||
Org Cite. Out of the box, you can tell it to export your library, or parts of it,
|
||||
to a <kbd>.bib</kbd> file and automatically keep it in sync. I’d recommend installing the
|
||||
<a href="https://retorque.re/zotero-better-bibtex/">Better BibTeX</a> extension though.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org3421fca">
|
||||
<img src="figures/zotero-export-library.png" alt="zotero-export-library.png" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 3: </span>Zotero library right click context menu, showing the export option</figcaption>
|
||||
</figure>
|
||||
|
||||
|
||||
<figure id="org36de69f">
|
||||
<img src="figures/zotero-export-options-prompt.png" alt="zotero-export-options-prompt.png" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 4: </span>Zotero collection export dialog</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
Zotero also works well with <span class='acr'>CSL</span>. In addition to supporting <span class='acr'>CSL</span>-<span class='acr'>JSON</span> exports,
|
||||
Zotero also features an easy way to install <span class='acr'>CSL</span> styles within the preferences.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="orgb936c75">
|
||||
<img src="figures/zotero-cite-styles-menu.png" alt="zotero-cite-styles-menu.png" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 5: </span>Zotero <span class='acr'>CSL</span> style management within preferences</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
Since these files are put under <kbd>~/Zotero/styles</kbd>, you can use them with Org Cite
|
||||
and Citeproc simply by setting <code>org-cite-csl-styles-dir</code> to the Zotero styles
|
||||
directory.
|
||||
</p>
|
||||
<details id='working-with-zotero,code--1' class='code' open><summary><span class="lang">Emacs Lisp</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#working-with-zotero,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-emacs-lisp">(<span class="org-keyword">setq</span> org-cite-csl-styles-dir <span class="org-string">"~/Zotero/styles"</span>)
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
To then use the citation style defined by <kbd>~/Zotero/styles/apa.csl</kbd> one can then
|
||||
simply refer to <kbd>apa.csl</kbd> when using the <kbd>#+cite_export</kbd> keyword.
|
||||
</p>
|
||||
<details id='org00c3ad4' class='code' open>
|
||||
<summary></summary>
|
||||
<div class='gutter'><a href='#org00c3ad4'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<pre class="example" id="org00c3ad4">
|
||||
#+cite_export: csl apa.csl
|
||||
</pre>
|
||||
|
||||
</details>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-bright-future" class="outline-3">
|
||||
<h3 id="bright-future">A bright future<a aria-hidden="true" href="#bright-future">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-bright-future">
|
||||
<p>
|
||||
Org Cite has only just been merged in the past month, and is yet to be included
|
||||
in an Org release, but we’re seeing a tremendous degree of community interest.
|
||||
There are <i>already</i> promising developments with third-party packages, such as
|
||||
<a href="https://github.com/bdarcus/bibtex-actions">bibtex-actions</a> and <a href="https://github.com/jkitchin/org-ref-cite">org-ref-cite</a>. I can’t wait to see how the ecosystem continues
|
||||
to develop 😃.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="footnotes">
|
||||
<h2 class="footnotes">Footnotes: </h2>
|
||||
<div id="text-footnotes">
|
||||
|
||||
<div class="footdef"><sup><a id="fn.1" class="footnum" href="#fnr.1" role="doc-backlink">1</a></sup> <div class="footpara" role="doc-footnote"><p class="footpara">
|
||||
Citations were first being mentioned on the mailing list back in 2007, in
|
||||
<a href="https://lists.gnu.org/archive/html/emacs-orgmode/2007-05/msg00146.html">a thread about footnotes</a>.
|
||||
</p></div></div>
|
||||
|
||||
<div class="footdef"><sup><a id="fn.2" class="footnum" href="#fnr.2" role="doc-backlink">2</a></sup> <div class="footpara" role="doc-footnote"><p class="footpara">
|
||||
There is currently an <a href="https://github.com/andras-simonyi/org-cite-csl-activate">ongoing effort</a> to use <kbd>oc.el</kbd> and <kbd>citeproc.el</kbd> to
|
||||
produce citation overlays in the buffer.
|
||||
</p></div></div>
|
||||
|
||||
<div class="footdef"><sup><a id="fn.3" class="footnum" href="#fnr.3" role="doc-backlink">3</a></sup> <div class="footpara" role="doc-footnote"><p class="footpara">
|
||||
I’m talking about a certain company <a href="https://moneyweek.com/505757/great-frauds-in-history-robert-maxwell">created by a British Fraudster</a> that
|
||||
has a <a href="https://www.theguardian.com/science/2017/jun/27/profitable-business-scientific-publishing-bad-for-science">40% profit margin, engages in blackmail-like practices with universities</a>,
|
||||
prompted <a href="http://thecostofknowledge.com/">19,000 researchers</a> to boycott them, <a href="https://www.the-scientist.com/the-nutshell/elsevier-published-6-fake-journals-44160">published six fake journals</a>,
|
||||
vigorously <a href="https://web.archive.org/web/20200129202353/http://legacy.earlham.edu/~peters/fos/2007/08/publishers-launch-anti-oa-lobbying.html">lobbys against Open Access</a>, <a href="https://rossmounce.co.uk/2017/02/14/elsevier-selling-access-to-open-access-again/">charged for Open Acess articles</a>
|
||||
(repeatedly), made <a href="https://www.michaeleisen.org/blog/?p=807">financial contributions to politicians who then tried to
|
||||
prevent publicly accesible reaserch</a>, and whose reference manager <a href="https://www.zotero.org/support/kb/mendeley_import#mendeley_database_encryption">encrypted
|
||||
reaserchers’ <i>own</i> databases</a> “to comply with <span class='acr'>GDPR</span>”.
|
||||
</p></div></div>
|
||||
|
||||
|
||||
</div>
|
||||
</div></div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,15 +1,13 @@
|
|||
# Created 2024-01-12 Fri 13:39
|
||||
#+title: July 2021
|
||||
#+subtitle: Introducing citations!
|
||||
#+author: TEC
|
||||
#+date: 2021-07-31
|
||||
|
||||
#+author: TEC
|
||||
#+subtitle: Introducing citations!
|
||||
Last month I not-at-all-subtly hinted that a certain long-awaited feature was
|
||||
arriving imminently. At this point, I think it's a good idea to set the tone for the rest of
|
||||
this post.
|
||||
|
||||
#+attr_latex: :options inkscapelatex=false
|
||||
[[file:figures/celebrate-citations.svg]]
|
||||
|
||||
* Citations
|
||||
|
||||
After /years/ of (on and off) discussion[fn:1], I am elated to be able to present
|
||||
|
|
@ -25,14 +23,16 @@ András Simonyi's also deserves a special mention for his work creating the Elis
|
|||
CSL library ~Citeproc.el~, which while not directly included in Org is crucial to
|
||||
providing robust CSL support, and integrates with =oc-csl.el=.
|
||||
|
||||
[fn:1] Citations were first being mentioned on the mailing list back in 2007, in
|
||||
[[https://lists.gnu.org/archive/html/emacs-orgmode/2007-05/msg00146.html][a thread about footnotes]].
|
||||
** Outline
|
||||
|
||||
Citations have been carefully designed in such a way that users and Elisp
|
||||
tinkerers will be able to easily adapt and extend it to fit their needs.
|
||||
To that end, Org Cite (or OC for short) has been split into two halves:
|
||||
+ =oc.el= which defines the syntax and provides some machinery to interact with
|
||||
- =oc.el= which defines the syntax and provides some machinery to interact with
|
||||
citations
|
||||
+ Citation processors which interface with =oc.el= to produce nicely-formatted
|
||||
- Citation processors which interface with =oc.el= to produce nicely-formatted
|
||||
citations to be inserted in your bibliography, within the text, and even
|
||||
rendered in the buffer[fn:2]
|
||||
|
||||
|
|
@ -46,11 +46,11 @@ Each capability can have a particular citation processor assigned, independently
|
|||
of the others. Out of the box, Org uses the =basic= processor for all of these tasks.
|
||||
|
||||
The =basic= citation processor is one of four currently bundled with Org:
|
||||
+ =basic=, which has no dependencies and provides all four capabilities. It export
|
||||
- =basic=, which has no dependencies and provides all four capabilities. It export
|
||||
to all formats, but only provides very simple citations.
|
||||
+ =biblatex= and =natbib=, which provide the export capability to create citations
|
||||
- =biblatex= and =natbib=, which provide the export capability to create citations
|
||||
via [[http://biblatex-biber.sourceforge.net/][Biber]] and (to a lesser extent) [[https://ctan.org/pkg/natbib][natbib]], but only for LaTeX.
|
||||
+ =csl=, which provides the export capability using the [[https://citationstyles.org/][Citation Style Language]],
|
||||
- =csl=, which provides the export capability using the [[https://citationstyles.org/][Citation Style Language]],
|
||||
and exports to HTML, LaTeX, Org, and plain text (with an [[https://github.com/andras-simonyi/citeproc-el/issues/23][open issue]] for ODT)
|
||||
--- but depends on [[https://github.com/andras-simonyi/citeproc-el][citeproc.el]].
|
||||
|
||||
|
|
@ -58,29 +58,31 @@ This provides a solid foundation for other packages to build off, and despite
|
|||
Org Cite being yet to be released or documented in the manual we are already
|
||||
seeing the development of packages like [[https://github.com/jkitchin/org-ref-cite][org-ref-cite]] (by John Kitchin).
|
||||
|
||||
[fn:2] There is currently an [[https://github.com/andras-simonyi/org-cite-csl-activate][ongoing effort]] to use =oc.el= and =citeproc.el= to
|
||||
produce citation overlays in the buffer.
|
||||
** Basic usage
|
||||
|
||||
To get started with Org Cite, we must have some form of bibliography.
|
||||
This can either be a BibTeX file or a CSL-JSON file.
|
||||
|
||||
As an example, say we have a file =orgcite.bib= containing the following
|
||||
#+begin_src bibtex :tangle orgcite.bib :comments none
|
||||
@article{OrgCitations,
|
||||
author={org, mode and Syntax, Citation and List, Mailing and Effort, Time},
|
||||
journal={Journal of Plain Text Formats},
|
||||
title={Elegant Citations with Org-Mode},
|
||||
year={2021},
|
||||
month={7},
|
||||
volume={42},
|
||||
number={1},
|
||||
pages={2-3}}
|
||||
#+begin_src bibtex
|
||||
@article{OrgCitations,
|
||||
author={org, mode and Syntax, Citation and List, Mailing and Effort, Time},
|
||||
journal={Journal of Plain Text Formats},
|
||||
title={Elegant Citations with Org-Mode},
|
||||
year={2021},
|
||||
month={7},
|
||||
volume={42},
|
||||
number={1},
|
||||
pages={2-3}}
|
||||
#+end_src
|
||||
|
||||
First we need to let Org know about this bibliography file (which must have a
|
||||
=.bib=, =.bibtex=, or =.json= extension), which we do either via the =#+bibliography=
|
||||
keyword, or the variable ~org-cite-global-bibliography~.
|
||||
#+begin_example
|
||||
,#+bibliography: orgcite.bib
|
||||
,#+bibliography: orgcite.bib
|
||||
#+end_example
|
||||
|
||||
#+bibliography: orgcite.bib
|
||||
|
|
@ -89,31 +91,29 @@ Once you have a bibliography source, you can start referencing to your heart's
|
|||
content! The basic citation syntax is as follows:
|
||||
|
||||
#+caption: The new citation syntax, for simple citations
|
||||
#+attr_latex: :width 0.5\linewidth :options inkscapelatex=false
|
||||
[[file:figures/citation-structure-basic.svg]]
|
||||
|
||||
Using the default style =[cite:@OrgCitations]= produces [cite:@OrgCitations]. For
|
||||
Using the default style =[cite:@OrgCitations]= produces ([[citeproc_bib_item_1][org et al. 2021]]). For
|
||||
more information on the styles currently available, see [[cite-styles]].
|
||||
|
||||
Finally, to insert a bibliography somewhere, we just need to insert the
|
||||
=#+print_bibliography= keyword, like so:
|
||||
|
||||
#+begin_example
|
||||
,#+print_bibliography:
|
||||
,#+print_bibliography:
|
||||
#+end_example
|
||||
|
||||
#+begin_info
|
||||
#+print_bibliography:
|
||||
<<citeproc_bib_item_1>>org, mode, Citation Syntax, Mailing List, and Time Effort. 2021. “Elegant Citations with Org-Mode.” /Journal of Plain Text Formats/ 42 (1): 2–3.
|
||||
#+end_info
|
||||
|
||||
So, to summarise, all one needs to get started is:
|
||||
#+begin_example
|
||||
,#+bibliography: references.bib
|
||||
[cite:@key]
|
||||
,#+print_bibliography:
|
||||
,#+bibliography: references.bib
|
||||
[cite:@key]
|
||||
,#+print_bibliography:
|
||||
#+end_example
|
||||
That's it! 🎉
|
||||
|
||||
** The cite syntax
|
||||
|
||||
Don't let the simplicity in the examples above fool you, the new syntax is quite
|
||||
|
|
@ -121,20 +121,19 @@ capable of expressing more complex forms. Here's the /full/ version of the new
|
|||
cite syntax:
|
||||
|
||||
#+caption: The new citations syntax, in full
|
||||
#+attr_latex: :options inkscapelatex=false
|
||||
[[file:figures/citation-structure-full.svg]]
|
||||
|
||||
+ The *style* and *variant* determine what form the exported citation takes
|
||||
+ The *common prefix* and *suffix* and put at the start and end of the generated
|
||||
- The *style* and *variant* determine what form the exported citation takes
|
||||
- The *common prefix* and *suffix* and put at the start and end of the generated
|
||||
citation, respectively
|
||||
+ The citation *key* refers to a Bib(La)TeX or CSL-JSON key
|
||||
- The citation *key* refers to a Bib(La)TeX or CSL-JSON key
|
||||
- The citation *prefix* and *suffix* are put before and after the reference to the
|
||||
key
|
||||
- Some citation processors recognise locators, which refer to a particular
|
||||
part of the work, for example: =p. 7= to refer to page 7.
|
||||
|
||||
Using the default CSL citation style (Chicago author-name) =[cite/l/b:see
|
||||
@OrgCitations pp. 7 for fun]= becomes [cite/l/b:see @OrgCitations pp. 7 for fun].
|
||||
@OrgCitations pp. 7 for fun]= becomes see [[citeproc_bib_item_1][7]] for fun.
|
||||
|
||||
The citation styles and variants, and recognised locators are handled by the
|
||||
citation processors. Org cite's bundled processors currently supports the
|
||||
|
|
@ -143,59 +142,57 @@ following citation styles.
|
|||
#+name: cite-styles
|
||||
#+caption: The current set of supported citation styles with variants,
|
||||
#+caption: with samples generated by ~oc-csl.el~ and ~citeproc.el~.
|
||||
#+attr_latex: :font \small
|
||||
| Style | Variant | Sample | Bib(La)TeX | NatBib |
|
||||
|-------------+--------------------+---------------------------------+-------------+-------------|
|
||||
| =a= author | =cf= caps-full | [cite/a/cf:@OrgCitations] | Citeauthor | |
|
||||
| =a= author | =f= full | [cite/a/f:@OrgCitations] | citeauthor | citeauthor* |
|
||||
| =a= author | =c= caps | [cite/a/c:@OrgCitations] | Citeauthor* | Citeauthor |
|
||||
| =a= author | | [cite/a:@OrgCitations] | citeauthor* | citeauthor |
|
||||
|-------------+--------------------+---------------------------------+-------------+-------------|
|
||||
| =na= noauthor | =b= bare | [cite/na/b:@OrgCitations] | | citeyear |
|
||||
| =na= noauthor | | [cite/na:@OrgCitations] | autocite* | citeyearpar |
|
||||
|-------------+--------------------+---------------------------------+-------------+-------------|
|
||||
| =l= locators | =bc= bare-caps | [cite/l/bc:@OrgCitations p. 2] | Notecite | |
|
||||
| =l= locators | =b= bare | [cite/l/b:@OrgCitations p. 2] | notecite | |
|
||||
| =l= locators | =bc= caps | [cite/l/bc:@OrgCitations, p. 2] | Pnotecite | |
|
||||
| =l= locators | | [cite/l:@OrgCitations, p. 2] | pnotecite | |
|
||||
|-------------+--------------------+---------------------------------+-------------+-------------|
|
||||
| =n= nocite | | [cite/n:@OrgCitations] | nocite | nocite |
|
||||
|-------------+--------------------+---------------------------------+-------------+-------------|
|
||||
| =t= text | =b= bare | [cite/t/b:@OrgCitations] | | citealp |
|
||||
| =t= text | =c= caps | [cite/t/c:@OrgCitations] | Textcite | Citep |
|
||||
| =t= text | =f= full | [cite/t/f:@OrgCitations] | | citep* |
|
||||
| =t= text | =bc= bare-caps | [cite/t/bc:@OrgCitations] | | Citealp |
|
||||
| =t= text | =bf= bare-full | [cite/t/bf:@OrgCitations] | | citealp* |
|
||||
| =t= text | =cf= caps-full | [cite/t/cf:@OrgCitations] | | Citep* |
|
||||
| =t= text | =bcf= bare-caps-full | [cite/t/bcf:@OrgCitations] | | Citealp* |
|
||||
| =t= text | | [cite/t:@OrgCitations] | textcite | |
|
||||
|-------------+--------------------+---------------------------------+-------------+-------------|
|
||||
| (default) | =b= bare | [cite//b:@OrgCitations] | cite | citealp |
|
||||
| (default) | =bc= bare-caps | [cite//bc:@OrgCitations] | Cite | Citealp |
|
||||
| (default) | =f= full | [cite//f:@OrgCitations] | | citep* |
|
||||
| (default) | =bf= bare-full | [cite//bf:@OrgCitations] | | citealp |
|
||||
| (default) | =cf= caps-full | [cite//cf:@OrgCitations] | | Citep* |
|
||||
| (default) | =bcf= bare-caps-full | [cite//bcf:@OrgCitations] | | Citealp* |
|
||||
| (default) | | [cite:@OrgCitations] | autocite | citep |
|
||||
| Style | Variant | Sample | Bib(La)TeX | NatBib |
|
||||
|---------------+----------------------+---------------------------------------------------------------+-------------+-------------|
|
||||
| =a= author | =cf= caps-full | ([[citeproc_bib_item_1][Org, Syntax, List, and Effort]]) | Citeauthor | |
|
||||
| =a= author | =f= full | ([[citeproc_bib_item_1][org, Syntax, List, and Effort]]) | citeauthor | citeauthor* |
|
||||
| =a= author | =c= caps | ([[citeproc_bib_item_1][Org et al.]]) | Citeauthor* | Citeauthor |
|
||||
| =a= author | | ([[citeproc_bib_item_1][org et al.]]) | citeauthor* | citeauthor |
|
||||
|---------------+----------------------+---------------------------------------------------------------+-------------+-------------|
|
||||
| =na= noauthor | =b= bare | [[citeproc_bib_item_1][2021]] | | citeyear |
|
||||
| =na= noauthor | | ([[citeproc_bib_item_1][2021]]) | autocite* | citeyearpar |
|
||||
|---------------+----------------------+---------------------------------------------------------------+-------------+-------------|
|
||||
| =l= locators | =bc= bare-caps | ([[citeproc_bib_item_1][2]]) | Notecite | |
|
||||
| =l= locators | =b= bare | [[citeproc_bib_item_1][2]] | notecite | |
|
||||
| =l= locators | =bc= caps | (, [[citeproc_bib_item_1][2]]) | Pnotecite | |
|
||||
| =l= locators | | (, [[citeproc_bib_item_1][2]]) | pnotecite | |
|
||||
|---------------+----------------------+---------------------------------------------------------------+-------------+-------------|
|
||||
| =n= nocite | | | nocite | nocite |
|
||||
|---------------+----------------------+---------------------------------------------------------------+-------------+-------------|
|
||||
| =t= text | =b= bare | org et al. ([[citeproc_bib_item_1][2021]]) | | citealp |
|
||||
| =t= text | =c= caps | Org et al. ([[citeproc_bib_item_1][2021]]) | Textcite | Citep |
|
||||
| =t= text | =f= full | org, Syntax, List, and Effort ([[citeproc_bib_item_1][2021]]) | | citep* |
|
||||
| =t= text | =bc= bare-caps | org et al. ([[citeproc_bib_item_1][2021]]) | | Citealp |
|
||||
| =t= text | =bf= bare-full | org et al. ([[citeproc_bib_item_1][2021]]) | | citealp* |
|
||||
| =t= text | =cf= caps-full | Org, Syntax, List, and Effort ([[citeproc_bib_item_1][2021]]) | | Citep* |
|
||||
| =t= text | =bcf= bare-caps-full | org et al. ([[citeproc_bib_item_1][2021]]) | | Citealp* |
|
||||
| =t= text | | org et al. ([[citeproc_bib_item_1][2021]]) | textcite | |
|
||||
|---------------+----------------------+---------------------------------------------------------------+-------------+-------------|
|
||||
| (default) | =b= bare | [[citeproc_bib_item_1][org et al. 2021]] | cite | citealp |
|
||||
| (default) | =bc= bare-caps | [[citeproc_bib_item_1][Org et al. 2021]] | Cite | Citealp |
|
||||
| (default) | =f= full | ([[citeproc_bib_item_1][org et al. 2021]]) | | citep* |
|
||||
| (default) | =bf= bare-full | ([[citeproc_bib_item_1][org et al. 2021]]) | | citealp |
|
||||
| (default) | =cf= caps-full | ([[citeproc_bib_item_1][org et al. 2021]]) | | Citep* |
|
||||
| (default) | =bcf= bare-caps-full | ([[citeproc_bib_item_1][org et al. 2021]]) | | Citealp* |
|
||||
| (default) | | ([[citeproc_bib_item_1][org et al. 2021]]) | autocite | citep |
|
||||
|
||||
The CSL processor supports the following locators:
|
||||
+ *=book=*, =bk.=, =bks.=
|
||||
+ *=chapter=*, =chap.=, =chaps.=
|
||||
+ *=column=*, =col.=, =cols.=
|
||||
+ *=figure=*, =fig.=, =figs.=
|
||||
+ *=folio=*, =fol.=, =fols.=
|
||||
+ *=number=*, =no.=, =Os.=
|
||||
+ *=line=*, =l.=, =ll.=
|
||||
+ *=note=*, =n.=, =nn.=
|
||||
+ *=opus=*, =op.=, =opp.=
|
||||
+ *=page=*, =p=, =p.=, =pp.=
|
||||
+ *=paragraph=*, =para.=, =paras.=, =¶=, =¶¶=, =§=, =§§=
|
||||
+ *=part=*, =pt.=, =pts.=
|
||||
+ *=section=*, =sec.=, =secs.=
|
||||
+ *=sub verbo=*, =s.v.=, =s.vv.=
|
||||
+ *=verse=*, =v.=, =vv.=
|
||||
+ *=volume=*, =vol.=, =vols.=
|
||||
|
||||
- *=book=*, =bk.=, =bks.=
|
||||
- *=chapter=*, =chap.=, =chaps.=
|
||||
- *=column=*, =col.=, =cols.=
|
||||
- *=figure=*, =fig.=, =figs.=
|
||||
- *=folio=*, =fol.=, =fols.=
|
||||
- *=number=*, =no.=, =Os.=
|
||||
- *=line=*, =l.=, =ll.=
|
||||
- *=note=*, =n.=, =nn.=
|
||||
- *=opus=*, =op.=, =opp.=
|
||||
- *=page=*, =p=, =p.=, =pp.=
|
||||
- *=paragraph=*, =para.=, =paras.=, =¶=, =¶¶=, =§=, =§§=
|
||||
- *=part=*, =pt.=, =pts.=
|
||||
- *=section=*, =sec.=, =secs.=
|
||||
- *=sub verbo=*, =s.v.=, =s.vv.=
|
||||
- *=verse=*, =v.=, =vv.=
|
||||
- *=volume=*, =vol.=, =vols.=
|
||||
** More on exporting
|
||||
|
||||
The style of the citations and the bibliography depend on three things:
|
||||
|
|
@ -208,17 +205,16 @@ The citation processor is automatically selected based on
|
|||
on a per-document basis via the =#+cite_export= keyword. Here, I shall use the =csl=
|
||||
processor,
|
||||
#+begin_example
|
||||
,#+cite_export: csl
|
||||
,#+cite_export: csl
|
||||
#+end_example
|
||||
|
||||
#+cite_export: csl
|
||||
|
||||
With ~org-cite-export-processors~, you can also set the bibliography and citation
|
||||
style by giving a triplet of parameters src_elisp{(PROCESSOR BIBLIOGRAPHY-STYLE
|
||||
CITATION-STYLE)} instead of just the processor. You can also use this triplet of
|
||||
style by giving a triplet of parameters src_elisp{(PROCESSOR BIBLIOGRAPHY-STYLE CITATION-STYLE)} instead of just the processor. You can also use this triplet of
|
||||
values with the =#+cite_export= keyword
|
||||
#+begin_example
|
||||
,#+cite_export: processor bibliography-style citation-style
|
||||
,#+cite_export: processor bibliography-style citation-style
|
||||
#+end_example
|
||||
|
||||
There are also some more options about how the bibliography is produced. These
|
||||
|
|
@ -227,10 +223,9 @@ processor does not currently support any options, the BibLaTeX processor passes
|
|||
options to a src_LaTeX{\printbibliography} command, allowing for the
|
||||
following:
|
||||
#+begin_example
|
||||
,#+print_bibliography: :section 2 :heading subbibliography
|
||||
,#+print_bibliography: :keyword abc,xyz :title "Primary Sources"
|
||||
,#+print_bibliography: :section 2 :heading subbibliography
|
||||
,#+print_bibliography: :keyword abc,xyz :title "Primary Sources"
|
||||
#+end_example
|
||||
|
||||
** Using CSL
|
||||
|
||||
[[https://github.com/andras-simonyi/citeproc-el][Citeproc]] is currently available on [[https://melpa.org/#/citeproc][MELPA]], and so can be installed via your
|
||||
|
|
@ -239,19 +234,19 @@ package manager of choice so long as MELPA is included in your
|
|||
=oc-csl.el=.
|
||||
|
||||
It currently supports exporting to:
|
||||
+ HTML
|
||||
+ LaTeX
|
||||
+ Org
|
||||
+ Plain text
|
||||
- HTML
|
||||
- LaTeX
|
||||
- Org
|
||||
- Plain text
|
||||
|
||||
Should you be interested in other formats, know that Citeproc is designed to
|
||||
easily support adding new formats (see =citeproc-formatters.el= for examples).
|
||||
|
||||
Citeproc can currently retrieve bibliographic information from the following
|
||||
formats:
|
||||
+ CSL-JSON
|
||||
+ Bib(La)TeX
|
||||
+ org-bibtex
|
||||
- CSL-JSON
|
||||
- Bib(La)TeX
|
||||
- org-bibtex
|
||||
|
||||
Though support for Bib(La)TeX and [[https://gewhere.github.io/org-bibtex][org-bibtex]] is rudimentary compared to CSL-JSON.
|
||||
|
||||
|
|
@ -259,19 +254,18 @@ When exporting, you can set the style by providing a path to CSL style files,
|
|||
either absolute or relative to ~org-cite-csl-styles-dir~. For example, if I
|
||||
download =apa.csl= I can use it like so:
|
||||
#+begin_example
|
||||
,#+cite_export: csl ~/Downloads/apa.csl
|
||||
,#+cite_export: csl ~/Downloads/apa.csl
|
||||
#+end_example
|
||||
|
||||
When no style is given ~org-cite-csl--fallback-style-file~ will be used, which
|
||||
defaults to a bundled Chicago author-date style.
|
||||
|
||||
** Working with Zotero
|
||||
|
||||
There are quite a few reference managers available, however, the list rapidly
|
||||
shrinks if you restrict yourself to applications which are:
|
||||
+ somewhat feature-rich
|
||||
+ open source software
|
||||
+ not owned by a parasitic company[fn:3]
|
||||
- somewhat feature-rich
|
||||
- open source software
|
||||
- not owned by a parasitic company[fn:3]
|
||||
|
||||
[[https://www.zotero.org/][Zotero]] is a good option, and if you're using it it's quite easy to use it with
|
||||
Org Cite. Out of the box, you can tell it to export your library, or parts of it,
|
||||
|
|
@ -279,52 +273,30 @@ to a =.bib= file and automatically keep it in sync. I'd recommend installing the
|
|||
[[https://retorque.re/zotero-better-bibtex/][Better BibTeX]] extension though.
|
||||
|
||||
#+caption: Zotero library right click context menu, showing the export option
|
||||
#+attr_latex: :width 0.4\linewidth
|
||||
#+attr_html: :class invertible
|
||||
[[file:figures/zotero-export-library.png]]
|
||||
|
||||
#+caption: Zotero collection export dialog
|
||||
#+attr_latex: :width 0.3\linewidth
|
||||
#+attr_html: :class invertible
|
||||
[[file:figures/zotero-export-options-prompt.png]]
|
||||
|
||||
Zotero also works well with CSL. In addition to supporting CSL-JSON exports,
|
||||
Zotero also features an easy way to install CSL styles within the preferences.
|
||||
|
||||
#+caption: Zotero CSL style management within preferences
|
||||
#+attr_latex: :width 0.6\linewidth
|
||||
#+attr_html: :class invertible
|
||||
[[file:figures/zotero-cite-styles-menu.png]]
|
||||
|
||||
Since these files are put under =~/Zotero/styles=, you can use them with Org Cite
|
||||
and Citeproc simply by setting ~org-cite-csl-styles-dir~ to the Zotero styles
|
||||
directory.
|
||||
#+begin_src emacs-lisp
|
||||
(setq org-cite-csl-styles-dir "~/Zotero/styles")
|
||||
(setq org-cite-csl-styles-dir "~/Zotero/styles")
|
||||
#+end_src
|
||||
|
||||
To then use the citation style defined by =~/Zotero/styles/apa.csl= one can then
|
||||
simply refer to =apa.csl= when using the =#+cite_export= keyword.
|
||||
#+begin_example
|
||||
,#+cite_export: csl apa.csl
|
||||
,#+cite_export: csl apa.csl
|
||||
#+end_example
|
||||
|
||||
** A bright future
|
||||
|
||||
Org Cite has only just been merged in the past month, and is yet to be included
|
||||
in an Org release, but we're seeing a tremendous degree of community interest.
|
||||
There are /already/ promising developments with third-party packages, such as
|
||||
[[https://github.com/bdarcus/bibtex-actions][bibtex-actions]] and [[https://github.com/jkitchin/org-ref-cite][org-ref-cite]]. I can't wait to see how the ecosystem continues
|
||||
to develop 😃.
|
||||
|
||||
* Footnotes
|
||||
|
||||
[fn:1] Citations were first being mentioned on the mailing list back in 2007, in
|
||||
[[https://lists.gnu.org/archive/html/emacs-orgmode/2007-05/msg00146.html][a thread about footnotes]].
|
||||
|
||||
[fn:2]There is currently an [[https://github.com/andras-simonyi/org-cite-csl-activate][ongoing effort]] to use =oc.el= and =citeproc.el= to
|
||||
produce citation overlays in the buffer.
|
||||
|
||||
[fn:3] I'm talking about a certain company [[https://moneyweek.com/505757/great-frauds-in-history-robert-maxwell][created by a British Fraudster]] that
|
||||
has a [[https://www.theguardian.com/science/2017/jun/27/profitable-business-scientific-publishing-bad-for-science][40% profit margin, engages in blackmail-like practices with universities]],
|
||||
prompted [[http://thecostofknowledge.com/][19,000 researchers]] to boycott them, [[https://www.the-scientist.com/the-nutshell/elsevier-published-6-fake-journals-44160][published six fake journals]],
|
||||
|
|
@ -332,3 +304,10 @@ vigorously [[https://web.archive.org/web/20200129202353/http://legacy.earlham.ed
|
|||
(repeatedly), made [[https://www.michaeleisen.org/blog/?p=807][financial contributions to politicians who then tried to
|
||||
prevent publicly accesible reaserch]], and whose reference manager [[https://www.zotero.org/support/kb/mendeley_import#mendeley_database_encryption][encrypted
|
||||
reaserchers' /own/ databases]] "to comply with GDPR".
|
||||
** A bright future
|
||||
|
||||
Org Cite has only just been merged in the past month, and is yet to be included
|
||||
in an Org release, but we're seeing a tremendous degree of community interest.
|
||||
There are /already/ promising developments with third-party packages, such as
|
||||
[[https://github.com/bdarcus/bibtex-actions][bibtex-actions]] and [[https://github.com/jkitchin/org-ref-cite][org-ref-cite]]. I can't wait to see how the ecosystem continues
|
||||
to develop 😃.
|
||||
|
|
@ -0,0 +1,455 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>2021-07-31-citations.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">July 2021
|
||||
</span><span style="color: #9e9e9e;">#+subtitle:</span> Introducing citations!
|
||||
<span style="color: #9e9e9e;">#+author:</span> TEC
|
||||
<span style="color: #9e9e9e;">#+date:</span> 2021-07-31
|
||||
|
||||
Last month I not-at-all-subtly hinted that a certain long-awaited feature was
|
||||
arriving imminently. At this point, I think it's a good idea to set the tone for the rest of
|
||||
this post.
|
||||
|
||||
<span style="color: #b1b1b1;">#+attr_latex: :options inkscapelatex=false</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/celebrate-citations.svg]]</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Citations</span>
|
||||
|
||||
After <span class="ef-i">/years/</span> of (on and off) discussion[fn:1], I am elated to be able to present
|
||||
Org's new native citation syntax. Org has grown a thoroughly designed, modular,
|
||||
capable citation system. At last you can refer to Org for all your attribution
|
||||
needs. Special thanks must go to Nicolas Goaziou for leading the charge, John
|
||||
Kitchin for paving the way with the <span style="color: #9e9e9e;">=org-ref=</span> package, Bruce D'Arcus for driving a
|
||||
lot of careful consideration of design decisions and starting to document some
|
||||
of the details --- and the many other denizens of the mailing list who have
|
||||
contributed to the discussion over the years.
|
||||
|
||||
András Simonyi's also deserves a special mention for his work creating the Elisp
|
||||
CSL library <span style="color: #9e9e9e;">~Citeproc.el~</span>, which while not directly included in Org is crucial to
|
||||
providing robust CSL support, and integrates with <span style="color: #9e9e9e;">=oc-csl.el=</span>.
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Outline</span>
|
||||
|
||||
Citations have been carefully designed in such a way that users and Elisp
|
||||
tinkerers will be able to easily adapt and extend it to fit their needs.
|
||||
To that end, Org Cite (or OC for short) has been split into two halves:
|
||||
+ <span style="color: #9e9e9e;">=oc.el=</span> which defines the syntax and provides some machinery to interact with
|
||||
citations
|
||||
+ Citation processors which interface with <span style="color: #9e9e9e;">=oc.el=</span> to produce nicely-formatted
|
||||
citations to be inserted in your bibliography, within the text, and even
|
||||
rendered in the buffer[fn:2]
|
||||
|
||||
There are four capabilities that Org Cite uses the processors for
|
||||
1. Inserting and editing citations
|
||||
2. Following citations to their definition
|
||||
3. Fontifying the citations in the buffer
|
||||
4. Exporting the citations
|
||||
|
||||
Each capability can have a particular citation processor assigned, independently
|
||||
of the others. Out of the box, Org uses the <span style="color: #9e9e9e;">=basic=</span> processor for all of these tasks.
|
||||
|
||||
The <span style="color: #9e9e9e;">=basic=</span> citation processor is one of four currently bundled with Org:
|
||||
+ <span style="color: #9e9e9e;">=basic=</span>, which has no dependencies and provides all four capabilities. It export
|
||||
to all formats, but only provides very simple citations.
|
||||
+ <span style="color: #9e9e9e;">=biblatex=</span> and <span style="color: #9e9e9e;">=natbib=</span>, which provide the export capability to create citations
|
||||
via <span style="color: #3b6ea8; font-weight: 700;">[[http://biblatex-biber.sourceforge.net/][Biber]]</span> and (to a lesser extent) <span style="color: #3b6ea8; font-weight: 700;">[[https://ctan.org/pkg/natbib][natbib]]</span>, but only for LaTeX.
|
||||
+ <span style="color: #9e9e9e;">=csl=</span>, which provides the export capability using the <span style="color: #3b6ea8; font-weight: 700;">[[https://citationstyles.org/][Citation Style Language]]</span>,
|
||||
and exports to HTML, LaTeX, Org, and plain text (with an <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/andras-simonyi/citeproc-el/issues/23][open issue]]</span> for ODT)
|
||||
--- but depends on <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/andras-simonyi/citeproc-el][citeproc.el]]</span>.
|
||||
|
||||
This provides a solid foundation for other packages to build off, and despite
|
||||
Org Cite being yet to be released or documented in the manual we are already
|
||||
seeing the development of packages like <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/jkitchin/org-ref-cite][org-ref-cite]]</span> (by John Kitchin).
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Basic usage</span>
|
||||
|
||||
To get started with Org Cite, we must have some form of bibliography.
|
||||
This can either be a BibTeX file or a CSL-JSON file.
|
||||
|
||||
As an example, say we have a file <span style="color: #9e9e9e;">=orgcite.bib=</span> containing the following
|
||||
<span class="ef-obb">#+begin_src bibtex :tangle orgcite.bib :comments none
|
||||
</span><span style="color: #29838d; background-color: #e0e0e0;">@article</span><span class="ef-ob">{</span><span style="color: #97365b; background-color: #e0e0e0;">OrgCitations</span><span class="ef-ob">,
|
||||
</span><span style="color: #cb9aad; background-color: #e0e0e0;">author</span><span class="ef-ob">={org, mode and Syntax, Citation and List, Mailing and Effort, Time},
|
||||
</span><span style="color: #cb9aad; background-color: #e0e0e0;">journal</span><span class="ef-ob">={Journal of Plain Text Formats},
|
||||
</span><span style="color: #cb9aad; background-color: #e0e0e0;">title</span><span class="ef-ob">={Elegant Citations with Org-Mode},
|
||||
</span><span style="color: #cb9aad; background-color: #e0e0e0;">year</span><span class="ef-ob">={2021},
|
||||
</span><span style="color: #cb9aad; background-color: #e0e0e0;">month</span><span class="ef-ob">={7},
|
||||
</span><span style="color: #cb9aad; background-color: #e0e0e0;">volume</span><span class="ef-ob">={42},
|
||||
</span><span style="color: #cb9aad; background-color: #e0e0e0;">number</span><span class="ef-ob">={1},
|
||||
</span><span style="color: #cb9aad; background-color: #e0e0e0;">pages</span><span class="ef-ob">={2-3}}
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
First we need to let Org know about this bibliography file (which must have a
|
||||
<span style="color: #9e9e9e;">=.bib=</span>, <span style="color: #9e9e9e;">=.bibtex=</span>, or <span style="color: #9e9e9e;">=.json=</span> extension), which we do either via the <span style="color: #9e9e9e;">=#+bibliography=</span>
|
||||
keyword, or the variable <span style="color: #9e9e9e;">~org-cite-global-bibliography~</span>.
|
||||
<span class="ef-obb">#+begin_example
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;">,#+bibliography: orgcite.bib
|
||||
</span><span class="ef-obe">#+end_example
|
||||
</span>
|
||||
<span style="color: #b1b1b1;">#+bibliography: orgcite.bib</span>
|
||||
|
||||
Once you have a bibliography source, you can start referencing to your heart's
|
||||
content! The basic citation syntax is as follows:
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">The new citation syntax, for simple citations</span>
|
||||
<span style="color: #b1b1b1;">#+attr_latex: :width 0.5\linewidth :options inkscapelatex=false</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/citation-structure-basic.svg]]</span>
|
||||
|
||||
Using the default style <span style="color: #9e9e9e;">=</span><span style="color: #3b6ea8; font-weight: 700;">[cite:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span><span style="color: #9e9e9e;">=</span> produces <span style="color: #3b6ea8; font-weight: 700;">[cite:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span>. For
|
||||
more information on the styles currently available, see <span style="color: #3b6ea8; font-weight: 700;">[[cite-styles]]</span>.
|
||||
|
||||
Finally, to insert a bibliography somewhere, we just need to insert the
|
||||
<span style="color: #9e9e9e;">=#+print_bibliography=</span> keyword, like so:
|
||||
|
||||
<span class="ef-obb">#+begin_example
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;">,#+print_bibliography:
|
||||
</span><span class="ef-obe">#+end_example
|
||||
</span>
|
||||
<span class="ef-obb">#+begin_info
|
||||
</span>#+print_bibliography:
|
||||
<span class="ef-obe">#+end_info
|
||||
</span>
|
||||
So, to summarise, all one needs to get started is:
|
||||
<span class="ef-obb">#+begin_example
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;">,#+bibliography: references.bib
|
||||
</span><span style="color: #3b6ea8; background-color: #e0e0e0; font-weight: 700;">[cite:</span><span style="color: #99324b; background-color: #e0e0e0; font-weight: 700;">@key</span><span style="color: #3b6ea8; background-color: #e0e0e0; font-weight: 700;">]</span><span style="color: #9e9e9e; background-color: #e0e0e0;">
|
||||
,#+print_bibliography:
|
||||
</span><span class="ef-obe">#+end_example
|
||||
</span>That's it! 🎉
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** The cite syntax</span>
|
||||
|
||||
Don't let the simplicity in the examples above fool you, the new syntax is quite
|
||||
capable of expressing more complex forms. Here's the <span class="ef-i">/full/</span> version of the new
|
||||
cite syntax:
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">The new citations syntax, in full</span>
|
||||
<span style="color: #b1b1b1;">#+attr_latex: :options inkscapelatex=false</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/citation-structure-full.svg]]</span>
|
||||
|
||||
+ The <span class="ef-b">*style*</span> and <span class="ef-b">*variant*</span> determine what form the exported citation takes
|
||||
+ The <span class="ef-b">*common prefix*</span> and <span class="ef-b">*suffix*</span> and put at the start and end of the generated
|
||||
citation, respectively
|
||||
+ The citation <span class="ef-b">*key*</span> refers to a Bib(La)TeX or CSL-JSON key
|
||||
- The citation <span class="ef-b">*prefix*</span> and <span class="ef-b">*suffix*</span> are put before and after the reference to the
|
||||
key
|
||||
- Some citation processors recognise locators, which refer to a particular
|
||||
part of the work, for example: <span style="color: #9e9e9e;">=p. 7=</span> to refer to page 7.
|
||||
|
||||
Using the default CSL citation style (Chicago author-name) <span style="color: #9e9e9e;">=</span><span style="color: #3b6ea8; font-weight: 700;">[cite/l/b:see
|
||||
</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;"> pp. 7 for fun]</span><span style="color: #9e9e9e;">=</span> becomes <span style="color: #3b6ea8; font-weight: 700;">[cite/l/b:see </span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;"> pp. 7 for fun]</span>.
|
||||
|
||||
The citation styles and variants, and recognised locators are handled by the
|
||||
citation processors. Org cite's bundled processors currently supports the
|
||||
following citation styles.
|
||||
|
||||
<span style="color: #b1b1b1;">#+name: cite-styles</span>
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">The current set of supported citation styles with variants,</span>
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">with samples generated by ~oc-csl.el~ and ~citeproc.el~.</span>
|
||||
<span style="color: #b1b1b1;">#+attr_latex: :font \small</span>
|
||||
| Style | Variant | Sample | Bib(La)TeX | NatBib |
|
||||
|-------------+--------------------+---------------------------------+-------------+-------------|
|
||||
| <span style="color: #9e9e9e;">=a=</span> author | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=cf=</span><span style="text-decoration: italic; font-weight: 700;"> caps-full </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite/a/cf:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | Citeauthor | |
|
||||
| <span style="color: #9e9e9e;">=a=</span> author | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=f=</span><span style="text-decoration: italic; font-weight: 700;"> full </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite/a/f:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | citeauthor | citeauthor* |
|
||||
| <span style="color: #9e9e9e;">=a=</span> author | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=c=</span><span style="text-decoration: italic; font-weight: 700;"> caps </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite/a/c:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | Citeauthor* | Citeauthor |
|
||||
| <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=a=</span><span style="text-decoration: italic; font-weight: 700;"> author </span>| | <span style="color: #3b6ea8; font-weight: 700;">[cite/a:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | citeauthor* | citeauthor |
|
||||
|-------------+--------------------+---------------------------------+-------------+-------------|
|
||||
| <span style="color: #9e9e9e;">=na=</span> noauthor | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=b=</span><span style="text-decoration: italic; font-weight: 700;"> bare </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite/na/b:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | | citeyear |
|
||||
| <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=na=</span><span style="text-decoration: italic; font-weight: 700;"> noauthor </span>| | <span style="color: #3b6ea8; font-weight: 700;">[cite/na:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | autocite* | citeyearpar |
|
||||
|-------------+--------------------+---------------------------------+-------------+-------------|
|
||||
| <span style="color: #9e9e9e;">=l=</span> locators | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=bc=</span><span style="text-decoration: italic; font-weight: 700;"> bare-caps </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite/l/bc:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;"> p. 2]</span> | Notecite | |
|
||||
| <span style="color: #9e9e9e;">=l=</span> locators | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=b=</span><span style="text-decoration: italic; font-weight: 700;"> bare </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite/l/b:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;"> p. 2]</span> | notecite | |
|
||||
| <span style="color: #9e9e9e;">=l=</span> locators | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=bc=</span><span style="text-decoration: italic; font-weight: 700;"> caps </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite/l/bc:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">, p. 2]</span> | Pnotecite | |
|
||||
| <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=l=</span><span style="text-decoration: italic; font-weight: 700;"> locators </span>| | <span style="color: #3b6ea8; font-weight: 700;">[cite/l:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">, p. 2]</span> | pnotecite | |
|
||||
|-------------+--------------------+---------------------------------+-------------+-------------|
|
||||
| <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=n=</span><span style="text-decoration: italic; font-weight: 700;"> nocite </span>| | <span style="color: #3b6ea8; font-weight: 700;">[cite/n:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | nocite | nocite |
|
||||
|-------------+--------------------+---------------------------------+-------------+-------------|
|
||||
| <span style="color: #9e9e9e;">=t=</span> text | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=b=</span><span style="text-decoration: italic; font-weight: 700;"> bare </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite/t/b:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | | citealp |
|
||||
| <span style="color: #9e9e9e;">=t=</span> text | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=c=</span><span style="text-decoration: italic; font-weight: 700;"> caps </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite/t/c:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | Textcite | Citep |
|
||||
| <span style="color: #9e9e9e;">=t=</span> text | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=f=</span><span style="text-decoration: italic; font-weight: 700;"> full </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite/t/f:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | | citep* |
|
||||
| <span style="color: #9e9e9e;">=t=</span> text | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=bc=</span><span style="text-decoration: italic; font-weight: 700;"> bare-caps </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite/t/bc:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | | Citealp |
|
||||
| <span style="color: #9e9e9e;">=t=</span> text | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=bf=</span><span style="text-decoration: italic; font-weight: 700;"> bare-full </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite/t/bf:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | | citealp* |
|
||||
| <span style="color: #9e9e9e;">=t=</span> text | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=cf=</span><span style="text-decoration: italic; font-weight: 700;"> caps-full </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite/t/cf:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | | Citep* |
|
||||
| <span style="color: #9e9e9e;">=t=</span> text | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=bcf=</span><span style="text-decoration: italic; font-weight: 700;"> bare-caps-full </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite/t/bcf:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | | Citealp* |
|
||||
| <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=t=</span><span style="text-decoration: italic; font-weight: 700;"> text </span>| | <span style="color: #3b6ea8; font-weight: 700;">[cite/t:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | textcite | |
|
||||
|-------------+--------------------+---------------------------------+-------------+-------------|
|
||||
| (default) | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=b=</span><span style="text-decoration: italic; font-weight: 700;"> bare </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite//b:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | cite | citealp |
|
||||
| (default) | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=bc=</span><span style="text-decoration: italic; font-weight: 700;"> bare-caps </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite//bc:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | Cite | Citealp |
|
||||
| (default) | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=f=</span><span style="text-decoration: italic; font-weight: 700;"> full </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite//f:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | | citep* |
|
||||
| (default) | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=bf=</span><span style="text-decoration: italic; font-weight: 700;"> bare-full </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite//bf:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | | citealp |
|
||||
| (default) | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=cf=</span><span style="text-decoration: italic; font-weight: 700;"> caps-full </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite//cf:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | | Citep* |
|
||||
| (default) | <span style="color: #9e9e9e; text-decoration: italic; font-weight: 700;">=bcf=</span><span style="text-decoration: italic; font-weight: 700;"> bare-caps-full </span>| <span style="color: #3b6ea8; font-weight: 700;">[cite//bcf:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | | Citealp* |
|
||||
| (default) | | <span style="color: #3b6ea8; font-weight: 700;">[cite:</span><span style="color: #3b6ea8; font-weight: 700;">@OrgCitations</span><span style="color: #3b6ea8; font-weight: 700;">]</span> | autocite | citep |
|
||||
|
||||
The CSL processor supports the following locators:
|
||||
+ <span class="ef-b">*=book=*</span>, <span style="color: #9e9e9e;">=bk.=</span>, <span style="color: #9e9e9e;">=bks.=</span>
|
||||
+ <span class="ef-b">*=chapter=*</span>, <span style="color: #9e9e9e;">=chap.=</span>, <span style="color: #9e9e9e;">=chaps.=</span>
|
||||
+ <span class="ef-b">*=column=*</span>, <span style="color: #9e9e9e;">=col.=</span>, <span style="color: #9e9e9e;">=cols.=</span>
|
||||
+ <span class="ef-b">*=figure=*</span>, <span style="color: #9e9e9e;">=fig.=</span>, <span style="color: #9e9e9e;">=figs.=</span>
|
||||
+ <span class="ef-b">*=folio=*</span>, <span style="color: #9e9e9e;">=fol.=</span>, <span style="color: #9e9e9e;">=fols.=</span>
|
||||
+ <span class="ef-b">*=number=*</span>, <span style="color: #9e9e9e;">=no.=</span>, <span style="color: #9e9e9e;">=Os.=</span>
|
||||
+ <span class="ef-b">*=line=*</span>, <span style="color: #9e9e9e;">=l.=</span>, <span style="color: #9e9e9e;">=ll.=</span>
|
||||
+ <span class="ef-b">*=note=*</span>, <span style="color: #9e9e9e;">=n.=</span>, <span style="color: #9e9e9e;">=nn.=</span>
|
||||
+ <span class="ef-b">*=opus=*</span>, <span style="color: #9e9e9e;">=op.=</span>, <span style="color: #9e9e9e;">=opp.=</span>
|
||||
+ <span class="ef-b">*=page=*</span>, <span style="color: #9e9e9e;">=p=</span>, <span style="color: #9e9e9e;">=p.=</span>, <span style="color: #9e9e9e;">=pp.=</span>
|
||||
+ <span class="ef-b">*=paragraph=*</span>, <span style="color: #9e9e9e;">=para.=</span>, <span style="color: #9e9e9e;">=paras.=</span>, <span style="color: #9e9e9e;">=¶=</span>, <span style="color: #9e9e9e;">=¶¶=</span>, <span style="color: #9e9e9e;">=§=</span>, <span style="color: #9e9e9e;">=§§=</span>
|
||||
+ <span class="ef-b">*=part=*</span>, <span style="color: #9e9e9e;">=pt.=</span>, <span style="color: #9e9e9e;">=pts.=</span>
|
||||
+ <span class="ef-b">*=section=*</span>, <span style="color: #9e9e9e;">=sec.=</span>, <span style="color: #9e9e9e;">=secs.=</span>
|
||||
+ <span class="ef-b">*=sub verbo=*</span>, <span style="color: #9e9e9e;">=s.v.=</span>, <span style="color: #9e9e9e;">=s.vv.=</span>
|
||||
+ <span class="ef-b">*=verse=*</span>, <span style="color: #9e9e9e;">=v.=</span>, <span style="color: #9e9e9e;">=vv.=</span>
|
||||
+ <span class="ef-b">*=volume=*</span>, <span style="color: #9e9e9e;">=vol.=</span>, <span style="color: #9e9e9e;">=vols.=</span>
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** More on exporting</span>
|
||||
|
||||
The style of the citations and the bibliography depend on three things:
|
||||
1. The citation processor used
|
||||
2. The citation style
|
||||
3. The bibliography style
|
||||
|
||||
The citation processor is automatically selected based on
|
||||
<span style="color: #9e9e9e;">~org-cite-export-processors~</span> based on the export format being used, but can be set
|
||||
on a per-document basis via the <span style="color: #9e9e9e;">=#+cite_export=</span> keyword. Here, I shall use the <span style="color: #9e9e9e;">=csl=</span>
|
||||
processor,
|
||||
<span class="ef-obb">#+begin_example
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;">,#+cite_export: csl
|
||||
</span><span class="ef-obe">#+end_example
|
||||
</span>
|
||||
<span style="color: #b1b1b1;">#+cite_export: csl</span>
|
||||
|
||||
With <span style="color: #9e9e9e;">~org-cite-export-processors~</span>, you can also set the bibliography and citation
|
||||
style by giving a triplet of parameters <span style="color: #9e9e9e; background-color: #e0e0e0;">src_</span><span style="color: #b1b1b1; background-color: #e0e0e0;">elisp</span><span style="color: #9e9e9e; background-color: #e0e0e0;">{</span><span class="ef-ob">(PROCESSOR BIBLIOGRAPHY-STYLE
|
||||
CITATION-STYLE)</span><span style="color: #9e9e9e; background-color: #e0e0e0;">}</span> instead of just the processor. You can also use this triplet of
|
||||
values with the <span style="color: #9e9e9e;">=#+cite_export=</span> keyword
|
||||
<span class="ef-obb">#+begin_example
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;">,#+cite_export: processor bibliography-style citation-style
|
||||
</span><span class="ef-obe">#+end_example
|
||||
</span>
|
||||
There are also some more options about how the bibliography is produced. These
|
||||
options are handled by the active citation processor. For example, while the CSL
|
||||
processor does not currently support any options, the BibLaTeX processor passes
|
||||
options to a <span style="color: #9e9e9e; background-color: #e0e0e0;">src_</span><span style="color: #b1b1b1; background-color: #e0e0e0;">LaTeX</span><span style="color: #9e9e9e; background-color: #e0e0e0;">{</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\printbibliography</span><span style="color: #9e9e9e; background-color: #e0e0e0;">}</span> command, allowing for the
|
||||
following:
|
||||
<span class="ef-obb">#+begin_example
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;">,#+print_bibliography: :section 2 :heading subbibliography
|
||||
,#+print_bibliography: :keyword abc,xyz :title "Primary Sources"
|
||||
</span><span class="ef-obe">#+end_example
|
||||
</span>
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Using CSL</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/andras-simonyi/citeproc-el][Citeproc]]</span> is currently available on <span style="color: #3b6ea8; font-weight: 700;">[[https://melpa.org/#/citeproc][MELPA]]</span>, and so can be installed via your
|
||||
package manager of choice so long as MELPA is included in your
|
||||
<span style="color: #9e9e9e;">~package-archives~</span>. When available, it will be automatically loaded by
|
||||
<span style="color: #9e9e9e;">=oc-csl.el=</span>.
|
||||
|
||||
It currently supports exporting to:
|
||||
+ HTML
|
||||
+ LaTeX
|
||||
+ Org
|
||||
+ Plain text
|
||||
|
||||
Should you be interested in other formats, know that Citeproc is designed to
|
||||
easily support adding new formats (see <span style="color: #9e9e9e;">=citeproc-formatters.el=</span> for examples).
|
||||
|
||||
Citeproc can currently retrieve bibliographic information from the following
|
||||
formats:
|
||||
+ CSL-JSON
|
||||
+ Bib(La)TeX
|
||||
+ org-bibtex
|
||||
|
||||
Though support for Bib(La)TeX and <span style="color: #3b6ea8; font-weight: 700;">[[https://gewhere.github.io/org-bibtex][org-bibtex]]</span> is rudimentary compared to CSL-JSON.
|
||||
|
||||
When exporting, you can set the style by providing a path to CSL style files,
|
||||
either absolute or relative to <span style="color: #9e9e9e;">~org-cite-csl-styles-dir~</span>. For example, if I
|
||||
download <span style="color: #9e9e9e;">=apa.csl=</span> I can use it like so:
|
||||
<span class="ef-obb">#+begin_example
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;">,#+cite_export: csl ~/Downloads/apa.csl
|
||||
</span><span class="ef-obe">#+end_example
|
||||
</span>
|
||||
When no style is given <span style="color: #9e9e9e;">~org-cite-csl--fallback-style-file~</span> will be used, which
|
||||
defaults to a bundled Chicago author-date style.
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Working with Zotero</span>
|
||||
|
||||
There are quite a few reference managers available, however, the list rapidly
|
||||
shrinks if you restrict yourself to applications which are:
|
||||
+ somewhat feature-rich
|
||||
+ open source software
|
||||
+ not owned by a parasitic company[fn:3]
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[https://www.zotero.org/][Zotero]]</span> is a good option, and if you're using it it's quite easy to use it with
|
||||
Org Cite. Out of the box, you can tell it to export your library, or parts of it,
|
||||
to a <span style="color: #9e9e9e;">=.bib=</span> file and automatically keep it in sync. I'd recommend installing the
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[https://retorque.re/zotero-better-bibtex/][Better BibTeX]]</span> extension though.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Zotero library right click context menu, showing the export option</span>
|
||||
<span style="color: #b1b1b1;">#+attr_latex: :width 0.4\linewidth</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/zotero-export-library.png]]</span>
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Zotero collection export dialog</span>
|
||||
<span style="color: #b1b1b1;">#+attr_latex: :width 0.3\linewidth</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/zotero-export-options-prompt.png]]</span>
|
||||
|
||||
Zotero also works well with CSL. In addition to supporting CSL-JSON exports,
|
||||
Zotero also features an easy way to install CSL styles within the preferences.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Zotero CSL style management within preferences</span>
|
||||
<span style="color: #b1b1b1;">#+attr_latex: :width 0.6\linewidth</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/zotero-cite-styles-menu.png]]</span>
|
||||
|
||||
Since these files are put under <span style="color: #9e9e9e;">=~/Zotero/styles=</span>, you can use them with Org Cite
|
||||
and Citeproc simply by setting <span style="color: #9e9e9e;">~org-cite-csl-styles-dir~</span> to the Zotero styles
|
||||
directory.
|
||||
<span class="ef-obb">#+begin_src emacs-lisp
|
||||
</span><span class="ef-ob">(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">setq</span><span class="ef-ob"> org-cite-csl-styles-dir </span><span style="color: #4f894c; background-color: #e0e0e0;">"~/Zotero/styles"</span><span class="ef-ob">)
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
To then use the citation style defined by <span style="color: #9e9e9e;">=~/Zotero/styles/apa.csl=</span> one can then
|
||||
simply refer to <span style="color: #9e9e9e;">=apa.csl=</span> when using the <span style="color: #9e9e9e;">=#+cite_export=</span> keyword.
|
||||
<span class="ef-obb">#+begin_example
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;">,#+cite_export: csl apa.csl
|
||||
</span><span class="ef-obe">#+end_example
|
||||
</span>
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** A bright future</span>
|
||||
|
||||
Org Cite has only just been merged in the past month, and is yet to be included
|
||||
in an Org release, but we're seeing a tremendous degree of community interest.
|
||||
There are <span class="ef-i">/already/</span> promising developments with third-party packages, such as
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/bdarcus/bibtex-actions][bibtex-actions]]</span> and <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/jkitchin/org-ref-cite][org-ref-cite]]</span>. I can't wait to see how the ecosystem continues
|
||||
to develop 😃.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Footnotes</span>
|
||||
|
||||
[fn:1] Citations were first being mentioned on the mailing list back in 2007, in
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[https://lists.gnu.org/archive/html/emacs-orgmode/2007-05/msg00146.html][a thread about footnotes]]</span>.
|
||||
|
||||
[fn:2]There is currently an <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/andras-simonyi/org-cite-csl-activate][ongoing effort]]</span> to use <span style="color: #9e9e9e;">=oc.el=</span> and <span style="color: #9e9e9e;">=citeproc.el=</span> to
|
||||
produce citation overlays in the buffer.
|
||||
|
||||
[fn:3] I'm talking about a certain company <span style="color: #3b6ea8; font-weight: 700;">[[https://moneyweek.com/505757/great-frauds-in-history-robert-maxwell][created by a British Fraudster]]</span> that
|
||||
has a <span style="color: #3b6ea8; font-weight: 700;">[[https://www.theguardian.com/science/2017/jun/27/profitable-business-scientific-publishing-bad-for-science][40% profit margin, engages in blackmail-like practices with universities]]</span>,
|
||||
prompted <span style="color: #3b6ea8; font-weight: 700;">[[http://thecostofknowledge.com/][19,000 researchers]]</span> to boycott them, <span style="color: #3b6ea8; font-weight: 700;">[[https://www.the-scientist.com/the-nutshell/elsevier-published-6-fake-journals-44160][published six fake journals]]</span>,
|
||||
vigorously <span style="color: #3b6ea8; font-weight: 700;">[[https://web.archive.org/web/20200129202353/http://legacy.earlham.edu/~peters/fos/2007/08/publishers-launch-anti-oa-lobbying.html][lobbys against Open Access]]</span>, <span style="color: #3b6ea8; font-weight: 700;">[[https://rossmounce.co.uk/2017/02/14/elsevier-selling-access-to-open-access-again/][charged for Open Acess articles]]</span>
|
||||
(repeatedly), made <span style="color: #3b6ea8; font-weight: 700;">[[https://www.michaeleisen.org/blog/?p=807][financial contributions to politicians who then tried to
|
||||
prevent publicly accesible reaserch]]</span>, and whose reference manager <span style="color: #3b6ea8; font-weight: 700;">[[https://www.zotero.org/support/kb/mendeley_import#mendeley_database_encryption][encrypted
|
||||
reaserchers' </span><span style="color: #3b6ea8; text-decoration: italic; font-weight: 700;">/own/</span><span style="color: #3b6ea8; font-weight: 700;"> databases]]</span> "to comply with GDPR".
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,403 @@
|
|||
━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
JULY 2021
|
||||
Introducing citations!
|
||||
|
||||
TEC
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
|
||||
2021-07-31
|
||||
|
||||
|
||||
Last month I not-at-all-subtly hinted that a certain long-awaited
|
||||
feature was arriving imminently. At this point, I think it’s a good idea
|
||||
to set the tone for the rest of this post.
|
||||
|
||||
<file:figures/celebrate-citations.svg>
|
||||
|
||||
|
||||
Citations
|
||||
═════════
|
||||
|
||||
After /years/ of (on and off) discussion[1], I am elated to be able to
|
||||
present Org’s new native citation syntax. Org has grown a thoroughly
|
||||
designed, modular, capable citation system. At last you can refer to
|
||||
Org for all your attribution needs. Special thanks must go to Nicolas
|
||||
Goaziou for leading the charge, John Kitchin for paving the way with
|
||||
the `org-ref' package, Bruce D’Arcus for driving a lot of careful
|
||||
consideration of design decisions and starting to document some of the
|
||||
details — and the many other denizens of the mailing list who have
|
||||
contributed to the discussion over the years.
|
||||
|
||||
András Simonyi’s also deserves a special mention for his work creating
|
||||
the Elisp CSL library `Citeproc.el', which while not directly included
|
||||
in Org is crucial to providing robust CSL support, and integrates with
|
||||
`oc-csl.el'.
|
||||
|
||||
|
||||
Outline
|
||||
───────
|
||||
|
||||
Citations have been carefully designed in such a way that users and
|
||||
Elisp tinkerers will be able to easily adapt and extend it to fit
|
||||
their needs. To that end, Org Cite (or OC for short) has been split
|
||||
into two halves:
|
||||
⁃ `oc.el' which defines the syntax and provides some machinery to
|
||||
interact with citations
|
||||
⁃ Citation processors which interface with `oc.el' to produce
|
||||
nicely-formatted citations to be inserted in your bibliography,
|
||||
within the text, and even rendered in the buffer[2]
|
||||
|
||||
There are four capabilities that Org Cite uses the processors for
|
||||
1. Inserting and editing citations
|
||||
2. Following citations to their definition
|
||||
3. Fontifying the citations in the buffer
|
||||
4. Exporting the citations
|
||||
|
||||
Each capability can have a particular citation processor assigned,
|
||||
independently of the others. Out of the box, Org uses the `basic'
|
||||
processor for all of these tasks.
|
||||
|
||||
The `basic' citation processor is one of four currently bundled with
|
||||
Org:
|
||||
⁃ `basic', which has no dependencies and provides all four
|
||||
capabilities. It export to all formats, but only provides very
|
||||
simple citations.
|
||||
⁃ `biblatex' and `natbib', which provide the export capability to
|
||||
create citations via [Biber] and (to a lesser extent) [natbib], but
|
||||
only for LaTeX.
|
||||
⁃ `csl', which provides the export capability using the [Citation
|
||||
Style Language], and exports to HTML, LaTeX, Org, and plain text
|
||||
(with an [open issue] for ODT) — but depends on [citeproc.el].
|
||||
|
||||
This provides a solid foundation for other packages to build off, and
|
||||
despite Org Cite being yet to be released or documented in the manual
|
||||
we are already seeing the development of packages like [org-ref-cite]
|
||||
(by John Kitchin).
|
||||
|
||||
|
||||
[Biber] <http://biblatex-biber.sourceforge.net/>
|
||||
|
||||
[natbib] <https://ctan.org/pkg/natbib>
|
||||
|
||||
[Citation Style Language] <https://citationstyles.org/>
|
||||
|
||||
[open issue] <https://github.com/andras-simonyi/citeproc-el/issues/23>
|
||||
|
||||
[citeproc.el] <https://github.com/andras-simonyi/citeproc-el>
|
||||
|
||||
[org-ref-cite] <https://github.com/jkitchin/org-ref-cite>
|
||||
|
||||
|
||||
Basic usage
|
||||
───────────
|
||||
|
||||
To get started with Org Cite, we must have some form of bibliography.
|
||||
This can either be a BibTeX file or a CSL-JSON file.
|
||||
|
||||
As an example, say we have a file `orgcite.bib' containing the
|
||||
following
|
||||
┌────
|
||||
│ @article{OrgCitations,
|
||||
│ author={org, mode and Syntax, Citation and List, Mailing and Effort, Time},
|
||||
│ journal={Journal of Plain Text Formats},
|
||||
│ title={Elegant Citations with Org-Mode},
|
||||
│ year={2021},
|
||||
│ month={7},
|
||||
│ volume={42},
|
||||
│ number={1},
|
||||
│ pages={2-3}}
|
||||
└────
|
||||
|
||||
First we need to let Org know about this bibliography file (which must
|
||||
have a `.bib', `.bibtex', or `.json' extension), which we do either
|
||||
via the `#+bibliography' keyword, or the variable
|
||||
`org-cite-global-bibliography'.
|
||||
┌────
|
||||
│ #+bibliography: orgcite.bib
|
||||
└────
|
||||
|
||||
Once you have a bibliography source, you can start referencing to your
|
||||
heart’s content! The basic citation syntax is as follows:
|
||||
|
||||
<file:figures/citation-structure-basic.svg>
|
||||
|
||||
Using the default style `[cite:@OrgCitations]' produces (org et
|
||||
al. 2021). For more information on the styles currently available, see
|
||||
1.
|
||||
|
||||
Finally, to insert a bibliography somewhere, we just need to insert
|
||||
the `#+print_bibliography' keyword, like so:
|
||||
|
||||
┌────
|
||||
│ #+print_bibliography:
|
||||
└────
|
||||
|
||||
org, mode, Citation Syntax, Mailing List, and Time
|
||||
Effort. 2021. “Elegant Citations with Org-Mode.” /Journal of Plain
|
||||
Text Formats/ 42 (1): 2–3.
|
||||
|
||||
So, to summarise, all one needs to get started is:
|
||||
┌────
|
||||
│ #+bibliography: references.bib
|
||||
│ [cite:@key]
|
||||
│ #+print_bibliography:
|
||||
└────
|
||||
That’s it! 🎉
|
||||
|
||||
|
||||
The cite syntax
|
||||
───────────────
|
||||
|
||||
Don’t let the simplicity in the examples above fool you, the new
|
||||
syntax is quite capable of expressing more complex forms. Here’s the
|
||||
/full/ version of the new cite syntax:
|
||||
|
||||
<file:figures/citation-structure-full.svg>
|
||||
|
||||
⁃ The *style* and *variant* determine what form the exported citation
|
||||
takes
|
||||
⁃ The *common prefix* and *suffix* and put at the start and end of the
|
||||
generated citation, respectively
|
||||
⁃ The citation *key* refers to a Bib(La)TeX or CSL-JSON key
|
||||
• The citation *prefix* and *suffix* are put before and after the
|
||||
reference to the key
|
||||
• Some citation processors recognise locators, which refer to a
|
||||
particular part of the work, for example: `p. 7' to refer to page
|
||||
7.
|
||||
|
||||
Using the default CSL citation style (Chicago author-name)
|
||||
`[cite/l/b:see @OrgCitations pp. 7 for fun]' becomes see 7 for fun.
|
||||
|
||||
The citation styles and variants, and recognised locators are handled
|
||||
by the citation processors. Org cite’s bundled processors currently
|
||||
supports the following citation styles.
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Style Variant Sample Bib(La)TeX NatBib
|
||||
─────────────────────────────────────────────────────────────────────────────────────────────────────
|
||||
`a' author `cf' caps-full (Org, Syntax, List, and Effort) Citeauthor
|
||||
`a' author `f' full (org, Syntax, List, and Effort) citeauthor citeauthor*
|
||||
`a' author `c' caps (Org et al.) Citeauthor* Citeauthor
|
||||
`a' author (org et al.) citeauthor* citeauthor
|
||||
─────────────────────────────────────────────────────────────────────────────────────────────────────
|
||||
`na' noauthor `b' bare 2021 citeyear
|
||||
`na' noauthor (2021) autocite* citeyearpar
|
||||
─────────────────────────────────────────────────────────────────────────────────────────────────────
|
||||
`l' locators `bc' bare-caps (2) Notecite
|
||||
`l' locators `b' bare 2 notecite
|
||||
`l' locators `bc' caps (, 2) Pnotecite
|
||||
`l' locators (, 2) pnotecite
|
||||
─────────────────────────────────────────────────────────────────────────────────────────────────────
|
||||
`n' nocite nocite nocite
|
||||
─────────────────────────────────────────────────────────────────────────────────────────────────────
|
||||
`t' text `b' bare org et al. (2021) citealp
|
||||
`t' text `c' caps Org et al. (2021) Textcite Citep
|
||||
`t' text `f' full org, Syntax, List, and Effort (2021) citep*
|
||||
`t' text `bc' bare-caps org et al. (2021) Citealp
|
||||
`t' text `bf' bare-full org et al. (2021) citealp*
|
||||
`t' text `cf' caps-full Org, Syntax, List, and Effort (2021) Citep*
|
||||
`t' text `bcf' bare-caps-full org et al. (2021) Citealp*
|
||||
`t' text org et al. (2021) textcite
|
||||
─────────────────────────────────────────────────────────────────────────────────────────────────────
|
||||
(default) `b' bare org et al. 2021 cite citealp
|
||||
(default) `bc' bare-caps Org et al. 2021 Cite Citealp
|
||||
(default) `f' full (org et al. 2021) citep*
|
||||
(default) `bf' bare-full (org et al. 2021) citealp
|
||||
(default) `cf' caps-full (org et al. 2021) Citep*
|
||||
(default) `bcf' bare-caps-full (org et al. 2021) Citealp*
|
||||
(default) (org et al. 2021) autocite citep
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Table 1: The current set of supported citation styles with variants,
|
||||
with samples generated by `oc-csl.el' and `citeproc.el'.
|
||||
|
||||
The CSL processor supports the following locators:
|
||||
⁃ *`book'*, `bk.', `bks.'
|
||||
⁃ *`chapter'*, `chap.', `chaps.'
|
||||
⁃ *`column'*, `col.', `cols.'
|
||||
⁃ *`figure'*, `fig.', `figs.'
|
||||
⁃ *`folio'*, `fol.', `fols.'
|
||||
⁃ *`number'*, `no.', `Os.'
|
||||
⁃ *`line'*, `l.', `ll.'
|
||||
⁃ *`note'*, `n.', `nn.'
|
||||
⁃ *`opus'*, `op.', `opp.'
|
||||
⁃ *`page'*, `p', `p.', `pp.'
|
||||
⁃ *`paragraph'*, `para.', `paras.', `¶', `¶¶', `§', `§§'
|
||||
⁃ *`part'*, `pt.', `pts.'
|
||||
⁃ *`section'*, `sec.', `secs.'
|
||||
⁃ *`sub verbo'*, `s.v.', `s.vv.'
|
||||
⁃ *`verse'*, `v.', `vv.'
|
||||
⁃ *`volume'*, `vol.', `vols.'
|
||||
|
||||
|
||||
More on exporting
|
||||
─────────────────
|
||||
|
||||
The style of the citations and the bibliography depend on three
|
||||
things:
|
||||
1. The citation processor used
|
||||
2. The citation style
|
||||
3. The bibliography style
|
||||
|
||||
The citation processor is automatically selected based on
|
||||
`org-cite-export-processors' based on the export format being used,
|
||||
but can be set on a per-document basis via the `#+cite_export'
|
||||
keyword. Here, I shall use the `csl' processor,
|
||||
┌────
|
||||
│ #+cite_export: csl
|
||||
└────
|
||||
|
||||
With `org-cite-export-processors', you can also set the bibliography
|
||||
and citation style by giving a triplet of parameters `(PROCESSOR
|
||||
BIBLIOGRAPHY-STYLE CITATION-STYLE)' instead of just the processor. You
|
||||
can also use this triplet of values with the `#+cite_export' keyword
|
||||
┌────
|
||||
│ #+cite_export: processor bibliography-style citation-style
|
||||
└────
|
||||
|
||||
There are also some more options about how the bibliography is
|
||||
produced. These options are handled by the active citation
|
||||
processor. For example, while the CSL processor does not currently
|
||||
support any options, the BibLaTeX processor passes options to a
|
||||
`\printbibliography' command, allowing for the following:
|
||||
┌────
|
||||
│ #+print_bibliography: :section 2 :heading subbibliography
|
||||
│ #+print_bibliography: :keyword abc,xyz :title "Primary Sources"
|
||||
└────
|
||||
|
||||
|
||||
Using CSL
|
||||
─────────
|
||||
|
||||
[Citeproc] is currently available on [MELPA], and so can be installed
|
||||
via your package manager of choice so long as MELPA is included in
|
||||
your `package-archives'. When available, it will be automatically
|
||||
loaded by `oc-csl.el'.
|
||||
|
||||
It currently supports exporting to:
|
||||
⁃ HTML
|
||||
⁃ LaTeX
|
||||
⁃ Org
|
||||
⁃ Plain text
|
||||
|
||||
Should you be interested in other formats, know that Citeproc is
|
||||
designed to easily support adding new formats (see
|
||||
`citeproc-formatters.el' for examples).
|
||||
|
||||
Citeproc can currently retrieve bibliographic information from the
|
||||
following formats:
|
||||
⁃ CSL-JSON
|
||||
⁃ Bib(La)TeX
|
||||
⁃ org-bibtex
|
||||
|
||||
Though support for Bib(La)TeX and [org-bibtex] is rudimentary compared
|
||||
to CSL-JSON.
|
||||
|
||||
When exporting, you can set the style by providing a path to CSL style
|
||||
files, either absolute or relative to `org-cite-csl-styles-dir'. For
|
||||
example, if I download `apa.csl' I can use it like so:
|
||||
┌────
|
||||
│ #+cite_export: csl ~/Downloads/apa.csl
|
||||
└────
|
||||
|
||||
When no style is given `org-cite-csl--fallback-style-file' will be
|
||||
used, which defaults to a bundled Chicago author-date style.
|
||||
|
||||
|
||||
[Citeproc] <https://github.com/andras-simonyi/citeproc-el>
|
||||
|
||||
[MELPA] <https://melpa.org/#/citeproc>
|
||||
|
||||
[org-bibtex] <https://gewhere.github.io/org-bibtex>
|
||||
|
||||
|
||||
Working with Zotero
|
||||
───────────────────
|
||||
|
||||
There are quite a few reference managers available, however, the list
|
||||
rapidly shrinks if you restrict yourself to applications which are:
|
||||
⁃ somewhat feature-rich
|
||||
⁃ open source software
|
||||
⁃ not owned by a parasitic company[3]
|
||||
|
||||
[Zotero] is a good option, and if you’re using it it’s quite easy to
|
||||
use it with Org Cite. Out of the box, you can tell it to export your
|
||||
library, or parts of it, to a `.bib' file and automatically keep it in
|
||||
sync. I’d recommend installing the [Better BibTeX] extension though.
|
||||
|
||||
<file:figures/zotero-export-library.png>
|
||||
|
||||
<file:figures/zotero-export-options-prompt.png>
|
||||
|
||||
Zotero also works well with CSL. In addition to supporting CSL-JSON
|
||||
exports, Zotero also features an easy way to install CSL styles within
|
||||
the preferences.
|
||||
|
||||
<file:figures/zotero-cite-styles-menu.png>
|
||||
|
||||
Since these files are put under `~/Zotero/styles', you can use them
|
||||
with Org Cite and Citeproc simply by setting `org-cite-csl-styles-dir'
|
||||
to the Zotero styles directory.
|
||||
┌────
|
||||
│ (setq org-cite-csl-styles-dir "~/Zotero/styles")
|
||||
└────
|
||||
|
||||
To then use the citation style defined by `~/Zotero/styles/apa.csl'
|
||||
one can then simply refer to `apa.csl' when using the `#+cite_export'
|
||||
keyword.
|
||||
┌────
|
||||
│ #+cite_export: csl apa.csl
|
||||
└────
|
||||
|
||||
|
||||
[Zotero] <https://www.zotero.org/>
|
||||
|
||||
[Better BibTeX] <https://retorque.re/zotero-better-bibtex/>
|
||||
|
||||
|
||||
A bright future
|
||||
───────────────
|
||||
|
||||
Org Cite has only just been merged in the past month, and is yet to be
|
||||
included in an Org release, but we’re seeing a tremendous degree of
|
||||
community interest. There are /already/ promising developments with
|
||||
third-party packages, such as [bibtex-actions] and [org-ref-cite]. I
|
||||
can’t wait to see how the ecosystem continues to develop 😃.
|
||||
|
||||
|
||||
[bibtex-actions] <https://github.com/bdarcus/bibtex-actions>
|
||||
|
||||
[org-ref-cite] <https://github.com/jkitchin/org-ref-cite>
|
||||
|
||||
|
||||
|
||||
Footnotes
|
||||
─────────
|
||||
|
||||
[1] Citations were first being mentioned on the mailing list back in
|
||||
2007, in [a thread about footnotes]
|
||||
(<https://lists.gnu.org/archive/html/emacs-orgmode/2007-05/msg00146.html>).
|
||||
|
||||
[2] There is currently an [ongoing effort]
|
||||
(<https://github.com/andras-simonyi/org-cite-csl-activate>) to use
|
||||
`oc.el' and `citeproc.el' to produce citation overlays in the buffer.
|
||||
|
||||
[3] I’m talking about a certain company [created by a British
|
||||
Fraudster]
|
||||
(<https://moneyweek.com/505757/great-frauds-in-history-robert-maxwell>)
|
||||
that has a [40% profit margin, engages in blackmail-like practices
|
||||
with universities]
|
||||
(<https://www.theguardian.com/science/2017/jun/27/profitable-business-scientific-publishing-bad-for-science>),
|
||||
prompted [19,000 researchers] (<http://thecostofknowledge.com/>) to
|
||||
boycott them, [published six fake journals]
|
||||
(<https://www.the-scientist.com/the-nutshell/elsevier-published-6-fake-journals-44160>),
|
||||
vigorously [lobbys against Open Access]
|
||||
(<https://web.archive.org/web/20200129202353/http://legacy.earlham.edu/~peters/fos/2007/08/publishers-launch-anti-oa-lobbying.html>),
|
||||
[charged for Open Acess articles]
|
||||
(<https://rossmounce.co.uk/2017/02/14/elsevier-selling-access-to-open-access-again/>)
|
||||
(repeatedly), made [financial contributions to politicians who then
|
||||
tried to prevent publicly accesible reaserch]
|
||||
(<https://www.michaeleisen.org/blog/?p=807>), and whose reference
|
||||
manager [encrypted reaserchers’ /own/ databases]
|
||||
(<https://www.zotero.org/support/kb/mendeley_import#mendeley_database_encryption>)
|
||||
“to comply with GDPR”.
|
||||
|
|
@ -0,0 +1,233 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-12 Fri 13:39 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>August 2021</title>
|
||||
<meta name="author" content="TEC" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="August 2021" />
|
||||
<meta property="og:description" content="Roaming around" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="TEC" />
|
||||
<meta property="og:article:published_time" content="2021-09-07T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2021-09-08T15:31:20+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
<script>
|
||||
MathJax = {
|
||||
chtml: {
|
||||
scale: 1
|
||||
},
|
||||
svg: {
|
||||
scale: 1,
|
||||
fontCache: "global"
|
||||
},
|
||||
tex: {
|
||||
tags: "%AUTONUMBER",
|
||||
multlineWidth: "85%",
|
||||
tagSide: "right",
|
||||
tagIndent: ".8em"
|
||||
}
|
||||
};
|
||||
</script>
|
||||
<script id="MathJax-script" async
|
||||
src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2021-08-38, <span class='acr'>TEC</span></div>
|
||||
|
||||
<h1 class="title">August 2021</h1>
|
||||
<p class="subtitle" role="doc-subtitle">Roaming around</p>
|
||||
</header><blockquote>
|
||||
<p>
|
||||
Dear readers, unfortunately I’ve been unusually busy as of late, and will
|
||||
continue to be for a bit over a month. As such, it’s entirely likely that the
|
||||
next post or two may <del>be late</del> make use of creative dates too.
|
||||
</p>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
In terms of Org development, we’ve had a fairly slow month — mostly tweaks and
|
||||
fixes, concentrated on the new org-cite functionality. However, there have been
|
||||
big developments with Roam as of late.
|
||||
</p>
|
||||
<div id="outline-container-org-roam-v2" class="outline-2">
|
||||
<h2 id="org-roam-v2"><a href="https://github.com/org-roam/org-roam">Org-roam v2</a><a aria-hidden="true" href="#org-roam-v2">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-org-roam-v2">
|
||||
<p>
|
||||
Pushed to the sidelines by last month’s hugely significant citations
|
||||
announcement was the release of Org-roam v2 🎉. The project’s author Jethro
|
||||
wrote a nice <a href="https://blog.jethro.dev/posts/org_roam_v2/">blog post</a> outlining the major changes and motivations, and so I’ll
|
||||
leave him to speak on that. Suffice to say, the idea of org-roam has been
|
||||
refined into a form that should better server tinkerers looking to build off Org
|
||||
roam, and make maintenance easier — thus improving the user experience in the
|
||||
long term 🙂. Should you be worried that the v1 → v2 upgrade will be painful,
|
||||
read <a href="https://macowners.club/posts/org-roam-v2-doesnt-hurt/">Org-roam v2 doesn’t hurt</a>, relax, and try the upgrade wizard.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-org-roam-ui" class="outline-2">
|
||||
<h2 id="org-roam-ui"><a href="https://github.com/org-roam/org-roam-ui/">Org-roam-ui</a><a aria-hidden="true" href="#org-roam-ui">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-org-roam-ui">
|
||||
<p>
|
||||
Within a month of Roam v2’s announcement, we were pleasantly surprised by the
|
||||
release of <a href="https://github.com/org-roam/org-roam-server">org-roam-server</a> usurper — org-roam-ui.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org178ef09">
|
||||
<img src="figures/org-roam-graph-2d-overview.png" alt="org-roam-graph-2d-overview.png" class="doom-one" width="50%">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 1: </span>org-roam-ui’s 2D overview.</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
While org-roam-server remains incompatible with Roam v2, org-roam-ui is built
|
||||
around v2 from the ground up. With this shift comes a much more ambitious set
|
||||
of features. The graph view itself is now based on <a href="https://github.com/vasturiano/react-force-graph">react-force-graph</a>, which
|
||||
allows for both 2D and 3D views of the graph, with WebGL acceleration.
|
||||
</p>
|
||||
|
||||
<figure>
|
||||
<video width="60%" height="auto" autoplay loop muted class="doom-one">
|
||||
<source src="figures/org-roam-ui-3d-rotation.mp4" type="video/mp4" />
|
||||
</video>
|
||||
<figcaption>
|
||||
<span class="figure-number">Figure 1.1:</span>
|
||||
org-roam-ui's 3D graph view.
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
Using <a href="https://github.com/ahyatt/emacs-websocket">emacs-websocket</a>, org-roam-ui establishes a two-way connection between
|
||||
Emacs and the Web visualisation. This allows for nifty features like syncing the
|
||||
graph view and the currently open roam file in Emacs. Furthermore, with
|
||||
<kbd>xwidget-webkit</kbd> you can even embed org-roam-ui <i>inside</i> Emacs!<sup><a id="fnr.1" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="orged74fed">
|
||||
<img src="figures/org-roam-ui-in-emacs.png" alt="org-roam-ui-in-emacs.png" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 2: </span>Embed org-roam-ui in Emacs using xwidget-webkit.</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
Beyond this, org-roam-ui also provides a number of other nice features, such as
|
||||
filtering and theme syncing, with more in the works. To see more, check out the
|
||||
<kbd>README</kbd> published on GitHub.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<div class="link-preview"><a href="https://github.com/org-roam/org-roam-ui/"><img src="https://repository-images.githubusercontent.com/386398327/72086426-51c8-4b7b-86f1-950195373de7"/><small>github.com</small><p><b>GitHub - org-roam/org-roam-ui: A graphical frontend for exploring your org-roam Zettelkasten</b></br>A graphical frontend for exploring your org-roam Zettelkasten - GitHub - org-roam/org-roam-ui: A graphical frontend for exploring your org-roam Zettelkasten</p></a></div>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-new-context-exporter" class="outline-2">
|
||||
<h2 id="new-context-exporter">New ConTeXt exporter<a aria-hidden="true" href="#new-context-exporter">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-new-context-exporter">
|
||||
<p>
|
||||
We’ve long been able to export to LaTeX files with <kbd>ox-latex</kbd>, but now you can
|
||||
export to ConTeXt too with <a href="https://github.com/Jason-S-Ross/ox-context">ox-context</a>! While only just released, a lot of work
|
||||
has already gone into this — with development starting almost a year ago by the
|
||||
commit history.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<div class="link-preview"><a href="https://github.com/Jason-S-Ross/ox-context"><img src="https://opengraph.githubassets.com/911927be079fa6588bc60b179d8c13df1327e703acf2e0848cb282fb3c739d43/Jason-S-Ross/ox-context"/><small>github.com</small><p><b>GitHub - Jason-S-Ross/ox-context: An Org Mode export backend for ConTeXt</b></br>An Org Mode export backend for ConTeXt. Contribute to Jason-S-Ross/ox-context development by creating an account on GitHub.</p></a></div>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
It’s always nice to see more export options for Org, and I wish Jason all the
|
||||
best in developing <kbd>ox-context</kbd>.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-other-improvements" class="outline-2">
|
||||
<h2 id="other-improvements">Other improvements<a aria-hidden="true" href="#other-improvements">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-other-improvements">
|
||||
<ul class="org-ul">
|
||||
<li>Refactor <kbd>oc-natbib.el</kbd>, <kbd>oc-biblatex</kbd>, <kbd>oc-basic.el</kbd>, <kbd>org-compat.el</kbd> to improve byte
|
||||
compilation <span class="underline">Maxim Nikulin</span> <span class="underline">Nicolas Goaziou</span> <span class="underline">Marco Wahl</span></li>
|
||||
<li>Allow for selecting cite style with a citation argument <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Add support for Italian “smart quotes” <span class="underline">DPDmancul</span></li>
|
||||
<li>Fix Spanish mistranslation in footnote Documentation <span class="underline">Juan Manuel Macias</span></li>
|
||||
<li>Define <kbd>\citeprocitem</kbd> in <kbd>oc-csl.el</kbd> for use by <kbd>citeproc-el</kbd> <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>Fix error in <kbd>org-export-define-backend</kbd> docstring <span class="underline">Zachary Kanfer</span> <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Document the <kbd>:results none</kbd> option <span class="underline">Yasushi Shoji</span></li>
|
||||
<li>Other documentation improvements: <span class="underline">Jorge Neto</span> <span class="underline">Marco Wahl</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-bugfixes" class="outline-2">
|
||||
<h2 id="bugfixes">Bugfixes<a aria-hidden="true" href="#bugfixes">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-bugfixes">
|
||||
<ul class="org-ul">
|
||||
<li>When tangling a certain language, be more careful about which blocks are
|
||||
matched <span class="underline"><span class='acr'>DMG</span>, Nicolas Goaziou</span></li>
|
||||
<li>Make <kbd>q</kbd> in <kbd>org-agenda</kbd> work even when <code>debug-on-error</code> is set <span class="underline">Lars Ingebrigtsen</span></li>
|
||||
<li>Make <kbd>org-attach</kbd> work again for Emacs \(< 28\) <span class="underline">Kyle Meyer, Marco Wahl</span></li>
|
||||
<li>Make <code>rx</code> usage in <kbd>org-cite</kbd> files compatible with Emacs \(< 27.1\) <span class="underline">Max Nikulin</span></li>
|
||||
<li>Prevent <kbd>'</kbd> from becoming a LaTeX active char in exports using <kbd>oc-csl</kbd> <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>Have <kbd>org-colview</kbd> dynblock <kbd>match</kbd> and <kbd>mixlevel</kbd> interact sensibly <span class="underline">Nick Dokos</span></li>
|
||||
<li>Behave appropriately when <code>ffap-url-regexp</code> is <code>nil</code>, instead of throwing an error
|
||||
<span class="underline">Peder Stray</span> <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="footnotes">
|
||||
<h2 class="footnotes">Footnotes: </h2>
|
||||
<div id="text-footnotes">
|
||||
|
||||
<div class="footdef"><sup><a id="fn.1" class="footnum" href="#fnr.1" role="doc-backlink">1</a></sup> <div class="footpara" role="doc-footnote"><p class="footpara">
|
||||
I have found the <kbd>xwidget-webkit</kbd> experience quite unstable until I
|
||||
started using Emacs 28 with the pure-<span class='acr'>GTK</span> branch. So, if you’re not getting a
|
||||
good experience now, there’s a good chance you’ll have a better experience in
|
||||
the future.
|
||||
</p></div></div>
|
||||
|
||||
|
||||
</div>
|
||||
</div></div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
# Created 2024-01-12 Fri 13:39
|
||||
#+title: August 2021
|
||||
#+subtitle: Roaming around
|
||||
#+author: TEC
|
||||
#+date: 2021-08-38
|
||||
|
||||
#+author: TEC
|
||||
#+subtitle: Roaming around
|
||||
#+begin_quote
|
||||
Dear readers, unfortunately I've been unusually busy as of late, and will
|
||||
continue to be for a bit over a month. As such, it's entirely likely that the
|
||||
|
|
@ -12,7 +12,6 @@ next post or two may +be late+ make use of creative dates too.
|
|||
In terms of Org development, we've had a fairly slow month --- mostly tweaks and
|
||||
fixes, concentrated on the new org-cite functionality. However, there have been
|
||||
big developments with Roam as of late.
|
||||
|
||||
* [[https://github.com/org-roam/org-roam][Org-roam v2]]
|
||||
|
||||
Pushed to the sidelines by last month's hugely significant citations
|
||||
|
|
@ -23,15 +22,12 @@ refined into a form that should better server tinkerers looking to build off Org
|
|||
roam, and make maintenance easier --- thus improving the user experience in the
|
||||
long term 🙂. Should you be worried that the v1 -> v2 upgrade will be painful,
|
||||
read [[https://macowners.club/posts/org-roam-v2-doesnt-hurt/][Org-roam v2 doesn't hurt]], relax, and try the upgrade wizard.
|
||||
|
||||
* [[https://github.com/org-roam/org-roam-ui/][Org-roam-ui]]
|
||||
|
||||
Within a month of Roam v2's announcement, we were pleasantly surprised by the
|
||||
release of [[https://github.com/org-roam/org-roam-server][org-roam-server]] usurper --- org-roam-ui.
|
||||
|
||||
#+caption: org-roam-ui's 2D overview.
|
||||
#+attr_html: :class doom-one :width 50%
|
||||
#+attr_latex: :width 0.5\linewidth
|
||||
[[file:figures/org-roam-graph-2d-overview.png]]
|
||||
|
||||
While org-roam-server remains incompatible with Roam v2, org-roam-ui is built
|
||||
|
|
@ -39,33 +35,24 @@ around v2 from the ground up. With this shift comes a much more ambitious set
|
|||
of features. The graph view itself is now based on [[https://github.com/vasturiano/react-force-graph][react-force-graph]], which
|
||||
allows for both 2D and 3D views of the graph, with WebGL acceleration.
|
||||
|
||||
#+begin_export html
|
||||
<figure>
|
||||
<video width="60%" height="auto" autoplay loop muted class="doom-one">
|
||||
<source src="figures/org-roam-ui-3d-rotation.mp4" type="video/mp4" />
|
||||
</video>
|
||||
<figcaption>
|
||||
<span class="figure-number">Figure 1.1:</span>
|
||||
org-roam-ui's 3D graph view.
|
||||
</figcaption>
|
||||
</figure>
|
||||
#+end_export
|
||||
|
||||
Using [[https://github.com/ahyatt/emacs-websocket][emacs-websocket]], org-roam-ui establishes a two-way connection between
|
||||
Emacs and the Web visualisation. This allows for nifty features like syncing the
|
||||
graph view and the currently open roam file in Emacs. Furthermore, with
|
||||
=xwidget-webkit= you can even embed org-roam-ui /inside/ Emacs![fn:1]
|
||||
|
||||
#+caption: Embed org-roam-ui in Emacs using xwidget-webkit.
|
||||
#+attr_html: :class invertible
|
||||
[[file:figures/org-roam-ui-in-emacs.png]]
|
||||
|
||||
Beyond this, org-roam-ui also provides a number of other nice features, such as
|
||||
filtering and theme syncing, with more in the works. To see more, check out the
|
||||
=README= published on GitHub.
|
||||
|
||||
[[Https://github.com/org-roam/org-roam-ui/]]
|
||||
//github.com/org-roam/org-roam-ui/
|
||||
|
||||
[fn:1] I have found the =xwidget-webkit= experience quite unstable until I
|
||||
started using Emacs 28 with the pure-GTK branch. So, if you're not getting a
|
||||
good experience now, there's a good chance you'll have a better experience in
|
||||
the future.
|
||||
* New ConTeXt exporter
|
||||
|
||||
We've long been able to export to LaTeX files with =ox-latex=, but now you can
|
||||
|
|
@ -73,36 +60,27 @@ export to ConTeXt too with [[https://github.com/Jason-S-Ross/ox-context][ox-cont
|
|||
has already gone into this --- with development starting almost a year ago by the
|
||||
commit history.
|
||||
|
||||
Https://github.com/Jason-S-Ross/ox-context
|
||||
//github.com/Jason-S-Ross/ox-context
|
||||
|
||||
It's always nice to see more export options for Org, and I wish Jason all the
|
||||
best in developing =ox-context=.
|
||||
|
||||
* Other improvements
|
||||
+ Refactor =oc-natbib.el=, =oc-biblatex=, =oc-basic.el=, =org-compat.el= to improve byte
|
||||
- Refactor =oc-natbib.el=, =oc-biblatex=, =oc-basic.el=, =org-compat.el= to improve byte
|
||||
compilation _Maxim Nikulin_ _Nicolas Goaziou_ _Marco Wahl_
|
||||
+ Allow for selecting cite style with a citation argument _Nicolas Goaziou_
|
||||
+ Add support for Italian "smart quotes" _DPDmancul_
|
||||
+ Fix Spanish mistranslation in footnote Documentation _Juan Manuel Macias_
|
||||
+ Define =\citeprocitem= in =oc-csl.el= for use by =citeproc-el= _TEC_
|
||||
+ Fix error in =org-export-define-backend= docstring _Zachary Kanfer_ _Nicolas Goaziou_
|
||||
+ Document the =:results none= option _Yasushi Shoji_
|
||||
+ Other documentation improvements: _Jorge Neto_ _Marco Wahl_
|
||||
|
||||
- Allow for selecting cite style with a citation argument _Nicolas Goaziou_
|
||||
- Add support for Italian "smart quotes" _DPDmancul_
|
||||
- Fix Spanish mistranslation in footnote Documentation _Juan Manuel Macias_
|
||||
- Define =\citeprocitem= in =oc-csl.el= for use by =citeproc-el= _TEC_
|
||||
- Fix error in =org-export-define-backend= docstring _Zachary Kanfer_ _Nicolas Goaziou_
|
||||
- Document the =:results none= option _Yasushi Shoji_
|
||||
- Other documentation improvements: _Jorge Neto_ _Marco Wahl_
|
||||
* Bugfixes
|
||||
+ When tangling a certain language, be more careful about which blocks are
|
||||
- When tangling a certain language, be more careful about which blocks are
|
||||
matched _DMG, Nicolas Goaziou_
|
||||
+ Make =q= in =org-agenda= work even when ~debug-on-error~ is set _Lars Ingebrigtsen_
|
||||
+ Make =org-attach= work again for Emacs \(< 28\) _Kyle Meyer, Marco Wahl_
|
||||
+ Make ~rx~ usage in =org-cite= files compatible with Emacs \(< 27.1\) _Max Nikulin_
|
||||
+ Prevent ='= from becoming a LaTeX active char in exports using =oc-csl= _TEC_
|
||||
+ Have =org-colview= dynblock =match= and =mixlevel= interact sensibly _Nick Dokos_
|
||||
+ Behave appropriately when ~ffap-url-regexp~ is ~nil~, instead of throwing an error
|
||||
- Make =q= in =org-agenda= work even when ~debug-on-error~ is set _Lars Ingebrigtsen_
|
||||
- Make =org-attach= work again for Emacs \(< 28\) _Kyle Meyer, Marco Wahl_
|
||||
- Make ~rx~ usage in =org-cite= files compatible with Emacs \(< 27.1\) _Max Nikulin_
|
||||
- Prevent ='= from becoming a LaTeX active char in exports using =oc-csl= _TEC_
|
||||
- Have =org-colview= dynblock =match= and =mixlevel= interact sensibly _Nick Dokos_
|
||||
- Behave appropriately when ~ffap-url-regexp~ is ~nil~, instead of throwing an error
|
||||
_Peder Stray_ _TEC_
|
||||
|
||||
* Footnotes
|
||||
|
||||
[fn:1] I have found the =xwidget-webkit= experience quite unstable until I
|
||||
started using Emacs 28 with the pure-GTK branch. So, if you're not getting a
|
||||
good experience now, there's a good chance you'll have a better experience in
|
||||
the future.
|
||||
|
|
@ -0,0 +1,229 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>2021-08-38-roaming.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">August 2021
|
||||
</span><span style="color: #9e9e9e;">#+subtitle:</span> Roaming around
|
||||
<span style="color: #9e9e9e;">#+author:</span> TEC
|
||||
<span style="color: #9e9e9e;">#+date:</span> 2021-08-38
|
||||
|
||||
<span class="ef-obb">#+begin_quote
|
||||
</span>Dear readers, unfortunately I've been unusually busy as of late, and will
|
||||
continue to be for a bit over a month. As such, it's entirely likely that the
|
||||
next post or two may <span style="text-decoration: line-through;">+be late+</span> make use of creative dates too.
|
||||
<span class="ef-obe">#+end_quote
|
||||
</span>
|
||||
In terms of Org development, we've had a fairly slow month --- mostly tweaks and
|
||||
fixes, concentrated on the new org-cite functionality. However, there have been
|
||||
big developments with Roam as of late.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* </span><span style="color: #3b6ea8; font-weight: 700; font-size: 1.25em">[[https://github.com/org-roam/org-roam][</span><span style="color: #3b6ea8; font-weight: 700; font-size: 1.25em">Org-roam v2</span><span style="color: #3b6ea8; font-weight: 700; font-size: 1.25em">]</span><span style="color: #3b6ea8; font-weight: 700; font-size: 1.25em">]</span>
|
||||
|
||||
Pushed to the sidelines by last month's hugely significant citations
|
||||
announcement was the release of Org-roam v2 🎉. The project's author Jethro
|
||||
wrote a nice <span style="color: #3b6ea8; font-weight: 700;">[[https://blog.jethro.dev/posts/org_roam_v2/][blog post]]</span> outlining the major changes and motivations, and so I'll
|
||||
leave him to speak on that. Suffice to say, the idea of org-roam has been
|
||||
refined into a form that should better server tinkerers looking to build off Org
|
||||
roam, and make maintenance easier --- thus improving the user experience in the
|
||||
long term 🙂. Should you be worried that the v1 -> v2 upgrade will be painful,
|
||||
read <span style="color: #3b6ea8; font-weight: 700;">[[https://macowners.club/posts/org-roam-v2-doesnt-hurt/][Org-roam v2 doesn't hurt]]</span>, relax, and try the upgrade wizard.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* </span><span style="color: #3b6ea8; font-weight: 700; font-size: 1.25em">[[https://github.com/org-roam/org-roam-ui/][</span><span style="color: #3b6ea8; font-weight: 700; font-size: 1.25em">Org-roam-ui</span><span style="color: #3b6ea8; font-weight: 700; font-size: 1.25em">]</span><span style="color: #3b6ea8; font-weight: 700; font-size: 1.25em">]</span>
|
||||
|
||||
Within a month of Roam v2's announcement, we were pleasantly surprised by the
|
||||
release of <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/org-roam/org-roam-server][org-roam-server]]</span> usurper --- org-roam-ui.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">org-roam-ui's 2D overview.</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class doom-one :width 50%</span>
|
||||
<span style="color: #b1b1b1;">#+attr_latex: :width 0.5\linewidth</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/org-roam-graph-2d-overview.png]]</span>
|
||||
|
||||
While org-roam-server remains incompatible with Roam v2, org-roam-ui is built
|
||||
around v2 from the ground up. With this shift comes a much more ambitious set
|
||||
of features. The graph view itself is now based on <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/vasturiano/react-force-graph][react-force-graph]]</span>, which
|
||||
allows for both 2D and 3D views of the graph, with WebGL acceleration.
|
||||
|
||||
<span class="ef-obb">#+begin_export html
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;"><figure>
|
||||
<video width="60%" height="auto" autoplay loop muted class="doom-one">
|
||||
<source src="figures/org-roam-ui-3d-rotation.mp4" type="video/mp4" />
|
||||
</video>
|
||||
<figcaption>
|
||||
<span class="figure-number">Figure 1.1:</span>
|
||||
org-roam-ui's 3D graph view.
|
||||
</figcaption>
|
||||
</figure>
|
||||
</span><span class="ef-obe">#+end_export
|
||||
</span>
|
||||
Using <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/ahyatt/emacs-websocket][emacs-websocket]]</span>, org-roam-ui establishes a two-way connection between
|
||||
Emacs and the Web visualisation. This allows for nifty features like syncing the
|
||||
graph view and the currently open roam file in Emacs. Furthermore, with
|
||||
<span style="color: #9e9e9e;">=xwidget-webkit=</span> you can even embed org-roam-ui <span class="ef-i">/inside/</span> Emacs![fn:1]
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Embed org-roam-ui in Emacs using xwidget-webkit.</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/org-roam-ui-in-emacs.png]]</span>
|
||||
|
||||
Beyond this, org-roam-ui also provides a number of other nice features, such as
|
||||
filtering and theme syncing, with more in the works. To see more, check out the
|
||||
<span style="color: #9e9e9e;">=README=</span> published on GitHub.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[Https://github.com/org-roam/org-roam-ui/]]</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* New ConTeXt exporter</span>
|
||||
|
||||
We've long been able to export to LaTeX files with <span style="color: #9e9e9e;">=ox-latex=</span>, but now you can
|
||||
export to ConTeXt too with <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/Jason-S-Ross/ox-context][ox-context]]</span>! While only just released, a lot of work
|
||||
has already gone into this --- with development starting almost a year ago by the
|
||||
commit history.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: 700;">Https://github.com/Jason-S-Ross/ox-context</span>
|
||||
|
||||
It's always nice to see more export options for Org, and I wish Jason all the
|
||||
best in developing <span style="color: #9e9e9e;">=ox-context=</span>.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Other improvements</span>
|
||||
+ Refactor <span style="color: #9e9e9e;">=oc-natbib.el=</span>, <span style="color: #9e9e9e;">=oc-biblatex=</span>, <span style="color: #9e9e9e;">=oc-basic.el=</span>, <span style="color: #9e9e9e;">=org-compat.el=</span> to improve byte
|
||||
compilation _Maxim Nikulin_ _Nicolas Goaziou_ _Marco Wahl_
|
||||
+ Allow for selecting cite style with a citation argument _Nicolas Goaziou_
|
||||
+ Add support for Italian "smart quotes" _DPDmancul_
|
||||
+ Fix Spanish mistranslation in footnote Documentation _Juan Manuel Macias_
|
||||
+ Define <span style="color: #9e9e9e;">=\citeprocitem=</span> in <span style="color: #9e9e9e;">=oc-csl.el=</span> for use by <span style="color: #9e9e9e;">=citeproc-el=</span> _TEC_
|
||||
+ Fix error in <span style="color: #9e9e9e;">=org-export-define-backend=</span> docstring _Zachary Kanfer_ _Nicolas Goaziou_
|
||||
+ Document the <span style="color: #9e9e9e;">=:results none=</span> option _Yasushi Shoji_
|
||||
+ Other documentation improvements: _Jorge Neto_ _Marco Wahl_
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Bugfixes</span>
|
||||
+ When tangling a certain language, be more careful about which blocks are
|
||||
matched _DMG, Nicolas Goaziou_
|
||||
+ Make <span style="color: #9e9e9e;">=q=</span> in <span style="color: #9e9e9e;">=org-agenda=</span> work even when <span style="color: #9e9e9e;">~debug-on-error~</span> is set _Lars Ingebrigtsen_
|
||||
+ Make <span style="color: #9e9e9e;">=org-attach=</span> work again for Emacs \(< 28\) _Kyle Meyer, Marco Wahl_
|
||||
+ Make <span style="color: #9e9e9e;">~rx~</span> usage in <span style="color: #9e9e9e;">=org-cite=</span> files compatible with Emacs \(< 27.1\) _Max Nikulin_
|
||||
+ Prevent <span style="color: #9e9e9e;">='=</span> from becoming a LaTeX active char in exports using <span style="color: #9e9e9e;">=oc-csl=</span> _TEC_
|
||||
+ Have <span style="color: #9e9e9e;">=org-colview=</span> dynblock <span style="color: #9e9e9e;">=match=</span> and <span style="color: #9e9e9e;">=mixlevel=</span> interact sensibly _Nick Dokos_
|
||||
+ Behave appropriately when <span style="color: #9e9e9e;">~ffap-url-regexp~</span> is <span style="color: #9e9e9e;">~nil~</span>, instead of throwing an error
|
||||
_Peder Stray_ _TEC_
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Footnotes</span>
|
||||
|
||||
[fn:1] I have found the <span style="color: #9e9e9e;">=xwidget-webkit=</span> experience quite unstable until I
|
||||
started using Emacs 28 with the pure-GTK branch. So, if you're not getting a
|
||||
good experience now, there's a good chance you'll have a better experience in
|
||||
the future.
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,143 @@
|
|||
━━━━━━━━━━━━━━━━
|
||||
AUGUST 2021
|
||||
Roaming around
|
||||
|
||||
TEC
|
||||
━━━━━━━━━━━━━━━━
|
||||
|
||||
|
||||
2021-08-38
|
||||
|
||||
|
||||
Dear readers, unfortunately I’ve been unusually busy as of
|
||||
late, and will continue to be for a bit over a month. As
|
||||
such, it’s entirely likely that the next post or two may +be
|
||||
late+ make use of creative dates too.
|
||||
|
||||
In terms of Org development, we’ve had a fairly slow month — mostly
|
||||
tweaks and fixes, concentrated on the new org-cite
|
||||
functionality. However, there have been big developments with Roam as of
|
||||
late.
|
||||
|
||||
|
||||
[Org-roam v2]
|
||||
═════════════
|
||||
|
||||
Pushed to the sidelines by last month’s hugely significant citations
|
||||
announcement was the release of Org-roam v2 🎉. The project’s author
|
||||
Jethro wrote a nice [blog post] outlining the major changes and
|
||||
motivations, and so I’ll leave him to speak on that. Suffice to say,
|
||||
the idea of org-roam has been refined into a form that should better
|
||||
server tinkerers looking to build off Org roam, and make maintenance
|
||||
easier — thus improving the user experience in the long term
|
||||
🙂. Should you be worried that the v1 -> v2 upgrade will be painful,
|
||||
read [Org-roam v2 doesn’t hurt], relax, and try the upgrade wizard.
|
||||
|
||||
|
||||
[Org-roam v2] <https://github.com/org-roam/org-roam>
|
||||
|
||||
[blog post] <https://blog.jethro.dev/posts/org_roam_v2/>
|
||||
|
||||
[Org-roam v2 doesn’t hurt]
|
||||
<https://macowners.club/posts/org-roam-v2-doesnt-hurt/>
|
||||
|
||||
|
||||
[Org-roam-ui]
|
||||
═════════════
|
||||
|
||||
Within a month of Roam v2’s announcement, we were pleasantly surprised
|
||||
by the release of [org-roam-server] usurper — org-roam-ui.
|
||||
|
||||
<file:figures/org-roam-graph-2d-overview.png>
|
||||
|
||||
While org-roam-server remains incompatible with Roam v2, org-roam-ui
|
||||
is built around v2 from the ground up. With this shift comes a much
|
||||
more ambitious set of features. The graph view itself is now based on
|
||||
[react-force-graph], which allows for both 2D and 3D views of the
|
||||
graph, with WebGL acceleration.
|
||||
|
||||
Using [emacs-websocket], org-roam-ui establishes a two-way connection
|
||||
between Emacs and the Web visualisation. This allows for nifty
|
||||
features like syncing the graph view and the currently open roam file
|
||||
in Emacs. Furthermore, with `xwidget-webkit' you can even embed
|
||||
org-roam-ui /inside/ Emacs![1]
|
||||
|
||||
<file:figures/org-roam-ui-in-emacs.png>
|
||||
|
||||
Beyond this, org-roam-ui also provides a number of other nice
|
||||
features, such as filtering and theme syncing, with more in the
|
||||
works. To see more, check out the `README' published on GitHub.
|
||||
|
||||
//github.com/org-roam/org-roam-ui/
|
||||
|
||||
|
||||
[Org-roam-ui] <https://github.com/org-roam/org-roam-ui/>
|
||||
|
||||
[org-roam-server] <https://github.com/org-roam/org-roam-server>
|
||||
|
||||
[react-force-graph] <https://github.com/vasturiano/react-force-graph>
|
||||
|
||||
[emacs-websocket] <https://github.com/ahyatt/emacs-websocket>
|
||||
|
||||
|
||||
New ConTeXt exporter
|
||||
════════════════════
|
||||
|
||||
We’ve long been able to export to LaTeX files with `ox-latex', but now
|
||||
you can export to ConTeXt too with [ox-context]! While only just
|
||||
released, a lot of work has already gone into this — with development
|
||||
starting almost a year ago by the commit history.
|
||||
|
||||
//github.com/Jason-S-Ross/ox-context
|
||||
|
||||
It’s always nice to see more export options for Org, and I wish Jason
|
||||
all the best in developing `ox-context'.
|
||||
|
||||
|
||||
[ox-context] <https://github.com/Jason-S-Ross/ox-context>
|
||||
|
||||
|
||||
Other improvements
|
||||
══════════════════
|
||||
|
||||
⁃ Refactor `oc-natbib.el', `oc-biblatex', `oc-basic.el',
|
||||
`org-compat.el' to improve byte compilation _Maxim Nikulin_ _Nicolas
|
||||
Goaziou_ _Marco Wahl_
|
||||
⁃ Allow for selecting cite style with a citation argument _Nicolas
|
||||
Goaziou_
|
||||
⁃ Add support for Italian “smart quotes” _DPDmancul_
|
||||
⁃ Fix Spanish mistranslation in footnote Documentation _Juan Manuel
|
||||
Macias_
|
||||
⁃ Define `\citeprocitem' in `oc-csl.el' for use by `citeproc-el' _TEC_
|
||||
⁃ Fix error in `org-export-define-backend' docstring _Zachary Kanfer_
|
||||
_Nicolas Goaziou_
|
||||
⁃ Document the `:results none' option _Yasushi Shoji_
|
||||
⁃ Other documentation improvements: _Jorge Neto_ _Marco Wahl_
|
||||
|
||||
|
||||
Bugfixes
|
||||
════════
|
||||
|
||||
⁃ When tangling a certain language, be more careful about which blocks
|
||||
are matched _DMG, Nicolas Goaziou_
|
||||
⁃ Make `q' in `org-agenda' work even when `debug-on-error' is set
|
||||
_Lars Ingebrigtsen_
|
||||
⁃ Make `org-attach' work again for Emacs < 28 _Kyle Meyer, Marco Wahl_
|
||||
⁃ Make `rx' usage in `org-cite' files compatible with Emacs < 27.1
|
||||
_Max Nikulin_
|
||||
⁃ Prevent `'' from becoming a LaTeX active char in exports using
|
||||
`oc-csl' _TEC_
|
||||
⁃ Have `org-colview' dynblock `match' and `mixlevel' interact sensibly
|
||||
_Nick Dokos_
|
||||
⁃ Behave appropriately when `ffap-url-regexp' is `nil', instead of
|
||||
throwing an error _Peder Stray_ _TEC_
|
||||
|
||||
|
||||
|
||||
Footnotes
|
||||
─────────
|
||||
|
||||
[1] I have found the `xwidget-webkit' experience quite unstable until
|
||||
I started using Emacs 28 with the pure-GTK branch. So, if you’re not
|
||||
getting a good experience now, there’s a good chance you’ll have a
|
||||
better experience in the future.
|
||||
|
|
@ -0,0 +1,218 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-12 Fri 13:39 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>October 2021</title>
|
||||
<meta name="author" content="TEC" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="October 2021" />
|
||||
<meta property="og:description" content="Release 9.5" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="TEC" />
|
||||
<meta property="og:article:published_time" content="2021-10-31T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2021-11-01T04:31:52+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2021-10-31, <span class='acr'>TEC</span></div>
|
||||
|
||||
<h1 class="title">October 2021</h1>
|
||||
<p class="subtitle" role="doc-subtitle">Release 9.5</p>
|
||||
</header><blockquote>
|
||||
<p>
|
||||
Turns out that life became busy enough that instead of delaying, last month’s
|
||||
post had to be cancelled. We’re now back to business as usual though 🙂.
|
||||
</p>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
There have been some cool recent developments in Org over the past two months,
|
||||
but you’ll have to learn about those is next month’s edition as <i>Org 9.5 has been
|
||||
released</i> 🎉. So, let’s go over some of the changes I’m most excited about, in no
|
||||
particular order. To get a more complete picture of the latest changes, see
|
||||
<a href="https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/etc/ORG-NEWS?h=release_9.5#n14"><span class='acr'>ORG</span>-<span class='acr'>NEWS</span></a>.
|
||||
</p>
|
||||
<div id="outline-container-new-citation-engine" class="outline-2">
|
||||
<h2 id="new-citation-engine">The new citation engine<a aria-hidden="true" href="#new-citation-engine">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-new-citation-engine">
|
||||
<p>
|
||||
As tempted as I am to wax lyrical about the lovely new citation engine, I’ve
|
||||
already dedicated <a href="2021-07-31-citations.html">July’s post</a> to it, and so will simply highlight how versatile
|
||||
the syntax is. Combined with the ability to swap out the default backends
|
||||
(basic, <span class='acr'>CSL</span>, natbib, and bib(la)tex) for a 3rd party backend (for example,
|
||||
provided by a package) it is capable of meeting your citation and technical
|
||||
document publishing needs, whatever they may be.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org38c4d6c">
|
||||
<img src="figures/citation-structure-full.svg" alt="citation-structure-full.svg" class="org-svg">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 1: </span>The full citation syntax</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
Since the announcement of org-cite, the ecosystem has continued to expand with a
|
||||
number of promising packages like Bruce D’Arcus’ <a href="https://github.com/bdarcus/citar">citar</a> (previously
|
||||
<i>bibtex-actions</i>), which currently provides what is arguably the best citation
|
||||
insertion experience.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org95924c1">
|
||||
<img src="figures/org-citar-insertion.png" alt="org-citar-insertion.png" class="doom-one">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 2: </span>Inserting a citation with the <i>citar</i> package</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-asynchronous-session-evaluation" class="outline-2">
|
||||
<h2 id="asynchronous-session-evaluation">Asynchronous session evaluation<a aria-hidden="true" href="#asynchronous-session-evaluation">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-asynchronous-session-evaluation">
|
||||
<p>
|
||||
Since being featured in <a href="2021-05-31-async.html">May’s post</a>, we’ve had the initial python support
|
||||
expanded with support for R too. I have good reason to believe that more
|
||||
backends will join this list in the future.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
To get started, just add <kbd>:async</kbd> to the header arguments of Python or R source
|
||||
blocks with a <kbd>:session</kbd>.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-latex-environment-results" class="outline-2">
|
||||
<h2 id="latex-environment-results">LaTeX environment <kbd>#+results</kbd> are now removed<a aria-hidden="true" href="#latex-environment-results">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-latex-environment-results">
|
||||
<p>
|
||||
LaTeX environments (i.e. <code class="src src-LaTeX"><span class="org-keyword">\begin</span>{} ... <span class="org-keyword">\end</span>{}</code> blocks) have been added
|
||||
to the list of <kbd>#+results</kbd> types that will be removed. This is bigger news than
|
||||
one might think, as it means that raw LaTeX environments are now a viable output
|
||||
for org-babel backends. This possesses a distinct advantage over <kbd>:results latex</kbd>
|
||||
as LaTeX environments can be rendered inline with <code>org-latex-preview</code> and are
|
||||
exported to more formats — for example <span class='acr'>HTML</span> with MathJax.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
This is likely going to be first seen in the new <kbd>ob-julia</kbd> backend (unreleased,
|
||||
currently in early development), but could well be utilised by other backends
|
||||
such as <kbd>ob-octave</kbd>, <kbd>ob-mathematica</kbd> (in contrib), <kbd>ob-python</kbd> (using <code>SymPy</code>), <kbd>ob-calc</kbd>
|
||||
and more.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="orgd10e7b4">
|
||||
<img src="figures/ob-julia-latexify-rendered.png" alt="ob-julia-latexify-rendered.png" class="doom-one">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 3: </span>Rendered LaTeX representations of some Julia values</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-more-fontification" class="outline-2">
|
||||
<h2 id="more-fontification">More fontification<a aria-hidden="true" href="#more-fontification">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-more-fontification">
|
||||
<p>
|
||||
A number of new faces have been introduced to allow for improved theming
|
||||
capability, and better contextual hints in the agenda, namely:
|
||||
<code>org-agenda-date-weekend-today</code>, <code>org-imminent-deadline</code>,
|
||||
<code>org-agenda-structure-secondary</code>, and <code>org-agenda-structure-filter</code>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Inline export snippets are now also fontified using the <code>org-tag</code> and
|
||||
<code>font-lock-comment-face</code> faces, to better stand out from surrounding text.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-more-link-formatting" class="outline-2">
|
||||
<h2 id="more-link-formatting">More link formatting options with org-capture<a aria-hidden="true" href="#more-link-formatting">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-more-link-formatting">
|
||||
<p>
|
||||
A new formatting directive, <code>%L</code> has been introduced which provides the bare link
|
||||
target. This allows for links with automatically generated descriptions 🙂.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-export-improvements" class="outline-2">
|
||||
<h2 id="export-improvements">Export improvements<a aria-hidden="true" href="#export-improvements">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-export-improvements">
|
||||
<p>
|
||||
The <span class='acr'>HTML</span> and LaTeX backends have both been given some love in this release of
|
||||
Org.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The <span class='acr'>HTML</span> backend now supports customisation of the <kbd><meta></kbd> tags included with
|
||||
<code>org-html-meta-tags</code>, which should be particularly useful to anybody using
|
||||
<kbd>org-publish</kbd> for blogs or websites (in fact, this blog has been making use of it
|
||||
for some time now). A new variable has been introduced to help with styling,
|
||||
<code>org-html-content-class</code> (<kbd>"content"</kbd> by default) which is used as the <span class='acr'>CSS</span> class for
|
||||
the top-level content wrapper. To further improve styling capabilities,
|
||||
<code>org-html-style-default</code> and <code>org-html-scripts</code> have been changed from constants to
|
||||
customisable variables.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The LaTeX backend (<kbd>ox-latex</kbd>) no longer has obsolete LaTeX packages in
|
||||
<code>org-latex-default-packages-alist</code> (<kbd>grffile</kbd> and <kbd>texcomp</kbd> have been removed).
|
||||
It also now supports arbitrary <kbd>:float</kbd> argument values, and accepts a six new
|
||||
arguments (in total) for verse (<kbd>:lines</kbd>, <kbd>:center</kbd>, <kbd>:versewidth</kbd>, and <kbd>:latexcode</kbd>)
|
||||
and quote blocks (<kbd>:environment</kbd> and <kbd>:options</kbd>).
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-project-changes" class="outline-2">
|
||||
<h2 id="project-changes">Project changes<a aria-hidden="true" href="#project-changes">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-project-changes">
|
||||
<p>
|
||||
To reduce the maintainer burden, the <kbd>contrib/</kbd> folder and a collection of
|
||||
rarely-used or barely-maintained <kbd>ob-*</kbd> backends have been moved to a new repo,
|
||||
<a href="https://git.sr.ht/~bzg/org-contrib">org-contrib</a>. Support for Emacs 24 (2012–2014) has also been dropped, and Org
|
||||
will now aim to support the three most recent major versions of Emacs.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
# Created 2024-01-12 Fri 13:39
|
||||
#+title: October 2021
|
||||
#+subtitle: Release 9.5
|
||||
#+author: TEC
|
||||
#+date: 2021-10-31
|
||||
|
||||
#+author: TEC
|
||||
#+subtitle: Release 9.5
|
||||
#+begin_quote
|
||||
Turns out that life became busy enough that instead of delaying, last month's
|
||||
post had to be cancelled. We're now back to business as usual though 🙂.
|
||||
|
|
@ -13,7 +13,6 @@ but you'll have to learn about those is next month's edition as /Org 9.5 has bee
|
|||
released/ 🎉. So, let's go over some of the changes I'm most excited about, in no
|
||||
particular order. To get a more complete picture of the latest changes, see
|
||||
[[https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/etc/ORG-NEWS?h=release_9.5#n14][ORG-NEWS]].
|
||||
|
||||
* The new citation engine
|
||||
|
||||
As tempted as I am to wax lyrical about the lovely new citation engine, I've
|
||||
|
|
@ -32,9 +31,7 @@ number of promising packages like Bruce D'Arcus' [[https://github.com/bdarcus/ci
|
|||
insertion experience.
|
||||
|
||||
#+caption: Inserting a citation with the /citar/ package
|
||||
#+attr_html: :class doom-one
|
||||
[[file:figures/org-citar-insertion.png]]
|
||||
|
||||
* Asynchronous session evaluation
|
||||
|
||||
Since being featured in [[file:2021-05-31-async.org][May's post]], we've had the initial python support
|
||||
|
|
@ -43,7 +40,6 @@ backends will join this list in the future.
|
|||
|
||||
To get started, just add =:async= to the header arguments of Python or R source
|
||||
blocks with a =:session=.
|
||||
|
||||
* LaTeX environment =#+results= are now removed
|
||||
|
||||
LaTeX environments (i.e. src_LaTeX{\begin{} ... \end{}} blocks) have been added
|
||||
|
|
@ -59,10 +55,7 @@ such as =ob-octave=, =ob-mathematica= (in contrib), =ob-python= (using ~SymPy~),
|
|||
and more.
|
||||
|
||||
#+caption: Rendered LaTeX representations of some Julia values
|
||||
#+attr_html: :class doom-one
|
||||
#+attr_latex: :width 0.5\linewidth
|
||||
[[file:figures/ob-julia-latexify-rendered.png]]
|
||||
|
||||
* More fontification
|
||||
|
||||
A number of new faces have been introduced to allow for improved theming
|
||||
|
|
@ -72,12 +65,10 @@ capability, and better contextual hints in the agenda, namely:
|
|||
|
||||
Inline export snippets are now also fontified using the ~org-tag~ and
|
||||
~font-lock-comment-face~ faces, to better stand out from surrounding text.
|
||||
|
||||
* More link formatting options with org-capture
|
||||
|
||||
A new formatting directive, ~%L~ has been introduced which provides the bare link
|
||||
target. This allows for links with automatically generated descriptions 🙂.
|
||||
|
||||
* Export improvements
|
||||
|
||||
The HTML and LaTeX backends have both been given some love in this release of
|
||||
|
|
@ -97,7 +88,6 @@ The LaTeX backend (=ox-latex=) no longer has obsolete LaTeX packages in
|
|||
It also now supports arbitrary =:float= argument values, and accepts a six new
|
||||
arguments (in total) for verse (=:lines=, =:center=, =:versewidth=, and =:latexcode=)
|
||||
and quote blocks (=:environment= and =:options=).
|
||||
|
||||
* Project changes
|
||||
|
||||
To reduce the maintainer burden, the =contrib/= folder and a collection of
|
||||
|
|
@ -0,0 +1,227 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>2021-10-31-release.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">October 2021
|
||||
</span><span style="color: #9e9e9e;">#+subtitle:</span> Release 9.5
|
||||
<span style="color: #9e9e9e;">#+author:</span> TEC
|
||||
<span style="color: #9e9e9e;">#+date:</span> 2021-10-31
|
||||
|
||||
<span class="ef-obb">#+begin_quote
|
||||
</span>Turns out that life became busy enough that instead of delaying, last month's
|
||||
post had to be cancelled. We're now back to business as usual though 🙂.
|
||||
<span class="ef-obe">#+end_quote
|
||||
</span>
|
||||
There have been some cool recent developments in Org over the past two months,
|
||||
but you'll have to learn about those is next month's edition as <span class="ef-i">/Org 9.5 has been
|
||||
released/</span> 🎉. So, let's go over some of the changes I'm most excited about, in no
|
||||
particular order. To get a more complete picture of the latest changes, see
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/etc/ORG-NEWS?h=release_9.5#n14][ORG-NEWS]]</span>.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* The new citation engine</span>
|
||||
|
||||
As tempted as I am to wax lyrical about the lovely new citation engine, I've
|
||||
already dedicated <span style="color: #3b6ea8; font-weight: 700;">[[file:2021-07-31-citations.org][July's post]]</span> to it, and so will simply highlight how versatile
|
||||
the syntax is. Combined with the ability to swap out the default backends
|
||||
(basic, CSL, natbib, and bib(la)tex) for a 3rd party backend (for example,
|
||||
provided by a package) it is capable of meeting your citation and technical
|
||||
document publishing needs, whatever they may be.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">The full citation syntax</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/citation-structure-full.svg]]</span>
|
||||
|
||||
Since the announcement of org-cite, the ecosystem has continued to expand with a
|
||||
number of promising packages like Bruce D'Arcus' <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/bdarcus/citar][citar]]</span> (previously
|
||||
<span class="ef-i">/bibtex-actions/</span>), which currently provides what is arguably the best citation
|
||||
insertion experience.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Inserting a citation with the /citar/ package</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class doom-one</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/org-citar-insertion.png]]</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Asynchronous session evaluation</span>
|
||||
|
||||
Since being featured in <span style="color: #3b6ea8; font-weight: 700;">[[file:2021-05-31-async.org][May's post]]</span>, we've had the initial python support
|
||||
expanded with support for R too. I have good reason to believe that more
|
||||
backends will join this list in the future.
|
||||
|
||||
To get started, just add <span style="color: #9e9e9e;">=:async=</span> to the header arguments of Python or R source
|
||||
blocks with a <span style="color: #9e9e9e;">=:session=</span>.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* LaTeX environment </span><span style="color: #9e9e9e; font-weight: nil; font-size: 1.25em">=#+results=</span><span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em"> are now removed</span>
|
||||
|
||||
LaTeX environments (i.e. <span style="color: #9e9e9e; background-color: #e0e0e0;">src_</span><span style="color: #b1b1b1; background-color: #e0e0e0;">LaTeX</span><span style="color: #9e9e9e; background-color: #e0e0e0;">{</span><span style="color: #3b6ea8; background-color: #e0e0e0;">\begin</span><span class="ef-ob">{} ... </span><span style="color: #3b6ea8; background-color: #e0e0e0;">\end</span><span class="ef-ob">{}</span><span style="color: #9e9e9e; background-color: #e0e0e0;">}</span> blocks) have been added
|
||||
to the list of <span style="color: #9e9e9e;">=#+results=</span> types that will be removed. This is bigger news than
|
||||
one might think, as it means that raw LaTeX environments are now a viable output
|
||||
for org-babel backends. This possesses a distinct advantage over <span style="color: #9e9e9e;">=:results latex=</span>
|
||||
as LaTeX environments can be rendered inline with <span style="color: #9e9e9e;">~org-latex-preview~</span> and are
|
||||
exported to more formats --- for example HTML with MathJax.
|
||||
|
||||
This is likely going to be first seen in the new <span style="color: #9e9e9e;">=ob-julia=</span> backend (unreleased,
|
||||
currently in early development), but could well be utilised by other backends
|
||||
such as <span style="color: #9e9e9e;">=ob-octave=</span>, <span style="color: #9e9e9e;">=ob-mathematica=</span> (in contrib), <span style="color: #9e9e9e;">=ob-python=</span> (using <span style="color: #9e9e9e;">~SymPy~</span>), <span style="color: #9e9e9e;">=ob-calc=</span>
|
||||
and more.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Rendered LaTeX representations of some Julia values</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class doom-one</span>
|
||||
<span style="color: #b1b1b1;">#+attr_latex: :width 0.5\linewidth</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/ob-julia-latexify-rendered.png]]</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* More fontification</span>
|
||||
|
||||
A number of new faces have been introduced to allow for improved theming
|
||||
capability, and better contextual hints in the agenda, namely:
|
||||
<span style="color: #9e9e9e;">~org-agenda-date-weekend-today~</span>, <span style="color: #9e9e9e;">~org-imminent-deadline~</span>,
|
||||
<span style="color: #9e9e9e;">~org-agenda-structure-secondary~</span>, and <span style="color: #9e9e9e;">~org-agenda-structure-filter~</span>.
|
||||
|
||||
Inline export snippets are now also fontified using the <span style="color: #9e9e9e;">~org-tag~</span> and
|
||||
<span style="color: #9e9e9e;">~font-lock-comment-face~</span> faces, to better stand out from surrounding text.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* More link formatting options with org-capture</span>
|
||||
|
||||
A new formatting directive, <span style="color: #9e9e9e;">~%L~</span> has been introduced which provides the bare link
|
||||
target. This allows for links with automatically generated descriptions 🙂.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Export improvements</span>
|
||||
|
||||
The HTML and LaTeX backends have both been given some love in this release of
|
||||
Org.
|
||||
|
||||
The HTML backend now supports customisation of the <span style="color: #9e9e9e;">=<meta>=</span> tags included with
|
||||
<span style="color: #9e9e9e;">~org-html-meta-tags~</span>, which should be particularly useful to anybody using
|
||||
<span style="color: #9e9e9e;">=org-publish=</span> for blogs or websites (in fact, this blog has been making use of it
|
||||
for some time now). A new variable has been introduced to help with styling,
|
||||
<span style="color: #9e9e9e;">~org-html-content-class~</span> (<span style="color: #9e9e9e;">="content"=</span> by default) which is used as the CSS class for
|
||||
the top-level content wrapper. To further improve styling capabilities,
|
||||
<span style="color: #9e9e9e;">~org-html-style-default~</span> and <span style="color: #9e9e9e;">~org-html-scripts~</span> have been changed from constants to
|
||||
customisable variables.
|
||||
|
||||
The LaTeX backend (<span style="color: #9e9e9e;">=ox-latex=</span>) no longer has obsolete LaTeX packages in
|
||||
<span style="color: #9e9e9e;">~org-latex-default-packages-alist~</span> (<span style="color: #9e9e9e;">=grffile=</span> and <span style="color: #9e9e9e;">=texcomp=</span> have been removed).
|
||||
It also now supports arbitrary <span style="color: #9e9e9e;">=:float=</span> argument values, and accepts a six new
|
||||
arguments (in total) for verse (<span style="color: #9e9e9e;">=:lines=</span>, <span style="color: #9e9e9e;">=:center=</span>, <span style="color: #9e9e9e;">=:versewidth=</span>, and <span style="color: #9e9e9e;">=:latexcode=</span>)
|
||||
and quote blocks (<span style="color: #9e9e9e;">=:environment=</span> and <span style="color: #9e9e9e;">=:options=</span>).
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Project changes</span>
|
||||
|
||||
To reduce the maintainer burden, the <span style="color: #9e9e9e;">=contrib/=</span> folder and a collection of
|
||||
rarely-used or barely-maintained <span style="color: #9e9e9e;">=ob-*=</span> backends have been moved to a new repo,
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[https://git.sr.ht/~bzg/org-contrib][org-contrib]]</span>. Support for Emacs 24 (2012--2014) has also been dropped, and Org
|
||||
will now aim to support the three most recent major versions of Emacs.
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,141 @@
|
|||
━━━━━━━━━━━━━━
|
||||
OCTOBER 2021
|
||||
Release 9.5
|
||||
|
||||
TEC
|
||||
━━━━━━━━━━━━━━
|
||||
|
||||
|
||||
2021-10-31
|
||||
|
||||
|
||||
Turns out that life became busy enough that instead of
|
||||
delaying, last month’s post had to be cancelled. We’re now
|
||||
back to business as usual though 🙂.
|
||||
|
||||
There have been some cool recent developments in Org over the past two
|
||||
months, but you’ll have to learn about those is next month’s edition as
|
||||
/Org 9.5 has been released/ 🎉. So, let’s go over some of the changes
|
||||
I’m most excited about, in no particular order. To get a more complete
|
||||
picture of the latest changes, see [ORG-NEWS].
|
||||
|
||||
|
||||
[ORG-NEWS]
|
||||
<https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/etc/ORG-NEWS?h=release_9.5#n14>
|
||||
|
||||
|
||||
The new citation engine
|
||||
═══════════════════════
|
||||
|
||||
As tempted as I am to wax lyrical about the lovely new citation
|
||||
engine, I’ve already dedicated [July’s post] to it, and so will simply
|
||||
highlight how versatile the syntax is. Combined with the ability to
|
||||
swap out the default backends (basic, CSL, natbib, and bib(la)tex) for
|
||||
a 3rd party backend (for example, provided by a package) it is capable
|
||||
of meeting your citation and technical document publishing needs,
|
||||
whatever they may be.
|
||||
|
||||
<file:figures/citation-structure-full.svg>
|
||||
|
||||
Since the announcement of org-cite, the ecosystem has continued to
|
||||
expand with a number of promising packages like Bruce D’Arcus’ [citar]
|
||||
(previously /bibtex-actions/), which currently provides what is
|
||||
arguably the best citation insertion experience.
|
||||
|
||||
<file:figures/org-citar-insertion.png>
|
||||
|
||||
|
||||
[July’s post] <file:2021-07-31-citations.org>
|
||||
|
||||
[citar] <https://github.com/bdarcus/citar>
|
||||
|
||||
|
||||
Asynchronous session evaluation
|
||||
═══════════════════════════════
|
||||
|
||||
Since being featured in [May’s post], we’ve had the initial python
|
||||
support expanded with support for R too. I have good reason to believe
|
||||
that more backends will join this list in the future.
|
||||
|
||||
To get started, just add `:async' to the header arguments of Python or
|
||||
R source blocks with a `:session'.
|
||||
|
||||
|
||||
[May’s post] <file:2021-05-31-async.org>
|
||||
|
||||
|
||||
LaTeX environment `#+results' are now removed
|
||||
═════════════════════════════════════════════
|
||||
|
||||
LaTeX environments (i.e. `\begin{} ... \end{}' blocks) have been added
|
||||
to the list of `#+results' types that will be removed. This is bigger
|
||||
news than one might think, as it means that raw LaTeX environments are
|
||||
now a viable output for org-babel backends. This possesses a distinct
|
||||
advantage over `:results latex' as LaTeX environments can be rendered
|
||||
inline with `org-latex-preview' and are exported to more formats — for
|
||||
example HTML with MathJax.
|
||||
|
||||
This is likely going to be first seen in the new `ob-julia' backend
|
||||
(unreleased, currently in early development), but could well be
|
||||
utilised by other backends such as `ob-octave', `ob-mathematica' (in
|
||||
contrib), `ob-python' (using `SymPy'), `ob-calc' and more.
|
||||
|
||||
<file:figures/ob-julia-latexify-rendered.png>
|
||||
|
||||
|
||||
More fontification
|
||||
══════════════════
|
||||
|
||||
A number of new faces have been introduced to allow for improved
|
||||
theming capability, and better contextual hints in the agenda, namely:
|
||||
`org-agenda-date-weekend-today', `org-imminent-deadline',
|
||||
`org-agenda-structure-secondary', and `org-agenda-structure-filter'.
|
||||
|
||||
Inline export snippets are now also fontified using the `org-tag' and
|
||||
`font-lock-comment-face' faces, to better stand out from surrounding
|
||||
text.
|
||||
|
||||
|
||||
More link formatting options with org-capture
|
||||
═════════════════════════════════════════════
|
||||
|
||||
A new formatting directive, `%L' has been introduced which provides
|
||||
the bare link target. This allows for links with automatically
|
||||
generated descriptions 🙂.
|
||||
|
||||
|
||||
Export improvements
|
||||
═══════════════════
|
||||
|
||||
The HTML and LaTeX backends have both been given some love in this
|
||||
release of Org.
|
||||
|
||||
The HTML backend now supports customisation of the `<meta>' tags
|
||||
included with `org-html-meta-tags', which should be particularly
|
||||
useful to anybody using `org-publish' for blogs or websites (in fact,
|
||||
this blog has been making use of it for some time now). A new variable
|
||||
has been introduced to help with styling, `org-html-content-class'
|
||||
(`"content"' by default) which is used as the CSS class for the
|
||||
top-level content wrapper. To further improve styling capabilities,
|
||||
`org-html-style-default' and `org-html-scripts' have been changed from
|
||||
constants to customisable variables.
|
||||
|
||||
The LaTeX backend (`ox-latex') no longer has obsolete LaTeX packages
|
||||
in `org-latex-default-packages-alist' (`grffile' and `texcomp' have
|
||||
been removed). It also now supports arbitrary `:float' argument
|
||||
values, and accepts a six new arguments (in total) for verse
|
||||
(`:lines', `:center', `:versewidth', and `:latexcode') and quote
|
||||
blocks (`:environment' and `:options').
|
||||
|
||||
|
||||
Project changes
|
||||
═══════════════
|
||||
|
||||
To reduce the maintainer burden, the `contrib/' folder and a
|
||||
collection of rarely-used or barely-maintained `ob-*' backends have
|
||||
been moved to a new repo, [org-contrib]. Support for Emacs 24
|
||||
(2012–2014) has also been dropped, and Org will now aim to support the
|
||||
three most recent major versions of Emacs.
|
||||
|
||||
|
||||
[org-contrib] <https://git.sr.ht/~bzg/org-contrib>
|
||||
|
|
@ -0,0 +1,501 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-12 Fri 13:39 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>November 2021</title>
|
||||
<meta name="author" content="TEC" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="November 2021" />
|
||||
<meta property="og:description" content="Elementary improvements" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="TEC" />
|
||||
<meta property="og:article:published_time" content="2021-11-30T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2021-12-02T03:51:15+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2021-11-30, <span class='acr'>TEC</span></div>
|
||||
|
||||
<h1 class="title">November 2021</h1>
|
||||
<p class="subtitle" role="doc-subtitle">Elementary improvements</p>
|
||||
</header><p>
|
||||
With a 9.5 release highlight post last month, and the month before skipped, it’s
|
||||
now <i>three months</i> since the last regular instalment of <span class='acr'>TMIO</span>. Let’s get back up
|
||||
to date on some of the latest happenings with Org.
|
||||
</p>
|
||||
<div id="outline-container-org-as-markup" class="outline-2">
|
||||
<h2 id="org-as-markup">Org as markup<a aria-hidden="true" href="#org-as-markup">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-org-as-markup">
|
||||
<p>
|
||||
Looking at the wider ecosystem, it certainly appears that there is a growing
|
||||
appetite for Org markup outside org-mode. More projects like <a href="https://gohugo.io/">Hugo</a> and <a href="https://logseq.com/">Logseq</a>
|
||||
seem to be interested in supporting Org markup, and there has been a recent
|
||||
growth in editor extensions like Neovim’s <a href="https://github.com/nvim-orgmode/orgmode/">orgmode.nvim</a> (started in March this
|
||||
year) and Sublime Text’s <a href="https://packagecontrol.io/packages/OrgExtended">OrgExtended</a> (started in June this year).
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Interest in Org as a general-usage markup format can also be seen within the Org
|
||||
project. Primarily lead by Nicolas Goaziou, there is an ongoing attempt to
|
||||
codify the Org syntax in a formal specification in the Worg document <a href="https://orgmode.org/worg/dev/org-syntax.html">Org Syntax
|
||||
(draft)</a>. Other members of the Org mailing list have directed their effort to
|
||||
creating non-elisp parsers for Org, both to help Org tools be created in other
|
||||
languages, and as put in the <span class='acr'>README</span> for Tom Gillespie’s <a href="https://github.com/tgbugs/laundry">laundry</a> parser
|
||||
</p>
|
||||
<blockquote>
|
||||
<p>
|
||||
The long term goal of this work is to provide a reference that can be used to
|
||||
standardize Org syntax and behavior and to specify various levels of compliance
|
||||
for an implementation of Org mode.
|
||||
</p>
|
||||
</blockquote>
|
||||
|
||||
<p>
|
||||
Earlier this week Karl Voit, the author of the rather well-known document <a href="https://karl-voit.at/2017/09/23/orgmode-as-markup-only/">Org
|
||||
Mode Is One of the Most Reasonable Markup Languages to Use for Text</a>, surprised
|
||||
the mailing list by announcing his independent creation of a multi-leveled
|
||||
standard for Org syntax subsets called “Orgdown” (the name is a blend of
|
||||
“Org-mode” and “markdown”, but the standard is only a subset of Org). Each level
|
||||
defines a compliance score given by a mix of parsing and editing support, with
|
||||
example compliance scores for the first (and currently only) level of the
|
||||
standard given for common tools.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
At this stage, it isn’t clear exactly how the Org-outside-Emacs landscape will
|
||||
evolve, but the swelling interest is very encouraging.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-an-org-parser" class="outline-2">
|
||||
<h2 id="an-org-parser">An Org parser in Julia<a aria-hidden="true" href="#an-org-parser">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-an-org-parser">
|
||||
<p>
|
||||
Speaking of parsers, I may be somewhat biased but I’m quite happy that a Org
|
||||
parser for <a href="https://julialang.org/">Julia</a> now exists 🎉.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<div class="link-preview"><a href="https://github.com/tecosaur/OrgMode.jl"><img src="https://repository-images.githubusercontent.com/431592282/7a91c403-ceeb-45b5-8a23-a86136dfb7e1"/><small>github.com</small><p><b>GitHub - tecosaur/Org.jl: A Julia library for working with Org.</b></br>A Julia library for working with Org. Contribute to tecosaur/Org.jl development by creating an account on GitHub.</p></a></div>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
OrgMode.jl is a parser, but also intended as a general-purpose Org library for
|
||||
Julia. It’s only been a week since development started, but it currently
|
||||
supports most of the <a href="https://orgmode.org/worg/dev/org-syntax.html">Org Syntax</a> draft specification, along with the rendering of
|
||||
a parsed Org <span class='acr'>AST</span> to a <span class='acr'>TTY</span> or back to Org text. A few utility functions are also
|
||||
included, such as <code>filtermap</code> which operates similarly to <code>org-element-map</code>.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-autoloading-citation-backends" class="outline-2">
|
||||
<h2 id="autoloading-citation-backends">Autoloading citation backends<a aria-hidden="true" href="#autoloading-citation-backends">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-autoloading-citation-backends">
|
||||
<p>
|
||||
One small but impactful change is autoloading of citation backends. Until
|
||||
recently before say using the <kbd>csl</kbd> backend, one needed to
|
||||
<code class="src src-elisp">(<span class="org-keyword">require</span> '<span class="org-constant">oc-csl</span>)</code> or face error messages.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Now, if you have a line like:
|
||||
</p>
|
||||
<details id='org3915936' class='code' open>
|
||||
<summary></summary>
|
||||
<div class='gutter'><a href='#org3915936'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<pre class="example" id="org3915936">
|
||||
#+cite_export: FORMAT ...
|
||||
</pre>
|
||||
|
||||
</details>
|
||||
<p>
|
||||
org-mode will try to load the file <kbd>oc-FORMAT</kbd> before trying to process citations.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
This should make getting started with citations in Org just a bit easier.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-nicer-tangle-mode" class="outline-2">
|
||||
<h2 id="nicer-tangle-mode">A nicer <kbd>:tangle-mode</kbd> syntax<a aria-hidden="true" href="#nicer-tangle-mode">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-nicer-tangle-mode">
|
||||
<p>
|
||||
The standard way of setting a <kbd>:tangle-mode</kbd> has typically been by providing a
|
||||
closure that makes use of Elisp’s octal syntax, such as <kbd>(identity #o755)</kbd>. This
|
||||
is unnecessarily verbose, and certainly doesn’t feel natural.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
With the addition of a small mode-interpreting function
|
||||
(<code>org-babel-interpret-file-mode</code>) It is now possible to specify <kbd>:tangle-mode</kbd> using
|
||||
three different forms of shorthand
|
||||
</p>
|
||||
<dl class="org-dl">
|
||||
<dt>octal</dt><dd><kbd>o755</kbd> is equivalent to <kbd>(identity #o755)</kbd></dd>
|
||||
<dt>chmod</dt><dd><code>chmod</code>-style inputs like <kbd>u+x</kbd> are now parsed to a file mode<sup><a id="fnr.1" class="footref" href="#fn.1" role="doc-backlink">1</a></sup> with the
|
||||
the base/default mode set by <code>org-babel-tangle-default-file-mode</code>.</dd>
|
||||
<dt>ls -l</dt><dd>strings of the form given by <code>ls -l</code> like <kbd>rwxr-xr-x</kbd> are also accepted</dd>
|
||||
</dl>
|
||||
|
||||
<p>
|
||||
This means the following forms are now all equivalent:
|
||||
</p>
|
||||
<details id='org248fb38' class='code' open>
|
||||
<summary></summary>
|
||||
<div class='gutter'><a href='#org248fb38'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<pre class="example" id="org248fb38">
|
||||
:tangle-mode (identity #o755)
|
||||
:tangle-mode o755
|
||||
:tangle-mode a=rx,u+w
|
||||
:tangle-mode rwxr-xr-x
|
||||
</pre>
|
||||
|
||||
</details>
|
||||
|
||||
<p>
|
||||
It has also been noted on the mailing list that the <kbd>:tangle-mode (identity
|
||||
#o755)</kbd> form works by being transformed to <kbd>:tangle-mode 493</kbd> during parsing.
|
||||
Similarly <kbd>:tangle-mode 755</kbd> is equivalent to <kbd>:tangle-mode (identity #o1363)</kbd>. For
|
||||
some values the decimal and octal interpretation are <i>both</i> valid file modes. Due
|
||||
to the clear potential for confusion, and since file permissions are an
|
||||
important security consideration, it has been suggested on the mailing list that
|
||||
these forms should be depreciated with a warning in future. No decision has been
|
||||
made yet though.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-113526722" class="outline-2">
|
||||
<h2 id="113526722">Org element parser cache<a aria-hidden="true" href="#113526722">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-113526722">
|
||||
<p>
|
||||
Ihor Radchenko has done some fantastic work over the past few months by
|
||||
overhauling parts of <kbd>org-element.el</kbd> to introduce extensive caching. <kbd>org-element</kbd>
|
||||
is <i>the</i> Org markup parser inside org-mode. This allows for a huge jump in speed,
|
||||
and also provides a few functions which fetch information without updating the
|
||||
cache — allowing for particularly speedy lookups with a small sacrifice to
|
||||
correctness guarantees on one or two properties in particular cases.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Several org-mode <span class='acr'>API</span><small>s</small> now make use of the cache to dramatically improve speed.
|
||||
Aside from improvements to typically slow operations, this is ideal for
|
||||
situations involving frequent buffer edits.
|
||||
It’s no understatement to say that this work is transformative.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
One potential beneficiary from this work is actually fontification. It has
|
||||
become increasingly apparent that the current regex-based method for buffer
|
||||
fontification is imperfect, and can actually differ from the true structure of
|
||||
the document as parsed (authoritatively) by <kbd>org-element</kbd>. This has lead to the
|
||||
well-received suggestion on the mailing list to rewrite the fontification code
|
||||
to be built on <kbd>org-element</kbd> instead.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-inline-source-block" class="outline-2">
|
||||
<h2 id="inline-source-block">Inline source block fontification<a aria-hidden="true" href="#inline-source-block">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-inline-source-block">
|
||||
<p>
|
||||
I think <a href="https://orgmode.org/manual/Structure-of-Code-Blocks.html">inline source code blocks</a> are an underappreciated feature of Org. I
|
||||
don’t think it’s helped that they have not been visually treated at all
|
||||
differently from plain text. Now though, they have a new dedicated face
|
||||
(<code>org-inline-src-block</code>) <i>and</i> in the same manner as source blocks, based on
|
||||
<code>org-src-fontify-natively</code> can be fontified using the language’s major mode.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="orgbac6797">
|
||||
<img src="figures/inline-src-block-fontified-vs-code.png" alt="inline-src-block-fontified-vs-code.png" class="doom-one">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 1: </span>Side-by-side comparison of a identical paragraphs using code (<code>~</code>) markup and inline source blocks (<code>src_</code>).</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
If you aren’t familiar with inline source blocks, you’re missing out. They are
|
||||
very much the inline cousin of source blocks, and so support all your favourite
|
||||
Babel features like code execution and header arguments. This provides a
|
||||
fantastic capacity to inline dynamically computed expressions, and optionally
|
||||
show the code that produces them.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org039e913">
|
||||
<img src="figures/inline-src-block-julia-demo.png" alt="inline-src-block-julia-demo.png" class="doom-one">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 2: </span>A paragraph making use of <i>evaluated</i> inline source blocks. Note that the <kbd>⟨11⟩</kbd> is a prettified results macro (using a potential future org-mode patch).</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-functions-as-default" class="outline-2">
|
||||
<h2 id="functions-as-default">Functions as default heading arguments<a aria-hidden="true" href="#functions-as-default">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-functions-as-default">
|
||||
<p>
|
||||
Matt Huszagh has contributed a patch that allows functions to be used as values
|
||||
for default header arguments. This is great for arguments where a sensible
|
||||
default can be provided by evaluating a function on-the-fly.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Consider for example the arguments required to produce a simple image using R
|
||||
with Babel:
|
||||
</p>
|
||||
<details id='functions-as-default,code--1' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#functions-as-default,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-block-begin-line">#+begin_src R :results graphics file :file myimage.svg</span>
|
||||
<span class="org-org-block">library(ggplot2)</span>
|
||||
<span class="org-org-block">ggplot(mpg, aes(displ, hwy, colour = class)) + geom_point()</span>
|
||||
<span class="org-org-block-end-line">#+end_src</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
In a Jupyter-style (<kbd>.ipynb</kbd>) or throwaway document, we likely don’t care about
|
||||
the file name at all. With these new capabilities, we can provide a file name
|
||||
dynamically as a default argument!
|
||||
</p>
|
||||
|
||||
<p>
|
||||
First we must write a function that when run at the source block will give us a
|
||||
suitable file name, like so
|
||||
</p>
|
||||
|
||||
<details id='functions-as-default,code--2' class='code' open><summary><span class="lang">Emacs Lisp</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#functions-as-default,code--2'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-emacs-lisp">(<span class="org-keyword">defun</span> <span class="org-function-name">my/org-src-sha-to-image</span> ()
|
||||
(concat <span class="org-string">"generated-"</span>
|
||||
(substring
|
||||
(sha1 (org-element-property <span class="org-builtin">:value</span> (org-element-at-point)))
|
||||
0 8)
|
||||
<span class="org-string">".svg"</span>))
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
Let’s also write a function to guess whether the source block produces a plot by
|
||||
checking if there’s a plot command on the last line.
|
||||
</p>
|
||||
|
||||
<details id='functions-as-default,code--3' class='code' open><summary><span class="lang">Emacs Lisp</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#functions-as-default,code--3'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-emacs-lisp">(<span class="org-keyword">defun</span> <span class="org-function-name">my/org-src-guess-results-type</span> ()
|
||||
(<span class="org-keyword">if</span> (string-match-p <span class="org-string">"^ *</span><span class="org-string"><span class="org-regexp-grouping-backslash">\\</span></span><span class="org-string"><span class="org-regexp-grouping-construct">(?:</span></span><span class="org-string">plot</span><span class="org-string"><span class="org-regexp-grouping-backslash">\\</span></span><span class="org-string"><span class="org-regexp-grouping-construct">|</span></span><span class="org-string">ggplot</span><span class="org-string"><span class="org-regexp-grouping-backslash">\\</span></span><span class="org-string"><span class="org-regexp-grouping-construct">)</span></span><span class="org-string">([</span><span class="org-string"><span class="org-negation-char">^</span></span><span class="org-string">\n]+\n?\\'"</span>
|
||||
(org-element-property <span class="org-builtin">:value</span> (org-element-at-point)))
|
||||
<span class="org-string">"graphics file"</span> <span class="org-string">"replace"</span>))
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
Then we can just use these function in place of a static value in the default
|
||||
header arguments variable — that’s all it takes.
|
||||
</p>
|
||||
|
||||
<details id='functions-as-default,code--4' class='code' open><summary><span class="lang">Emacs Lisp</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#functions-as-default,code--4'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-emacs-lisp">(<span class="org-keyword">setq</span> org-babel-default-header-args:R
|
||||
'((<span class="org-builtin">:results</span> . my/org-src-guess-results-type)
|
||||
(<span class="org-builtin">:file</span> . my/org-src-sha-to-image)))
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
This means for most cases we can now get away without any header arguments at all.
|
||||
</p>
|
||||
|
||||
<details id='functions-as-default,code--5' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#functions-as-default,code--5'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-block-begin-line">#+begin_src R</span>
|
||||
<span class="org-org-block">library(ggplot2)</span>
|
||||
<span class="org-org-block">ggplot(mpg, aes(displ, hwy, colour = class)) + geom_point()</span>
|
||||
<span class="org-org-block-end-line">#+end_src</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
It’s always lovely to see more ways of reducing boilerplate.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-proportional-image-widths" class="outline-2">
|
||||
<h2 id="proportional-image-widths">Proportional image widths<a aria-hidden="true" href="#proportional-image-widths">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-proportional-image-widths">
|
||||
<p>
|
||||
Previously, as long as <code>org-image-actual-width</code> was <code>nil</code> or a list of the form
|
||||
<code>(default-value)</code>, <kbd>org-mode</kbd> would display images according to a <kbd>:width</kbd> attribute
|
||||
(e.g. <kbd>#+attr_html: :width 400px</kbd>) by simply looking for the first <kbd>#+attr_</kbd>
|
||||
affiliated keyword and reading the numeric component of the <kbd>:width</kbd> as the number
|
||||
of pixels wide the image should be.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
This has now become somewhat fancier. The image-width determining logic has been
|
||||
extracted to a new function (<code>org-display-inline-image--width</code>) which will now
|
||||
extract floating-point values like <kbd>0.7</kbd> and interpret them as that portion of the
|
||||
accessible text width in the buffer.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="orgfb0a353">
|
||||
<img src="figures/proportional-image-width.png" alt="proportional-image-width.png" class="doom-one">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 3: </span>A containing with an image set to half of the accesible text width</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
This means that a width parameter like <kbd>#+attr_latex: :width 0.7\linewidth</kbd> the
|
||||
image will displayed as 70% of the buffer text width.
|
||||
This also supports percentage value, like <kbd>#+attr_html: :width 80%</kbd> by dividing
|
||||
the number before the <kbd>%</kbd> by 100 as a floating-point value.
|
||||
As always, if you don’t like the way display width is inferred here you can
|
||||
override it by putting a <kbd>#+attr_org: :width X</kbd> statement first.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Support for proportional image widths extends to the <code>(default-value)</code> form of
|
||||
<code>org-image-actual-width</code>, as now if you set it to say <code>(0.9)</code> which will cause
|
||||
images <i>without</i> any width specification to be displayed at 90% of the buffer text
|
||||
width.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
If you want to have some images displayed as their actual width you can use the
|
||||
new special width parameter <kbd>t</kbd> to set this on a per-image basis with <kbd>#+attr_org:
|
||||
:width t</kbd>. Now all you need to do is remember to put this first. Based on current
|
||||
discussions on the mailing list though, soon <kbd>#+attr_org</kbd> will be prioritised when
|
||||
determining display image width, no matter which order you put the attributes
|
||||
in. I do like having one less thing to remember 🙂.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-other-improvements" class="outline-2">
|
||||
<h2 id="other-improvements">Other improvements<a aria-hidden="true" href="#other-improvements">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-other-improvements">
|
||||
<ul class="org-ul">
|
||||
<li>Allow citations immediately following an item bullet <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>Allow citations immediately following a footnote definition <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Update some obsolete function references <span class="underline">Marco Wahl</span></li>
|
||||
<li><kbd>ob-gnuplot</kbd> is now maintained by Ihor Radchenko</li>
|
||||
<li>Improve makescript support for <kbd>ORGVERSION</kbd> in tag-less mirrors <span class="underline">Nicholas Vollmer</span></li>
|
||||
<li>New <kbd>ob-julia</kbd>, now maintained by Pedro Bruel</li>
|
||||
<li>Allow for no indentation, but preserving current indentation by setting
|
||||
<code>org-indent-indentation-per-level</code> to <code>0</code> <span class="underline">David Lukes</span></li>
|
||||
<li>Eliminate some byte-compile warnings <span class="underline">Nicholas Vollmer</span> <span class="underline">Bastien</span></li>
|
||||
<li>Support Greek smart quotes <span class="underline">Juan Manuel Macías</span></li>
|
||||
<li><kbd>org-mouse</kbd> support for intermediate-state checkboxes <span class="underline">Jim Porter</span></li>
|
||||
<li>Allow nested parenthesis in <code>org-compile-prefix-format</code> <kbd>%(sexp)</kbd> expressions <span class="underline">Ihor Radchenko</span></li>
|
||||
<li><kbd>oc-csl</kbd> / citeproc improvements <span class="underline">András Simonyi</span></li>
|
||||
<li>Move more unmaintained/overly niche <kbd>ob-*</kbd> files to the contrib repo, reducing
|
||||
the maintainer burden <span class="underline">Bastien</span></li>
|
||||
<li>Allow use of a function for <code>org-agenda-overriding-header</code> for dynamic headers
|
||||
<span class="underline">Christopher League</span></li>
|
||||
<li>Improve <kbd>org-protocol</kbd> <span class='acr'>URI</span> decoding <span class="underline">Max Nikulin</span></li>
|
||||
<li>Remove some obsolete LaTeX packages from the default packages list <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>Add support for text and year citation styles to <kbd>oc-csl</kbd> <span class="underline">András Simonyi</span></li>
|
||||
<li>Produce lower-case keywords in <kbd>ox-org</kbd> <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>Improve <kbd>ob-gnuplot</kbd> argument processing <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>A collection of <kbd>oc-*</kbd> improvements <span class="underline">Nicholas Goaziou</span></li>
|
||||
<li>Support bare author citations in <kbd>oc-csl</kbd> <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>Add <kbd>:options</kbd> LaTeX attribute to tables <span class="underline">Juan Manuel Macías</span></li>
|
||||
<li>Fix display error with <kbd>ob-plantuml</kbd> and html export <span class="underline">Su Lin</span></li>
|
||||
<li>More tests! <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>Documentation improvements! <span class="underline">Marco Wahl</span> <span class="underline">Stefan Kangas</span> <span class="underline">Daniel Fleischer</span> <span class="underline">Wiliam
|
||||
Denton</span> <span class="underline">Thomas Dye</span> <span class="underline">Bastien</span> <span class="underline">Bruce D’Arcus</span> <span class="underline">Kyle Meyer</span> <span class="underline">Nicolas Goaziou</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-bugfixes" class="outline-2">
|
||||
<h2 id="bugfixes">Bugfixes<a aria-hidden="true" href="#bugfixes">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-bugfixes">
|
||||
<ul class="org-ul">
|
||||
<li>Fix heading insertion in a case where point is before any heading <span class="underline">Marco Wahl</span></li>
|
||||
<li>Prevent stringp error when tangling Org from an org-src edit buffer <span class="underline">Mark Dawson</span></li>
|
||||
<li>Prevent <code>indent-tabs-mode</code> from messing with justification in <span class='acr'>ASCII</span> exports
|
||||
<span class="underline">Morgan Willcock</span></li>
|
||||
<li>Fix form of default Babel haskell header args <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>No more duplicated logbook entries for repeated tasks <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>A headline fontification edge case <span class="underline">Sébastien Miquel</span></li>
|
||||
<li>Refactor code that needed Emacs 28 <span class="underline">Kyle Meyer</span></li>
|
||||
<li>Make sure a terminating emphasis marker can’t be used as a beginning emphasis
|
||||
marker in fontification <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>Allow footnotes at footnote definition start <span class="underline">Nicholas Goaziou</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="footnotes">
|
||||
<h2 class="footnotes">Footnotes: </h2>
|
||||
<div id="text-footnotes">
|
||||
|
||||
<div class="footdef"><sup><a id="fn.1" class="footnum" href="#fnr.1" role="doc-backlink">1</a></sup> <div class="footpara" role="doc-footnote"><p class="footpara">
|
||||
This is performed easily thanks to <code>file-modes-symbolic-to-number</code>, which
|
||||
is used as the basis for both the <code>chmod</code> and <code>ls -l</code> shorthand interpretations.
|
||||
</p></div></div>
|
||||
|
||||
|
||||
</div>
|
||||
</div></div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,12 +1,11 @@
|
|||
# Created 2024-01-12 Fri 13:39
|
||||
#+title: November 2021
|
||||
#+subtitle: Elementary improvements
|
||||
#+author: TEC
|
||||
#+date: 2021-11-30
|
||||
|
||||
#+author: TEC
|
||||
#+subtitle: Elementary improvements
|
||||
With a 9.5 release highlight post last month, and the month before skipped, it's
|
||||
now /three months/ since the last regular instalment of TMIO. Let's get back up
|
||||
to date on some of the latest happenings with Org.
|
||||
|
||||
* Org as markup
|
||||
|
||||
Looking at the wider ecosystem, it certainly appears that there is a growing
|
||||
|
|
@ -38,20 +37,18 @@ standard given for common tools.
|
|||
|
||||
At this stage, it isn't clear exactly how the Org-outside-Emacs landscape will
|
||||
evolve, but the swelling interest is very encouraging.
|
||||
|
||||
* An Org parser in Julia
|
||||
|
||||
Speaking of parsers, I may be somewhat biased but I'm quite happy that a Org
|
||||
parser for [[https://julialang.org/][Julia]] now exists 🎉.
|
||||
|
||||
[[Https://github.com/tecosaur/OrgMode.jl]]
|
||||
//github.com/tecosaur/OrgMode.jl
|
||||
|
||||
OrgMode.jl is a parser, but also intended as a general-purpose Org library for
|
||||
Julia. It's only been a week since development started, but it currently
|
||||
supports most of the [[https://orgmode.org/worg/dev/org-syntax.html][Org Syntax]] draft specification, along with the rendering of
|
||||
a parsed Org AST to a TTY or back to Org text. A few utility functions are also
|
||||
included, such as ~filtermap~ which operates similarly to ~org-element-map~.
|
||||
|
||||
* Autoloading citation backends
|
||||
|
||||
One small but impactful change is autoloading of citation backends. Until
|
||||
|
|
@ -60,12 +57,11 @@ src_elisp{(require 'oc-csl)} or face error messages.
|
|||
|
||||
Now, if you have a line like:
|
||||
#+begin_example
|
||||
#+cite_export: FORMAT ...
|
||||
,#+cite_export: FORMAT ...
|
||||
#+end_example
|
||||
org-mode will try to load the file =oc-FORMAT= before trying to process citations.
|
||||
|
||||
This should make getting started with citations in Org just a bit easier.
|
||||
|
||||
* A nicer =:tangle-mode= syntax
|
||||
|
||||
The standard way of setting a =:tangle-mode= has typically been by providing a
|
||||
|
|
@ -75,17 +71,17 @@ is unnecessarily verbose, and certainly doesn't feel natural.
|
|||
With the addition of a small mode-interpreting function
|
||||
(~org-babel-interpret-file-mode~) It is now possible to specify =:tangle-mode= using
|
||||
three different forms of shorthand
|
||||
+ octal :: =o755= is equivalent to =(identity #o755)=
|
||||
+ chmod :: ~chmod~-style inputs like =u+x= are now parsed to a file mode[fn:1] with the
|
||||
the base/default mode set by ~org-babel-tangle-default-file-mode~.
|
||||
+ ls -l :: strings of the form given by ~ls -l~ like =rwxr-xr-x= are also accepted
|
||||
- octal :: =o755= is equivalent to =(identity #o755)=
|
||||
- chmod :: ~chmod~-style inputs like =u+x= are now parsed to a file mode[fn:1] with the
|
||||
the base/default mode set by ~org-babel-tangle-default-file-mode~.
|
||||
- ls -l :: strings of the form given by ~ls -l~ like =rwxr-xr-x= are also accepted
|
||||
|
||||
This means the following forms are now all equivalent:
|
||||
#+begin_example
|
||||
:tangle-mode (identity #o755)
|
||||
:tangle-mode o755
|
||||
:tangle-mode a=rx,u+w
|
||||
:tangle-mode rwxr-xr-x
|
||||
:tangle-mode (identity #o755)
|
||||
:tangle-mode o755
|
||||
:tangle-mode a=rx,u+w
|
||||
:tangle-mode rwxr-xr-x
|
||||
#+end_example
|
||||
|
||||
It has also been noted on the mailing list that the =:tangle-mode (identity
|
||||
|
|
@ -97,6 +93,8 @@ important security consideration, it has been suggested on the mailing list that
|
|||
these forms should be depreciated with a warning in future. No decision has been
|
||||
made yet though.
|
||||
|
||||
[fn:1] This is performed easily thanks to ~file-modes-symbolic-to-number~, which
|
||||
is used as the basis for both the ~chmod~ and ~ls -l~ shorthand interpretations.
|
||||
* Org element parser cache
|
||||
|
||||
Ihor Radchenko has done some fantastic work over the past few months by
|
||||
|
|
@ -117,7 +115,6 @@ fontification is imperfect, and can actually differ from the true structure of
|
|||
the document as parsed (authoritatively) by =org-element=. This has lead to the
|
||||
well-received suggestion on the mailing list to rewrite the fontification code
|
||||
to be built on =org-element= instead.
|
||||
|
||||
* Inline source block fontification
|
||||
|
||||
I think [[https://orgmode.org/manual/Structure-of-Code-Blocks.html][inline source code blocks]] are an underappreciated feature of Org. I
|
||||
|
|
@ -128,8 +125,7 @@ differently from plain text. Now though, they have a new dedicated face
|
|||
|
||||
#+caption: Side-by-side comparison of a identical paragraphs using code (~~~) markup
|
||||
#+caption: and inline source blocks (~src_~).
|
||||
#+attr_html: :class doom-one
|
||||
[[file:figures/inline-src-block-fontified-vs-code.png]]
|
||||
[[file:figures/inline-src-block-fontified-vs-code.png]]
|
||||
|
||||
If you aren't familiar with inline source blocks, you're missing out. They are
|
||||
very much the inline cousin of source blocks, and so support all your favourite
|
||||
|
|
@ -140,9 +136,7 @@ show the code that produces them.
|
|||
#+caption: A paragraph making use of /evaluated/ inline source blocks.
|
||||
#+caption: Note that the =⟨11⟩= is a prettified results macro (using a potential future
|
||||
#+caption: org-mode patch).
|
||||
#+attr_html: :class doom-one
|
||||
[[file:figures/inline-src-block-julia-demo.png]]
|
||||
|
||||
* Functions as default heading arguments
|
||||
|
||||
Matt Huszagh has contributed a patch that allows functions to be used as values
|
||||
|
|
@ -152,10 +146,10 @@ default can be provided by evaluating a function on-the-fly.
|
|||
Consider for example the arguments required to produce a simple image using R
|
||||
with Babel:
|
||||
#+begin_src org
|
||||
,#+begin_src R :results graphics file :file myimage.svg
|
||||
library(ggplot2)
|
||||
ggplot(mpg, aes(displ, hwy, colour = class)) + geom_point()
|
||||
,#+end_src
|
||||
,#+begin_src R :results graphics file :file myimage.svg
|
||||
library(ggplot2)
|
||||
ggplot(mpg, aes(displ, hwy, colour = class)) + geom_point()
|
||||
,#+end_src
|
||||
#+end_src
|
||||
|
||||
In a Jupyter-style (=.ipynb=) or throwaway document, we likely don't care about
|
||||
|
|
@ -166,44 +160,43 @@ First we must write a function that when run at the source block will give us a
|
|||
suitable file name, like so
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(defun my/org-src-sha-to-image ()
|
||||
(concat "generated-"
|
||||
(substring
|
||||
(sha1 (org-element-property :value (org-element-at-point)))
|
||||
0 8)
|
||||
".svg"))
|
||||
(defun my/org-src-sha-to-image ()
|
||||
(concat "generated-"
|
||||
(substring
|
||||
(sha1 (org-element-property :value (org-element-at-point)))
|
||||
0 8)
|
||||
".svg"))
|
||||
#+end_src
|
||||
|
||||
Let's also write a function to guess whether the source block produces a plot by
|
||||
checking if there's a plot command on the last line.
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(defun my/org-src-guess-results-type ()
|
||||
(if (string-match-p "^ *\\(?:plot\\|ggplot\\)([^\n]+\n?\\'"
|
||||
(org-element-property :value (org-element-at-point)))
|
||||
"graphics file" "replace"))
|
||||
(defun my/org-src-guess-results-type ()
|
||||
(if (string-match-p "^ *\\(?:plot\\|ggplot\\)([^\n]+\n?\\'"
|
||||
(org-element-property :value (org-element-at-point)))
|
||||
"graphics file" "replace"))
|
||||
#+end_src
|
||||
|
||||
Then we can just use these function in place of a static value in the default
|
||||
header arguments variable --- that's all it takes.
|
||||
|
||||
#+begin_src emacs-lisp
|
||||
(setq org-babel-default-header-args:R
|
||||
'((:results . my/org-src-guess-results-type)
|
||||
(:file . my/org-src-sha-to-image)))
|
||||
(setq org-babel-default-header-args:R
|
||||
'((:results . my/org-src-guess-results-type)
|
||||
(:file . my/org-src-sha-to-image)))
|
||||
#+end_src
|
||||
|
||||
This means for most cases we can now get away without any header arguments at all.
|
||||
|
||||
#+begin_src org
|
||||
,#+begin_src R
|
||||
library(ggplot2)
|
||||
ggplot(mpg, aes(displ, hwy, colour = class)) + geom_point()
|
||||
,#+end_src
|
||||
,#+begin_src R
|
||||
library(ggplot2)
|
||||
ggplot(mpg, aes(displ, hwy, colour = class)) + geom_point()
|
||||
,#+end_src
|
||||
#+end_src
|
||||
|
||||
It's always lovely to see more ways of reducing boilerplate.
|
||||
|
||||
* Proportional image widths
|
||||
|
||||
Previously, as long as ~org-image-actual-width~ was ~nil~ or a list of the form
|
||||
|
|
@ -218,7 +211,6 @@ extract floating-point values like =0.7= and interpret them as that portion of t
|
|||
accessible text width in the buffer.
|
||||
|
||||
#+caption: A containing with an image set to half of the accesible text width
|
||||
#+attr_html: :class doom-one
|
||||
[[file:figures/proportional-image-width.png]]
|
||||
|
||||
This means that a width parameter like =#+attr_latex: :width 0.7\linewidth= the
|
||||
|
|
@ -239,52 +231,45 @@ new special width parameter =t= to set this on a per-image basis with =#+attr_or
|
|||
discussions on the mailing list though, soon =#+attr_org= will be prioritised when
|
||||
determining display image width, no matter which order you put the attributes
|
||||
in. I do like having one less thing to remember 🙂.
|
||||
|
||||
* Other improvements
|
||||
+ Allow citations immediately following an item bullet _TEC_
|
||||
+ Allow citations immediately following a footnote definition _Nicolas Goaziou_
|
||||
+ Update some obsolete function references _Marco Wahl_
|
||||
+ =ob-gnuplot= is now maintained by Ihor Radchenko
|
||||
+ Improve makescript support for =ORGVERSION= in tag-less mirrors _Nicholas Vollmer_
|
||||
+ New =ob-julia=, now maintained by Pedro Bruel
|
||||
+ Allow for no indentation, but preserving current indentation by setting
|
||||
- Allow citations immediately following an item bullet _TEC_
|
||||
- Allow citations immediately following a footnote definition _Nicolas Goaziou_
|
||||
- Update some obsolete function references _Marco Wahl_
|
||||
- =ob-gnuplot= is now maintained by Ihor Radchenko
|
||||
- Improve makescript support for =ORGVERSION= in tag-less mirrors _Nicholas Vollmer_
|
||||
- New =ob-julia=, now maintained by Pedro Bruel
|
||||
- Allow for no indentation, but preserving current indentation by setting
|
||||
~org-indent-indentation-per-level~ to ~0~ _David Lukes_
|
||||
+ Eliminate some byte-compile warnings _Nicholas Vollmer_ _Bastien_
|
||||
+ Support Greek smart quotes _Juan Manuel Macías_
|
||||
+ =org-mouse= support for intermediate-state checkboxes _Jim Porter_
|
||||
+ Allow nested parenthesis in ~org-compile-prefix-format~ =%(sexp)= expressions _Ihor Radchenko_
|
||||
+ =oc-csl= / citeproc improvements _András Simonyi_
|
||||
+ Move more unmaintained/overly niche =ob-*= files to the contrib repo, reducing
|
||||
- Eliminate some byte-compile warnings _Nicholas Vollmer_ _Bastien_
|
||||
- Support Greek smart quotes _Juan Manuel Macías_
|
||||
- =org-mouse= support for intermediate-state checkboxes _Jim Porter_
|
||||
- Allow nested parenthesis in ~org-compile-prefix-format~ =%(sexp)= expressions _Ihor Radchenko_
|
||||
- =oc-csl= / citeproc improvements _András Simonyi_
|
||||
- Move more unmaintained/overly niche =ob-*= files to the contrib repo, reducing
|
||||
the maintainer burden _Bastien_
|
||||
+ Allow use of a function for ~org-agenda-overriding-header~ for dynamic headers
|
||||
- Allow use of a function for ~org-agenda-overriding-header~ for dynamic headers
|
||||
_Christopher League_
|
||||
+ Improve =org-protocol= URI decoding _Max Nikulin_
|
||||
+ Remove some obsolete LaTeX packages from the default packages list _TEC_
|
||||
+ Add support for text and year citation styles to =oc-csl= _András Simonyi_
|
||||
+ Produce lower-case keywords in =ox-org= _TEC_
|
||||
+ Improve =ob-gnuplot= argument processing _Ihor Radchenko_
|
||||
+ A collection of =oc-*= improvements _Nicholas Goaziou_
|
||||
+ Support bare author citations in =oc-csl= _TEC_
|
||||
+ Add =:options= LaTeX attribute to tables _Juan Manuel Macías_
|
||||
+ Fix display error with =ob-plantuml= and html export _Su Lin_
|
||||
+ More tests! _Ihor Radchenko_
|
||||
+ Documentation improvements! _Marco Wahl_ _Stefan Kangas_ _Daniel Fleischer_ _Wiliam
|
||||
- Improve =org-protocol= URI decoding _Max Nikulin_
|
||||
- Remove some obsolete LaTeX packages from the default packages list _TEC_
|
||||
- Add support for text and year citation styles to =oc-csl= _András Simonyi_
|
||||
- Produce lower-case keywords in =ox-org= _TEC_
|
||||
- Improve =ob-gnuplot= argument processing _Ihor Radchenko_
|
||||
- A collection of =oc-*= improvements _Nicholas Goaziou_
|
||||
- Support bare author citations in =oc-csl= _TEC_
|
||||
- Add =:options= LaTeX attribute to tables _Juan Manuel Macías_
|
||||
- Fix display error with =ob-plantuml= and html export _Su Lin_
|
||||
- More tests! _Ihor Radchenko_
|
||||
- Documentation improvements! _Marco Wahl_ _Stefan Kangas_ _Daniel Fleischer_ _Wiliam
|
||||
Denton_ _Thomas Dye_ _Bastien_ _Bruce D'Arcus_ _Kyle Meyer_ _Nicolas Goaziou_
|
||||
|
||||
* Bugfixes
|
||||
+ Fix heading insertion in a case where point is before any heading _Marco Wahl_
|
||||
+ Prevent stringp error when tangling Org from an org-src edit buffer _Mark Dawson_
|
||||
+ Prevent ~indent-tabs-mode~ from messing with justification in ASCII exports
|
||||
- Fix heading insertion in a case where point is before any heading _Marco Wahl_
|
||||
- Prevent stringp error when tangling Org from an org-src edit buffer _Mark Dawson_
|
||||
- Prevent ~indent-tabs-mode~ from messing with justification in ASCII exports
|
||||
_Morgan Willcock_
|
||||
+ Fix form of default Babel haskell header args _Ihor Radchenko_
|
||||
+ No more duplicated logbook entries for repeated tasks _Ihor Radchenko_
|
||||
+ A headline fontification edge case _Sébastien Miquel_
|
||||
+ Refactor code that needed Emacs 28 _Kyle Meyer_
|
||||
+ Make sure a terminating emphasis marker can't be used as a beginning emphasis
|
||||
- Fix form of default Babel haskell header args _Ihor Radchenko_
|
||||
- No more duplicated logbook entries for repeated tasks _Ihor Radchenko_
|
||||
- A headline fontification edge case _Sébastien Miquel_
|
||||
- Refactor code that needed Emacs 28 _Kyle Meyer_
|
||||
- Make sure a terminating emphasis marker can't be used as a beginning emphasis
|
||||
marker in fontification _Ihor Radchenko_
|
||||
+ Allow footnotes at footnote definition start _Nicholas Goaziou_
|
||||
|
||||
* Footnotes
|
||||
|
||||
[fn:1] This is performed easily thanks to ~file-modes-symbolic-to-number~, which
|
||||
is used as the basis for both the ~chmod~ and ~ls -l~ shorthand interpretations.
|
||||
- Allow footnotes at footnote definition start _Nicholas Goaziou_
|
||||
|
|
@ -0,0 +1,411 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>2021-11-30-element.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">November 2021
|
||||
</span><span style="color: #9e9e9e;">#+subtitle:</span> Elementary improvements
|
||||
<span style="color: #9e9e9e;">#+author:</span> TEC
|
||||
<span style="color: #9e9e9e;">#+date:</span> 2021-11-30
|
||||
|
||||
With a 9.5 release highlight post last month, and the month before skipped, it's
|
||||
now <span class="ef-i">/three months/</span> since the last regular instalment of TMIO. Let's get back up
|
||||
to date on some of the latest happenings with Org.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Org as markup</span>
|
||||
|
||||
Looking at the wider ecosystem, it certainly appears that there is a growing
|
||||
appetite for Org markup outside org-mode. More projects like <span style="color: #3b6ea8; font-weight: 700;">[[https://gohugo.io/][Hugo]]</span> and <span style="color: #3b6ea8; font-weight: 700;">[[https://logseq.com/][Logseq]]</span>
|
||||
seem to be interested in supporting Org markup, and there has been a recent
|
||||
growth in editor extensions like Neovim's <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/nvim-orgmode/orgmode/][orgmode.nvim]]</span> (started in March this
|
||||
year) and Sublime Text's <span style="color: #3b6ea8; font-weight: 700;">[[https://packagecontrol.io/packages/OrgExtended][OrgExtended]]</span> (started in June this year).
|
||||
|
||||
Interest in Org as a general-usage markup format can also be seen within the Org
|
||||
project. Primarily lead by Nicolas Goaziou, there is an ongoing attempt to
|
||||
codify the Org syntax in a formal specification in the Worg document <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/worg/dev/org-syntax.html][Org Syntax
|
||||
(draft)]]</span>. Other members of the Org mailing list have directed their effort to
|
||||
creating non-elisp parsers for Org, both to help Org tools be created in other
|
||||
languages, and as put in the README for Tom Gillespie's <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/tgbugs/laundry][laundry]]</span> parser
|
||||
<span class="ef-obb">#+begin_quote
|
||||
</span>The long term goal of this work is to provide a reference that can be used to
|
||||
standardize Org syntax and behavior and to specify various levels of compliance
|
||||
for an implementation of Org mode.
|
||||
<span class="ef-obe">#+end_quote
|
||||
</span>
|
||||
Earlier this week Karl Voit, the author of the rather well-known document <span style="color: #3b6ea8; font-weight: 700;">[[https://karl-voit.at/2017/09/23/orgmode-as-markup-only/][Org
|
||||
Mode Is One of the Most Reasonable Markup Languages to Use for Text]]</span>, surprised
|
||||
the mailing list by announcing his independent creation of a multi-leveled
|
||||
standard for Org syntax subsets called "Orgdown" (the name is a blend of
|
||||
"Org-mode" and "markdown", but the standard is only a subset of Org). Each level
|
||||
defines a compliance score given by a mix of parsing and editing support, with
|
||||
example compliance scores for the first (and currently only) level of the
|
||||
standard given for common tools.
|
||||
|
||||
At this stage, it isn't clear exactly how the Org-outside-Emacs landscape will
|
||||
evolve, but the swelling interest is very encouraging.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* An Org parser in Julia</span>
|
||||
|
||||
Speaking of parsers, I may be somewhat biased but I'm quite happy that a Org
|
||||
parser for <span style="color: #3b6ea8; font-weight: 700;">[[https://julialang.org/][Julia]]</span> now exists 🎉.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[Https://github.com/tecosaur/OrgMode.jl]]</span>
|
||||
|
||||
OrgMode.jl is a parser, but also intended as a general-purpose Org library for
|
||||
Julia. It's only been a week since development started, but it currently
|
||||
supports most of the <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/worg/dev/org-syntax.html][Org Syntax]]</span> draft specification, along with the rendering of
|
||||
a parsed Org AST to a TTY or back to Org text. A few utility functions are also
|
||||
included, such as <span style="color: #9e9e9e;">~filtermap~</span> which operates similarly to <span style="color: #9e9e9e;">~org-element-map~</span>.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Autoloading citation backends</span>
|
||||
|
||||
One small but impactful change is autoloading of citation backends. Until
|
||||
recently before say using the <span style="color: #9e9e9e;">=csl=</span> backend, one needed to
|
||||
<span style="color: #9e9e9e; background-color: #e0e0e0;">src_</span><span style="color: #b1b1b1; background-color: #e0e0e0;">elisp</span><span style="color: #9e9e9e; background-color: #e0e0e0;">{</span><span class="ef-ob">(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">require</span><span class="ef-ob"> '</span><span style="color: #97365b; background-color: #e0e0e0;">oc-csl</span><span class="ef-ob">)</span><span style="color: #9e9e9e; background-color: #e0e0e0;">}</span> or face error messages.
|
||||
|
||||
Now, if you have a line like:
|
||||
<span class="ef-obb">#+begin_example
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;">#+cite_export: FORMAT ...
|
||||
</span><span class="ef-obe">#+end_example
|
||||
</span>org-mode will try to load the file <span style="color: #9e9e9e;">=oc-FORMAT=</span> before trying to process citations.
|
||||
|
||||
This should make getting started with citations in Org just a bit easier.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* A nicer </span><span style="color: #9e9e9e; font-weight: nil; font-size: 1.25em">=:tangle-mode=</span><span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em"> syntax</span>
|
||||
|
||||
The standard way of setting a <span style="color: #9e9e9e;">=:tangle-mode=</span> has typically been by providing a
|
||||
closure that makes use of Elisp's octal syntax, such as <span style="color: #9e9e9e;">=(identity #o755)=</span>. This
|
||||
is unnecessarily verbose, and certainly doesn't feel natural.
|
||||
|
||||
With the addition of a small mode-interpreting function
|
||||
(<span style="color: #9e9e9e;">~org-babel-interpret-file-mode~</span>) It is now possible to specify <span style="color: #9e9e9e;">=:tangle-mode=</span> using
|
||||
three different forms of shorthand
|
||||
+ <span style="font-weight: 700;">octal ::</span> <span style="color: #9e9e9e;">=o755=</span> is equivalent to <span style="color: #9e9e9e;">=(identity #o755)=</span>
|
||||
+ <span style="font-weight: 700;">chmod ::</span> <span style="color: #9e9e9e;">~chmod~</span>-style inputs like <span style="color: #9e9e9e;">=u+x=</span> are now parsed to a file mode[fn:1] with the
|
||||
the base/default mode set by <span style="color: #9e9e9e;">~org-babel-tangle-default-file-mode~</span>.
|
||||
+ <span style="font-weight: 700;">ls -l ::</span> strings of the form given by <span style="color: #9e9e9e;">~ls -l~</span> like <span style="color: #9e9e9e;">=rwxr-xr-x=</span> are also accepted
|
||||
|
||||
This means the following forms are now all equivalent:
|
||||
<span class="ef-obb">#+begin_example
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;">:tangle-mode (identity #o755)
|
||||
:tangle-mode o755
|
||||
:tangle-mode a=rx,u+w
|
||||
:tangle-mode rwxr-xr-x
|
||||
</span><span class="ef-obe">#+end_example
|
||||
</span>
|
||||
It has also been noted on the mailing list that the <span style="color: #9e9e9e;">=:tangle-mode (identity
|
||||
#o755)=</span> form works by being transformed to <span style="color: #9e9e9e;">=:tangle-mode 493=</span> during parsing.
|
||||
Similarly <span style="color: #9e9e9e;">=:tangle-mode 755=</span> is equivalent to <span style="color: #9e9e9e;">=:tangle-mode (identity #o1363)=</span>. For
|
||||
some values the decimal and octal interpretation are <span class="ef-i">/both/</span> valid file modes. Due
|
||||
to the clear potential for confusion, and since file permissions are an
|
||||
important security consideration, it has been suggested on the mailing list that
|
||||
these forms should be depreciated with a warning in future. No decision has been
|
||||
made yet though.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Org element parser cache</span>
|
||||
|
||||
Ihor Radchenko has done some fantastic work over the past few months by
|
||||
overhauling parts of <span style="color: #9e9e9e;">=org-element.el=</span> to introduce extensive caching. <span style="color: #9e9e9e;">=org-element=</span>
|
||||
is <span class="ef-i">/the/</span> Org markup parser inside org-mode. This allows for a huge jump in speed,
|
||||
and also provides a few functions which fetch information without updating the
|
||||
cache --- allowing for particularly speedy lookups with a small sacrifice to
|
||||
correctness guarantees on one or two properties in particular cases.
|
||||
|
||||
Several org-mode APIs now make use of the cache to dramatically improve speed.
|
||||
Aside from improvements to typically slow operations, this is ideal for
|
||||
situations involving frequent buffer edits.
|
||||
It's no understatement to say that this work is transformative.
|
||||
|
||||
One potential beneficiary from this work is actually fontification. It has
|
||||
become increasingly apparent that the current regex-based method for buffer
|
||||
fontification is imperfect, and can actually differ from the true structure of
|
||||
the document as parsed (authoritatively) by <span style="color: #9e9e9e;">=org-element=</span>. This has lead to the
|
||||
well-received suggestion on the mailing list to rewrite the fontification code
|
||||
to be built on <span style="color: #9e9e9e;">=org-element=</span> instead.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Inline source block fontification</span>
|
||||
|
||||
I think <span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/manual/Structure-of-Code-Blocks.html][inline source code blocks]]</span> are an underappreciated feature of Org. I
|
||||
don't think it's helped that they have not been visually treated at all
|
||||
differently from plain text. Now though, they have a new dedicated face
|
||||
(<span style="color: #9e9e9e;">~org-inline-src-block~</span>) <span class="ef-i">/and/</span> in the same manner as source blocks, based on
|
||||
<span style="color: #9e9e9e;">~org-src-fontify-natively~</span> can be fontified using the language's major mode.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Side-by-side comparison of a identical paragraphs using code (~~~) markup</span>
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">and inline source blocks (~src_~).</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class doom-one</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/inline-src-block-fontified-vs-code.png]]</span>
|
||||
|
||||
If you aren't familiar with inline source blocks, you're missing out. They are
|
||||
very much the inline cousin of source blocks, and so support all your favourite
|
||||
Babel features like code execution and header arguments. This provides a
|
||||
fantastic capacity to inline dynamically computed expressions, and optionally
|
||||
show the code that produces them.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">A paragraph making use of /evaluated/ inline source blocks.</span>
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Note that the =⟨11⟩= is a prettified results macro (using a potential future</span>
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">org-mode patch).</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class doom-one</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/inline-src-block-julia-demo.png]]</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Functions as default heading arguments</span>
|
||||
|
||||
Matt Huszagh has contributed a patch that allows functions to be used as values
|
||||
for default header arguments. This is great for arguments where a sensible
|
||||
default can be provided by evaluating a function on-the-fly.
|
||||
|
||||
Consider for example the arguments required to produce a simple image using R
|
||||
with Babel:
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+begin_src R :results graphics file :file myimage.svg
|
||||
library(ggplot2)
|
||||
ggplot(mpg, aes(displ, hwy, colour = class)) + geom_point()
|
||||
,#+end_src
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
In a Jupyter-style (<span style="color: #9e9e9e;">=.ipynb=</span>) or throwaway document, we likely don't care about
|
||||
the file name at all. With these new capabilities, we can provide a file name
|
||||
dynamically as a default argument!
|
||||
|
||||
First we must write a function that when run at the source block will give us a
|
||||
suitable file name, like so
|
||||
|
||||
<span class="ef-obb">#+begin_src emacs-lisp
|
||||
</span><span class="ef-ob">(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">defun</span> <span style="color: #29838d; background-color: #e0e0e0;">my/org-src-sha-to-image</span><span class="ef-ob"> ()
|
||||
(concat </span><span style="color: #4f894c; background-color: #e0e0e0;">"generated-"</span><span class="ef-ob">
|
||||
(substring
|
||||
(sha1 (org-element-property </span><span style="color: #29838d; background-color: #e0e0e0;">:value</span><span class="ef-ob"> (org-element-at-point)))
|
||||
0 8)
|
||||
</span><span style="color: #4f894c; background-color: #e0e0e0;">".svg"</span><span class="ef-ob">))
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
Let's also write a function to guess whether the source block produces a plot by
|
||||
checking if there's a plot command on the last line.
|
||||
|
||||
<span class="ef-obb">#+begin_src emacs-lisp
|
||||
</span><span class="ef-ob">(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">defun</span> <span style="color: #29838d; background-color: #e0e0e0;">my/org-src-guess-results-type</span><span class="ef-ob"> ()
|
||||
(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">if</span><span class="ef-ob"> (string-match-p </span><span style="color: #4f894c; background-color: #e0e0e0;">"^ *</span><span style="color: #3b6ea8; background-color: #e0e0e0; font-weight: 700;">\\</span><span style="color: #3b6ea8; background-color: #e0e0e0; font-weight: 700;">(?:</span><span style="color: #4f894c; background-color: #e0e0e0;">plot</span><span style="color: #3b6ea8; background-color: #e0e0e0; font-weight: 700;">\\</span><span style="color: #3b6ea8; background-color: #e0e0e0; font-weight: 700;">|</span><span style="color: #4f894c; background-color: #e0e0e0;">ggplot</span><span style="color: #3b6ea8; background-color: #e0e0e0; font-weight: 700;">\\</span><span style="color: #3b6ea8; background-color: #e0e0e0; font-weight: 700;">)</span><span style="color: #4f894c; background-color: #e0e0e0;">([</span><span style="color: #3b6ea8; background-color: #e0e0e0; font-weight: 700;">^</span><span style="color: #4f894c; background-color: #e0e0e0;">\n]+\n?\\'"</span><span class="ef-ob">
|
||||
(org-element-property </span><span style="color: #29838d; background-color: #e0e0e0;">:value</span><span class="ef-ob"> (org-element-at-point)))
|
||||
</span><span style="color: #4f894c; background-color: #e0e0e0;">"graphics file"</span> <span style="color: #4f894c; background-color: #e0e0e0;">"replace"</span><span class="ef-ob">))
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
Then we can just use these function in place of a static value in the default
|
||||
header arguments variable --- that's all it takes.
|
||||
|
||||
<span class="ef-obb">#+begin_src emacs-lisp
|
||||
</span><span class="ef-ob">(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">setq</span><span class="ef-ob"> org-babel-default-header-args:R
|
||||
'((</span><span style="color: #29838d; background-color: #e0e0e0;">:results</span><span class="ef-ob"> . my/org-src-guess-results-type)
|
||||
(</span><span style="color: #29838d; background-color: #e0e0e0;">:file</span><span class="ef-ob"> . my/org-src-sha-to-image)))
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
This means for most cases we can now get away without any header arguments at all.
|
||||
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+begin_src R
|
||||
library(ggplot2)
|
||||
ggplot(mpg, aes(displ, hwy, colour = class)) + geom_point()
|
||||
,#+end_src
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
It's always lovely to see more ways of reducing boilerplate.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Proportional image widths</span>
|
||||
|
||||
Previously, as long as <span style="color: #9e9e9e;">~org-image-actual-width~</span> was <span style="color: #9e9e9e;">~nil~</span> or a list of the form
|
||||
<span style="color: #9e9e9e;">~(default-value)~</span>, <span style="color: #9e9e9e;">=org-mode=</span> would display images according to a <span style="color: #9e9e9e;">=:width=</span> attribute
|
||||
(e.g. <span style="color: #9e9e9e;">=#+attr_html: :width 400px=</span>) by simply looking for the first <span style="color: #9e9e9e;">=#+attr_=</span>
|
||||
affiliated keyword and reading the numeric component of the <span style="color: #9e9e9e;">=:width=</span> as the number
|
||||
of pixels wide the image should be.
|
||||
|
||||
This has now become somewhat fancier. The image-width determining logic has been
|
||||
extracted to a new function (<span style="color: #9e9e9e;">~org-display-inline-image--width~</span>) which will now
|
||||
extract floating-point values like <span style="color: #9e9e9e;">=0.7=</span> and interpret them as that portion of the
|
||||
accessible text width in the buffer.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">A containing with an image set to half of the accesible text width</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class doom-one</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/proportional-image-width.png]]</span>
|
||||
|
||||
This means that a width parameter like <span style="color: #9e9e9e;">=#+attr_latex: :width 0.7\linewidth=</span> the
|
||||
image will displayed as 70% of the buffer text width.
|
||||
This also supports percentage value, like <span style="color: #9e9e9e;">=#+attr_html: :width 80%=</span> by dividing
|
||||
the number before the <span style="color: #9e9e9e;">=%=</span> by 100 as a floating-point value.
|
||||
As always, if you don't like the way display width is inferred here you can
|
||||
override it by putting a <span style="color: #9e9e9e;">=#+attr_org: :width X=</span> statement first.
|
||||
|
||||
Support for proportional image widths extends to the <span style="color: #9e9e9e;">~(default-value)~</span> form of
|
||||
<span style="color: #9e9e9e;">~org-image-actual-width~</span>, as now if you set it to say <span style="color: #9e9e9e;">~(0.9)~</span> which will cause
|
||||
images <span class="ef-i">/without/</span> any width specification to be displayed at 90% of the buffer text
|
||||
width.
|
||||
|
||||
If you want to have some images displayed as their actual width you can use the
|
||||
new special width parameter <span style="color: #9e9e9e;">=t=</span> to set this on a per-image basis with <span style="color: #9e9e9e;">=#+attr_org:
|
||||
:width t=</span>. Now all you need to do is remember to put this first. Based on current
|
||||
discussions on the mailing list though, soon <span style="color: #9e9e9e;">=#+attr_org=</span> will be prioritised when
|
||||
determining display image width, no matter which order you put the attributes
|
||||
in. I do like having one less thing to remember 🙂.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Other improvements</span>
|
||||
+ Allow citations immediately following an item bullet _TEC_
|
||||
+ Allow citations immediately following a footnote definition _Nicolas Goaziou_
|
||||
+ Update some obsolete function references _Marco Wahl_
|
||||
+ <span style="color: #9e9e9e;">=ob-gnuplot=</span> is now maintained by Ihor Radchenko
|
||||
+ Improve makescript support for <span style="color: #9e9e9e;">=ORGVERSION=</span> in tag-less mirrors _Nicholas Vollmer_
|
||||
+ New <span style="color: #9e9e9e;">=ob-julia=</span>, now maintained by Pedro Bruel
|
||||
+ Allow for no indentation, but preserving current indentation by setting
|
||||
<span style="color: #9e9e9e;">~org-indent-indentation-per-level~</span> to <span style="color: #9e9e9e;">~0~</span> _David Lukes_
|
||||
+ Eliminate some byte-compile warnings _Nicholas Vollmer_ _Bastien_
|
||||
+ Support Greek smart quotes _Juan Manuel Macías_
|
||||
+ <span style="color: #9e9e9e;">=org-mouse=</span> support for intermediate-state checkboxes _Jim Porter_
|
||||
+ Allow nested parenthesis in <span style="color: #9e9e9e;">~org-compile-prefix-format~</span> <span style="color: #9e9e9e;">=%(sexp)=</span> expressions _Ihor Radchenko_
|
||||
+ <span style="color: #9e9e9e;">=oc-csl=</span> / citeproc improvements _András Simonyi_
|
||||
+ Move more unmaintained/overly niche <span style="color: #9e9e9e;">=ob-*=</span> files to the contrib repo, reducing
|
||||
the maintainer burden _Bastien_
|
||||
+ Allow use of a function for <span style="color: #9e9e9e;">~org-agenda-overriding-header~</span> for dynamic headers
|
||||
_Christopher League_
|
||||
+ Improve <span style="color: #9e9e9e;">=org-protocol=</span> URI decoding _Max Nikulin_
|
||||
+ Remove some obsolete LaTeX packages from the default packages list _TEC_
|
||||
+ Add support for text and year citation styles to <span style="color: #9e9e9e;">=oc-csl=</span> _András Simonyi_
|
||||
+ Produce lower-case keywords in <span style="color: #9e9e9e;">=ox-org=</span> _TEC_
|
||||
+ Improve <span style="color: #9e9e9e;">=ob-gnuplot=</span> argument processing _Ihor Radchenko_
|
||||
+ A collection of <span style="color: #9e9e9e;">=oc-*=</span> improvements _Nicholas Goaziou_
|
||||
+ Support bare author citations in <span style="color: #9e9e9e;">=oc-csl=</span> _TEC_
|
||||
+ Add <span style="color: #9e9e9e;">=:options=</span> LaTeX attribute to tables _Juan Manuel Macías_
|
||||
+ Fix display error with <span style="color: #9e9e9e;">=ob-plantuml=</span> and html export _Su Lin_
|
||||
+ More tests! _Ihor Radchenko_
|
||||
+ Documentation improvements! _Marco Wahl_ _Stefan Kangas_ _Daniel Fleischer_ _Wiliam
|
||||
Denton_ _Thomas Dye_ _Bastien_ _Bruce D'Arcus_ _Kyle Meyer_ _Nicolas Goaziou_
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Bugfixes</span>
|
||||
+ Fix heading insertion in a case where point is before any heading _Marco Wahl_
|
||||
+ Prevent stringp error when tangling Org from an org-src edit buffer _Mark Dawson_
|
||||
+ Prevent <span style="color: #9e9e9e;">~indent-tabs-mode~</span> from messing with justification in ASCII exports
|
||||
_Morgan Willcock_
|
||||
+ Fix form of default Babel haskell header args _Ihor Radchenko_
|
||||
+ No more duplicated logbook entries for repeated tasks _Ihor Radchenko_
|
||||
+ A headline fontification edge case _Sébastien Miquel_
|
||||
+ Refactor code that needed Emacs 28 _Kyle Meyer_
|
||||
+ Make sure a terminating emphasis marker can't be used as a beginning emphasis
|
||||
marker in fontification _Ihor Radchenko_
|
||||
+ Allow footnotes at footnote definition start _Nicholas Goaziou_
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Footnotes</span>
|
||||
|
||||
[fn:1] This is performed easily thanks to <span style="color: #9e9e9e;">~file-modes-symbolic-to-number~</span>, which
|
||||
is used as the basis for both the <span style="color: #9e9e9e;">~chmod~</span> and <span style="color: #9e9e9e;">~ls -l~</span> shorthand interpretations.
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,370 @@
|
|||
━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
NOVEMBER 2021
|
||||
Elementary improvements
|
||||
|
||||
TEC
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
|
||||
2021-11-30
|
||||
|
||||
|
||||
With a 9.5 release highlight post last month, and the month before
|
||||
skipped, it’s now /three months/ since the last regular instalment of
|
||||
TMIO. Let’s get back up to date on some of the latest happenings with
|
||||
Org.
|
||||
|
||||
|
||||
Org as markup
|
||||
═════════════
|
||||
|
||||
Looking at the wider ecosystem, it certainly appears that there is a
|
||||
growing appetite for Org markup outside org-mode. More projects like
|
||||
[Hugo] and [Logseq] seem to be interested in supporting Org markup,
|
||||
and there has been a recent growth in editor extensions like Neovim’s
|
||||
[orgmode.nvim] (started in March this year) and Sublime Text’s
|
||||
[OrgExtended] (started in June this year).
|
||||
|
||||
Interest in Org as a general-usage markup format can also be seen
|
||||
within the Org project. Primarily lead by Nicolas Goaziou, there is an
|
||||
ongoing attempt to codify the Org syntax in a formal specification in
|
||||
the Worg document [Org Syntax (draft)]. Other members of the Org
|
||||
mailing list have directed their effort to creating non-elisp parsers
|
||||
for Org, both to help Org tools be created in other languages, and as
|
||||
put in the README for Tom Gillespie’s [laundry] parser
|
||||
The long term goal of this work is to provide a reference
|
||||
that can be used to standardize Org syntax and behavior
|
||||
and to specify various levels of compliance for an
|
||||
implementation of Org mode.
|
||||
|
||||
Earlier this week Karl Voit, the author of the rather well-known
|
||||
document [Org Mode Is One of the Most Reasonable Markup Languages to
|
||||
Use for Text], surprised the mailing list by announcing his
|
||||
independent creation of a multi-leveled standard for Org syntax
|
||||
subsets called “Orgdown” (the name is a blend of “Org-mode” and
|
||||
“markdown”, but the standard is only a subset of Org). Each level
|
||||
defines a compliance score given by a mix of parsing and editing
|
||||
support, with example compliance scores for the first (and currently
|
||||
only) level of the standard given for common tools.
|
||||
|
||||
At this stage, it isn’t clear exactly how the Org-outside-Emacs
|
||||
landscape will evolve, but the swelling interest is very encouraging.
|
||||
|
||||
|
||||
[Hugo] <https://gohugo.io/>
|
||||
|
||||
[Logseq] <https://logseq.com/>
|
||||
|
||||
[orgmode.nvim] <https://github.com/nvim-orgmode/orgmode/>
|
||||
|
||||
[OrgExtended] <https://packagecontrol.io/packages/OrgExtended>
|
||||
|
||||
[Org Syntax (draft)] <https://orgmode.org/worg/dev/org-syntax.html>
|
||||
|
||||
[laundry] <https://github.com/tgbugs/laundry>
|
||||
|
||||
[Org Mode Is One of the Most Reasonable Markup Languages to Use for
|
||||
Text] <https://karl-voit.at/2017/09/23/orgmode-as-markup-only/>
|
||||
|
||||
|
||||
An Org parser in Julia
|
||||
══════════════════════
|
||||
|
||||
Speaking of parsers, I may be somewhat biased but I’m quite happy that
|
||||
a Org parser for [Julia] now exists 🎉.
|
||||
|
||||
//github.com/tecosaur/OrgMode.jl
|
||||
|
||||
OrgMode.jl is a parser, but also intended as a general-purpose Org
|
||||
library for Julia. It’s only been a week since development started,
|
||||
but it currently supports most of the [Org Syntax] draft
|
||||
specification, along with the rendering of a parsed Org AST to a TTY
|
||||
or back to Org text. A few utility functions are also included, such
|
||||
as `filtermap' which operates similarly to `org-element-map'.
|
||||
|
||||
|
||||
[Julia] <https://julialang.org/>
|
||||
|
||||
[Org Syntax] <https://orgmode.org/worg/dev/org-syntax.html>
|
||||
|
||||
|
||||
Autoloading citation backends
|
||||
═════════════════════════════
|
||||
|
||||
One small but impactful change is autoloading of citation
|
||||
backends. Until recently before say using the `csl' backend, one
|
||||
needed to `(require 'oc-csl)' or face error messages.
|
||||
|
||||
Now, if you have a line like:
|
||||
┌────
|
||||
│ #+cite_export: FORMAT ...
|
||||
└────
|
||||
org-mode will try to load the file `oc-FORMAT' before trying to
|
||||
process citations.
|
||||
|
||||
This should make getting started with citations in Org just a bit
|
||||
easier.
|
||||
|
||||
|
||||
A nicer `:tangle-mode' syntax
|
||||
═════════════════════════════
|
||||
|
||||
The standard way of setting a `:tangle-mode' has typically been by
|
||||
providing a closure that makes use of Elisp’s octal syntax, such as
|
||||
`(identity #o755)'. This is unnecessarily verbose, and certainly
|
||||
doesn’t feel natural.
|
||||
|
||||
With the addition of a small mode-interpreting function
|
||||
(`org-babel-interpret-file-mode') It is now possible to specify
|
||||
`:tangle-mode' using three different forms of shorthand
|
||||
octal
|
||||
`o755' is equivalent to `(identity #o755)'
|
||||
chmod
|
||||
`chmod'-style inputs like `u+x' are now parsed to a file mode[1]
|
||||
with the the base/default mode set by
|
||||
`org-babel-tangle-default-file-mode'.
|
||||
ls -l
|
||||
strings of the form given by `ls -l' like `rwxr-xr-x' are also
|
||||
accepted
|
||||
|
||||
This means the following forms are now all equivalent:
|
||||
┌────
|
||||
│ :tangle-mode (identity #o755)
|
||||
│ :tangle-mode o755
|
||||
│ :tangle-mode a=rx,u+w
|
||||
│ :tangle-mode rwxr-xr-x
|
||||
└────
|
||||
|
||||
It has also been noted on the mailing list that the `:tangle-mode
|
||||
(identity #o755)' form works by being transformed to `:tangle-mode
|
||||
493' during parsing. Similarly `:tangle-mode 755' is equivalent to
|
||||
`:tangle-mode (identity #o1363)'. For some values the decimal and
|
||||
octal interpretation are /both/ valid file modes. Due to the clear
|
||||
potential for confusion, and since file permissions are an important
|
||||
security consideration, it has been suggested on the mailing list that
|
||||
these forms should be depreciated with a warning in future. No
|
||||
decision has been made yet though.
|
||||
|
||||
|
||||
Org element parser cache
|
||||
════════════════════════
|
||||
|
||||
Ihor Radchenko has done some fantastic work over the past few months
|
||||
by overhauling parts of `org-element.el' to introduce extensive
|
||||
caching. `org-element' is /the/ Org markup parser inside
|
||||
org-mode. This allows for a huge jump in speed, and also provides a
|
||||
few functions which fetch information without updating the cache —
|
||||
allowing for particularly speedy lookups with a small sacrifice to
|
||||
correctness guarantees on one or two properties in particular cases.
|
||||
|
||||
Several org-mode APIs now make use of the cache to dramatically
|
||||
improve speed. Aside from improvements to typically slow operations,
|
||||
this is ideal for situations involving frequent buffer edits. It’s no
|
||||
understatement to say that this work is transformative.
|
||||
|
||||
One potential beneficiary from this work is actually fontification. It
|
||||
has become increasingly apparent that the current regex-based method
|
||||
for buffer fontification is imperfect, and can actually differ from
|
||||
the true structure of the document as parsed (authoritatively) by
|
||||
`org-element'. This has lead to the well-received suggestion on the
|
||||
mailing list to rewrite the fontification code to be built on
|
||||
`org-element' instead.
|
||||
|
||||
|
||||
Inline source block fontification
|
||||
═════════════════════════════════
|
||||
|
||||
I think [inline source code blocks] are an underappreciated feature of
|
||||
Org. I don’t think it’s helped that they have not been visually
|
||||
treated at all differently from plain text. Now though, they have a
|
||||
new dedicated face (`org-inline-src-block') /and/ in the same manner
|
||||
as source blocks, based on `org-src-fontify-natively' can be fontified
|
||||
using the language’s major mode.
|
||||
|
||||
<file:figures/inline-src-block-fontified-vs-code.png>
|
||||
|
||||
If you aren’t familiar with inline source blocks, you’re missing
|
||||
out. They are very much the inline cousin of source blocks, and so
|
||||
support all your favourite Babel features like code execution and
|
||||
header arguments. This provides a fantastic capacity to inline
|
||||
dynamically computed expressions, and optionally show the code that
|
||||
produces them.
|
||||
|
||||
<file:figures/inline-src-block-julia-demo.png>
|
||||
|
||||
|
||||
[inline source code blocks]
|
||||
<https://orgmode.org/manual/Structure-of-Code-Blocks.html>
|
||||
|
||||
|
||||
Functions as default heading arguments
|
||||
══════════════════════════════════════
|
||||
|
||||
Matt Huszagh has contributed a patch that allows functions to be used
|
||||
as values for default header arguments. This is great for arguments
|
||||
where a sensible default can be provided by evaluating a function
|
||||
on-the-fly.
|
||||
|
||||
Consider for example the arguments required to produce a simple image
|
||||
using R with Babel:
|
||||
┌────
|
||||
│ #+begin_src R :results graphics file :file myimage.svg
|
||||
│ library(ggplot2)
|
||||
│ ggplot(mpg, aes(displ, hwy, colour = class)) + geom_point()
|
||||
│ #+end_src
|
||||
└────
|
||||
|
||||
In a Jupyter-style (`.ipynb') or throwaway document, we likely don’t
|
||||
care about the file name at all. With these new capabilities, we can
|
||||
provide a file name dynamically as a default argument!
|
||||
|
||||
First we must write a function that when run at the source block will
|
||||
give us a suitable file name, like so
|
||||
|
||||
┌────
|
||||
│ (defun my/org-src-sha-to-image ()
|
||||
│ (concat "generated-"
|
||||
│ (substring
|
||||
│ (sha1 (org-element-property :value (org-element-at-point)))
|
||||
│ 0 8)
|
||||
│ ".svg"))
|
||||
└────
|
||||
|
||||
Let’s also write a function to guess whether the source block produces
|
||||
a plot by checking if there’s a plot command on the last line.
|
||||
|
||||
┌────
|
||||
│ (defun my/org-src-guess-results-type ()
|
||||
│ (if (string-match-p "^ *\\(?:plot\\|ggplot\\)([^\n]+\n?\\'"
|
||||
│ (org-element-property :value (org-element-at-point)))
|
||||
│ "graphics file" "replace"))
|
||||
└────
|
||||
|
||||
Then we can just use these function in place of a static value in the
|
||||
default header arguments variable — that’s all it takes.
|
||||
|
||||
┌────
|
||||
│ (setq org-babel-default-header-args:R
|
||||
│ '((:results . my/org-src-guess-results-type)
|
||||
│ (:file . my/org-src-sha-to-image)))
|
||||
└────
|
||||
|
||||
This means for most cases we can now get away without any header
|
||||
arguments at all.
|
||||
|
||||
┌────
|
||||
│ #+begin_src R
|
||||
│ library(ggplot2)
|
||||
│ ggplot(mpg, aes(displ, hwy, colour = class)) + geom_point()
|
||||
│ #+end_src
|
||||
└────
|
||||
|
||||
It’s always lovely to see more ways of reducing boilerplate.
|
||||
|
||||
|
||||
Proportional image widths
|
||||
═════════════════════════
|
||||
|
||||
Previously, as long as `org-image-actual-width' was `nil' or a list of
|
||||
the form `(default-value)', `org-mode' would display images according
|
||||
to a `:width' attribute (e.g. `#+attr_html: :width 400px') by simply
|
||||
looking for the first `#+attr_' affiliated keyword and reading the
|
||||
numeric component of the `:width' as the number of pixels wide the
|
||||
image should be.
|
||||
|
||||
This has now become somewhat fancier. The image-width determining
|
||||
logic has been extracted to a new function
|
||||
(`org-display-inline-image--width') which will now extract
|
||||
floating-point values like `0.7' and interpret them as that portion of
|
||||
the accessible text width in the buffer.
|
||||
|
||||
<file:figures/proportional-image-width.png>
|
||||
|
||||
This means that a width parameter like `#+attr_latex: :width
|
||||
0.7\linewidth' the image will displayed as 70% of the buffer text
|
||||
width. This also supports percentage value, like `#+attr_html: :width
|
||||
80%' by dividing the number before the `%' by 100 as a floating-point
|
||||
value. As always, if you don’t like the way display width is inferred
|
||||
here you can override it by putting a `#+attr_org: :width X' statement
|
||||
first.
|
||||
|
||||
Support for proportional image widths extends to the `(default-value)'
|
||||
form of `org-image-actual-width', as now if you set it to say `(0.9)'
|
||||
which will cause images /without/ any width specification to be
|
||||
displayed at 90% of the buffer text width.
|
||||
|
||||
If you want to have some images displayed as their actual width you
|
||||
can use the new special width parameter `t' to set this on a per-image
|
||||
basis with `#+attr_org: :width t'. Now all you need to do is remember
|
||||
to put this first. Based on current discussions on the mailing list
|
||||
though, soon `#+attr_org' will be prioritised when determining display
|
||||
image width, no matter which order you put the attributes in. I do
|
||||
like having one less thing to remember 🙂.
|
||||
|
||||
|
||||
Other improvements
|
||||
══════════════════
|
||||
|
||||
⁃ Allow citations immediately following an item bullet _TEC_
|
||||
⁃ Allow citations immediately following a footnote definition _Nicolas
|
||||
Goaziou_
|
||||
⁃ Update some obsolete function references _Marco Wahl_
|
||||
⁃ `ob-gnuplot' is now maintained by Ihor Radchenko
|
||||
⁃ Improve makescript support for `ORGVERSION' in tag-less mirrors
|
||||
_Nicholas Vollmer_
|
||||
⁃ New `ob-julia', now maintained by Pedro Bruel
|
||||
⁃ Allow for no indentation, but preserving current indentation by
|
||||
setting `org-indent-indentation-per-level' to `0' _David Lukes_
|
||||
⁃ Eliminate some byte-compile warnings _Nicholas Vollmer_ _Bastien_
|
||||
⁃ Support Greek smart quotes _Juan Manuel Macías_
|
||||
⁃ `org-mouse' support for intermediate-state checkboxes _Jim Porter_
|
||||
⁃ Allow nested parenthesis in `org-compile-prefix-format' `%(sexp)'
|
||||
expressions _Ihor Radchenko_
|
||||
⁃ `oc-csl' / citeproc improvements _András Simonyi_
|
||||
⁃ Move more unmaintained/overly niche `ob-*' files to the contrib
|
||||
repo, reducing the maintainer burden _Bastien_
|
||||
⁃ Allow use of a function for `org-agenda-overriding-header' for
|
||||
dynamic headers _Christopher League_
|
||||
⁃ Improve `org-protocol' URI decoding _Max Nikulin_
|
||||
⁃ Remove some obsolete LaTeX packages from the default packages list
|
||||
_TEC_
|
||||
⁃ Add support for text and year citation styles to `oc-csl' _András
|
||||
Simonyi_
|
||||
⁃ Produce lower-case keywords in `ox-org' _TEC_
|
||||
⁃ Improve `ob-gnuplot' argument processing _Ihor Radchenko_
|
||||
⁃ A collection of `oc-*' improvements _Nicholas Goaziou_
|
||||
⁃ Support bare author citations in `oc-csl' _TEC_
|
||||
⁃ Add `:options' LaTeX attribute to tables _Juan Manuel Macías_
|
||||
⁃ Fix display error with `ob-plantuml' and html export _Su Lin_
|
||||
⁃ More tests! _Ihor Radchenko_
|
||||
⁃ Documentation improvements! _Marco Wahl_ _Stefan Kangas_ _Daniel
|
||||
Fleischer_ _Wiliam Denton_ _Thomas Dye_ _Bastien_ _Bruce D’Arcus_
|
||||
_Kyle Meyer_ _Nicolas Goaziou_
|
||||
|
||||
|
||||
Bugfixes
|
||||
════════
|
||||
|
||||
⁃ Fix heading insertion in a case where point is before any heading
|
||||
_Marco Wahl_
|
||||
⁃ Prevent stringp error when tangling Org from an org-src edit buffer
|
||||
_Mark Dawson_
|
||||
⁃ Prevent `indent-tabs-mode' from messing with justification in ASCII
|
||||
exports _Morgan Willcock_
|
||||
⁃ Fix form of default Babel haskell header args _Ihor Radchenko_
|
||||
⁃ No more duplicated logbook entries for repeated tasks _Ihor
|
||||
Radchenko_
|
||||
⁃ A headline fontification edge case _Sébastien Miquel_
|
||||
⁃ Refactor code that needed Emacs 28 _Kyle Meyer_
|
||||
⁃ Make sure a terminating emphasis marker can’t be used as a beginning
|
||||
emphasis marker in fontification _Ihor Radchenko_
|
||||
⁃ Allow footnotes at footnote definition start _Nicholas Goaziou_
|
||||
|
||||
|
||||
|
||||
Footnotes
|
||||
─────────
|
||||
|
||||
[1] This is performed easily thanks to
|
||||
`file-modes-symbolic-to-number', which is used as the basis for both
|
||||
the `chmod' and `ls -l' shorthand interpretations.
|
||||
|
|
@ -0,0 +1,145 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-12 Fri 13:39 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>December 2021</title>
|
||||
<meta name="author" content="TEC" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="December 2021" />
|
||||
<meta property="og:description" content="Looking back on my first year of blogging" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="TEC" />
|
||||
<meta property="og:article:published_time" content="2021-12-31T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2022-01-02T03:27:20+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2021-12-31, <span class='acr'>TEC</span></div>
|
||||
|
||||
<h1 class="title">December 2021</h1>
|
||||
<p class="subtitle" role="doc-subtitle">Looking back on my first year of blogging</p>
|
||||
</header><p>
|
||||
Just over eight months ago, I kicked off <i>This Month in Org</i> with an emphatic
|
||||
announcement of the blog’s in the form of a <a href="2021-04-26-Welcome.html">Welcome</a> post. If you haven’t
|
||||
guessed, this is the first “blog post” I’ve ever written. In that <i>welcome</i> post,
|
||||
I gave my motivation for starting the blog — essentially to bridge a perceived
|
||||
gap in information sources between a subscription to the Org project mailing
|
||||
list, and nothing.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
That is why I thought this blog should exist, but until now I have neglected to
|
||||
mention what <i>I</i> want to accomplish with it. By starting <i>TMiO</i> I hoped to:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li>Engage more people with the improvements being made to Org<sup><a id="fnr.1" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>.</li>
|
||||
<li>Highlight some of the great work being done by Org<sup><a id="fnr.1.100" class="footref" href="#fn.1" role="doc-backlink">1</a></sup> contributors.</li>
|
||||
<li>Encourage more people to consider contributing to Org<sup><a id="fnr.1.100" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>.</li>
|
||||
<li>Foster a stronger sense of an Org<sup><a id="fnr.1.100" class="footref" href="#fn.1" role="doc-backlink">1</a></sup> community, outside the mailing list.</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
Since then, I’ve effused about Org to the tune of around ten thousand words. We
|
||||
started off with a fairly dry recount recent changes, which (after initial
|
||||
feedback) has shifted slightly to try to give more context on the improvements
|
||||
and how they may be used. In June I even went as far as to make the majority of
|
||||
the post about pre-existing features (writing Org for LaTeX).
|
||||
This change has been made to:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li>Try to make the blog posts a little more interesting, and less tedious.</li>
|
||||
<li>Potentially introduce readers to nice features of Org they weren’t aware of before.</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
We have now arrived at the first crucial question of this post: <i>How effective
|
||||
has this blog been in achieving its goals?</i>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Let’s start off by looking at engagement. There is no tracking on this site, and
|
||||
I’m not even counting page views. We could read into Reddit upvotes (which
|
||||
usually hover around 100-ish per post), but with no strong trend I’m wary of
|
||||
reading too much into those numbers. What about engendering an interest in
|
||||
contributing? This is even harder to consider. It is similarly difficult to
|
||||
judge whether this blog might be helping (even if only a bit) foster a stronger
|
||||
sense of community.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Ok, how about the second crucial question: <i>Moving forwards, what changes should
|
||||
I make to the style of posts, if any?</i>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Hmmm, this is a prickly one too. Both of these questions suffer from the same
|
||||
problem — <i>I</i> can’t answer them. Simply put, I need to hear from <i>you</i>. Whether it
|
||||
be in the Reddit comments section, or by Email (<kbd>tec@</kbd> this domain), to direct
|
||||
2022’s posts I am <i>very</i> interested in hearing your thoughts on:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li>How engaging you’ve found this blog? (the content, the style of writing, etc.)</li>
|
||||
<li>Whether this blog has influenced your feelings on the Org project and/or community?</li>
|
||||
<li>Whether this blog has affected your thoughts on contributing to Org?</li>
|
||||
<li>What you think this blog has done well/badly over the past year?</li>
|
||||
<li>If there’s anything you’d be interested in this blog doing differently in 2022?</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
That’s all for now! Thank you for reading, and have a great new year 🙂
|
||||
</p>
|
||||
<div id="footnotes">
|
||||
<h2 class="footnotes">Footnotes: </h2>
|
||||
<div id="text-footnotes">
|
||||
|
||||
<div class="footdef"><sup><a id="fn.1" class="footnum" href="#fnr.1" role="doc-backlink">1</a></sup> <div class="footpara" role="doc-footnote"><p class="footpara">
|
||||
Both the org-mode codebase, and also the ecosystem that’s sprung up
|
||||
around it
|
||||
</p></div></div>
|
||||
|
||||
|
||||
</div>
|
||||
</div></div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
# Created 2024-01-12 Fri 13:39
|
||||
#+title: December 2021
|
||||
#+subtitle: Looking back on my first year of blogging
|
||||
#+author: TEC
|
||||
#+date: 2021-12-31
|
||||
|
||||
#+author: TEC
|
||||
#+subtitle: Looking back on my first year of blogging
|
||||
Just over eight months ago, I kicked off /This Month in Org/ with an emphatic
|
||||
announcement of the blog's in the form of a [[file:2021-04-26-Welcome.org][Welcome]] post. If you haven't
|
||||
guessed, this is the first "blog post" I've ever written. In that /welcome/ post,
|
||||
|
|
@ -12,10 +12,10 @@ list, and nothing.
|
|||
|
||||
That is why I thought this blog should exist, but until now I have neglected to
|
||||
mention what /I/ want to accomplish with it. By starting /TMiO/ I hoped to:
|
||||
+ Engage more people with the improvements being made to Org[fn:1].
|
||||
+ Highlight some of the great work being done by Org[fn:1] contributors.
|
||||
+ Encourage more people to consider contributing to Org[fn:1].
|
||||
+ Foster a stronger sense of an Org[fn:1] community, outside the mailing list.
|
||||
- Engage more people with the improvements being made to Org[fn:1].
|
||||
- Highlight some of the great work being done by Org[fn:1] contributors.
|
||||
- Encourage more people to consider contributing to Org[fn:1].
|
||||
- Foster a stronger sense of an Org[fn:1] community, outside the mailing list.
|
||||
|
||||
Since then, I've effused about Org to the tune of around ten thousand words. We
|
||||
started off with a fairly dry recount recent changes, which (after initial
|
||||
|
|
@ -23,8 +23,8 @@ feedback) has shifted slightly to try to give more context on the improvements
|
|||
and how they may be used. In June I even went as far as to make the majority of
|
||||
the post about pre-existing features (writing Org for LaTeX).
|
||||
This change has been made to:
|
||||
+ Try to make the blog posts a little more interesting, and less tedious.
|
||||
+ Potentially introduce readers to nice features of Org they weren't aware of before.
|
||||
- Try to make the blog posts a little more interesting, and less tedious.
|
||||
- Potentially introduce readers to nice features of Org they weren't aware of before.
|
||||
|
||||
We have now arrived at the first crucial question of this post: /How effective
|
||||
has this blog been in achieving its goals?/
|
||||
|
|
@ -44,15 +44,10 @@ Hmmm, this is a prickly one too. Both of these questions suffer from the same
|
|||
problem --- /I/ can't answer them. Simply put, I need to hear from /you/. Whether it
|
||||
be in the Reddit comments section, or by Email (=tec@= this domain), to direct
|
||||
2022's posts I am /very/ interested in hearing your thoughts on:
|
||||
+ How engaging you've found this blog? (the content, the style of writing, etc.)
|
||||
+ Whether this blog has influenced your feelings on the Org project and/or community?
|
||||
+ Whether this blog has affected your thoughts on contributing to Org?
|
||||
+ What you think this blog has done well/badly over the past year?
|
||||
+ If there's anything you'd be interested in this blog doing differently in 2022?
|
||||
- How engaging you've found this blog? (the content, the style of writing, etc.)
|
||||
- Whether this blog has influenced your feelings on the Org project and/or community?
|
||||
- Whether this blog has affected your thoughts on contributing to Org?
|
||||
- What you think this blog has done well/badly over the past year?
|
||||
- If there's anything you'd be interested in this blog doing differently in 2022?
|
||||
|
||||
That's all for now! Thank you for reading, and have a great new year 🙂
|
||||
|
||||
* Footnotes
|
||||
|
||||
[fn:1] Both the org-mode codebase, and also the ecosystem that's sprung up
|
||||
around it
|
||||
|
|
@ -0,0 +1,179 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>2021-12-31-retrospection.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">December 2021
|
||||
</span><span style="color: #9e9e9e;">#+subtitle:</span> Looking back on my first year of blogging
|
||||
<span style="color: #9e9e9e;">#+author:</span> TEC
|
||||
<span style="color: #9e9e9e;">#+date:</span> 2021-12-31
|
||||
|
||||
Just over eight months ago, I kicked off <span class="ef-i">/This Month in Org/</span> with an emphatic
|
||||
announcement of the blog's in the form of a <span style="color: #3b6ea8; font-weight: 700;">[[file:2021-04-26-Welcome.org][Welcome]]</span> post. If you haven't
|
||||
guessed, this is the first "blog post" I've ever written. In that <span class="ef-i">/welcome/</span> post,
|
||||
I gave my motivation for starting the blog --- essentially to bridge a perceived
|
||||
gap in information sources between a subscription to the Org project mailing
|
||||
list, and nothing.
|
||||
|
||||
That is why I thought this blog should exist, but until now I have neglected to
|
||||
mention what <span class="ef-i">/I/</span> want to accomplish with it. By starting <span class="ef-i">/TMiO/</span> I hoped to:
|
||||
+ Engage more people with the improvements being made to Org[fn:1].
|
||||
+ Highlight some of the great work being done by Org[fn:1] contributors.
|
||||
+ Encourage more people to consider contributing to Org[fn:1].
|
||||
+ Foster a stronger sense of an Org[fn:1] community, outside the mailing list.
|
||||
|
||||
Since then, I've effused about Org to the tune of around ten thousand words. We
|
||||
started off with a fairly dry recount recent changes, which (after initial
|
||||
feedback) has shifted slightly to try to give more context on the improvements
|
||||
and how they may be used. In June I even went as far as to make the majority of
|
||||
the post about pre-existing features (writing Org for LaTeX).
|
||||
This change has been made to:
|
||||
+ Try to make the blog posts a little more interesting, and less tedious.
|
||||
+ Potentially introduce readers to nice features of Org they weren't aware of before.
|
||||
|
||||
We have now arrived at the first crucial question of this post: <span class="ef-i">/How effective
|
||||
has this blog been in achieving its goals?/</span>
|
||||
|
||||
Let's start off by looking at engagement. There is no tracking on this site, and
|
||||
I'm not even counting page views. We could read into Reddit upvotes (which
|
||||
usually hover around 100-ish per post), but with no strong trend I'm wary of
|
||||
reading too much into those numbers. What about engendering an interest in
|
||||
contributing? This is even harder to consider. It is similarly difficult to
|
||||
judge whether this blog might be helping (even if only a bit) foster a stronger
|
||||
sense of community.
|
||||
|
||||
Ok, how about the second crucial question: <span class="ef-i">/Moving forwards, what changes should
|
||||
I make to the style of posts, if any?/</span>
|
||||
|
||||
Hmmm, this is a prickly one too. Both of these questions suffer from the same
|
||||
problem --- <span class="ef-i">/I/</span> can't answer them. Simply put, I need to hear from <span class="ef-i">/you/</span>. Whether it
|
||||
be in the Reddit comments section, or by Email (<span style="color: #9e9e9e;">=tec@=</span> this domain), to direct
|
||||
2022's posts I am <span class="ef-i">/very/</span> interested in hearing your thoughts on:
|
||||
+ How engaging you've found this blog? (the content, the style of writing, etc.)
|
||||
+ Whether this blog has influenced your feelings on the Org project and/or community?
|
||||
+ Whether this blog has affected your thoughts on contributing to Org?
|
||||
+ What you think this blog has done well/badly over the past year?
|
||||
+ If there's anything you'd be interested in this blog doing differently in 2022?
|
||||
|
||||
That's all for now! Thank you for reading, and have a great new year 🙂
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Footnotes</span>
|
||||
|
||||
[fn:1] Both the org-mode codebase, and also the ecosystem that's sprung up
|
||||
around it
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
DECEMBER 2021
|
||||
Looking back on my first year of blogging
|
||||
|
||||
TEC
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
|
||||
2021-12-31
|
||||
|
||||
|
||||
Just over eight months ago, I kicked off /This Month in Org/ with an
|
||||
emphatic announcement of the blog’s in the form of a [Welcome] post. If
|
||||
you haven’t guessed, this is the first “blog post” I’ve ever written. In
|
||||
that /welcome/ post, I gave my motivation for starting the blog —
|
||||
essentially to bridge a perceived gap in information sources between a
|
||||
subscription to the Org project mailing list, and nothing.
|
||||
|
||||
That is why I thought this blog should exist, but until now I have
|
||||
neglected to mention what /I/ want to accomplish with it. By starting
|
||||
/TMiO/ I hoped to:
|
||||
⁃ Engage more people with the improvements being made to Org[1].
|
||||
⁃ Highlight some of the great work being done by Org[1] contributors.
|
||||
⁃ Encourage more people to consider contributing to Org[1].
|
||||
⁃ Foster a stronger sense of an Org[1] community, outside the mailing
|
||||
list.
|
||||
|
||||
Since then, I’ve effused about Org to the tune of around ten thousand
|
||||
words. We started off with a fairly dry recount recent changes, which
|
||||
(after initial feedback) has shifted slightly to try to give more
|
||||
context on the improvements and how they may be used. In June I even
|
||||
went as far as to make the majority of the post about pre-existing
|
||||
features (writing Org for LaTeX). This change has been made to:
|
||||
⁃ Try to make the blog posts a little more interesting, and less
|
||||
tedious.
|
||||
⁃ Potentially introduce readers to nice features of Org they weren’t
|
||||
aware of before.
|
||||
|
||||
We have now arrived at the first crucial question of this post: /How
|
||||
effective has this blog been in achieving its goals?/
|
||||
|
||||
Let’s start off by looking at engagement. There is no tracking on this
|
||||
site, and I’m not even counting page views. We could read into Reddit
|
||||
upvotes (which usually hover around 100-ish per post), but with no
|
||||
strong trend I’m wary of reading too much into those numbers. What about
|
||||
engendering an interest in contributing? This is even harder to
|
||||
consider. It is similarly difficult to judge whether this blog might be
|
||||
helping (even if only a bit) foster a stronger sense of community.
|
||||
|
||||
Ok, how about the second crucial question: /Moving forwards, what
|
||||
changes should I make to the style of posts, if any?/
|
||||
|
||||
Hmmm, this is a prickly one too. Both of these questions suffer from the
|
||||
same problem — /I/ can’t answer them. Simply put, I need to hear from
|
||||
/you/. Whether it be in the Reddit comments section, or by Email (`tec@'
|
||||
this domain), to direct 2022’s posts I am /very/ interested in hearing
|
||||
your thoughts on:
|
||||
⁃ How engaging you’ve found this blog? (the content, the style of
|
||||
writing, etc.)
|
||||
⁃ Whether this blog has influenced your feelings on the Org project
|
||||
and/or community?
|
||||
⁃ Whether this blog has affected your thoughts on contributing to Org?
|
||||
⁃ What you think this blog has done well/badly over the past year?
|
||||
⁃ If there’s anything you’d be interested in this blog doing differently
|
||||
in 2022?
|
||||
|
||||
That’s all for now! Thank you for reading, and have a great new year 🙂
|
||||
|
||||
|
||||
[Welcome] <file:2021-04-26-Welcome.org>
|
||||
|
||||
|
||||
|
||||
Footnotes
|
||||
─────────
|
||||
|
||||
[1] Both the org-mode codebase, and also the ecosystem that’s sprung
|
||||
up around it
|
||||
|
|
@ -0,0 +1,227 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-12 Fri 13:39 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>January 2022</title>
|
||||
<meta name="author" content="TEC" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="January 2022" />
|
||||
<meta property="og:description" content="Caching" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="TEC" />
|
||||
<meta property="og:article:published_time" content="2022-01-31T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2024-01-11T15:57:56+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2022-01-31, <span class='acr'>TEC</span></div>
|
||||
|
||||
<h1 class="title">January 2022</h1>
|
||||
<p class="subtitle" role="doc-subtitle">Caching</p>
|
||||
</header><p>
|
||||
There are less “obvious user-facing changes” this month, but a lot of good work
|
||||
has been happening 🙂.
|
||||
</p>
|
||||
<div id="outline-container-cache-continues-make" class="outline-2">
|
||||
<h2 id="cache-continues-make">The cache continues to make strides<a aria-hidden="true" href="#cache-continues-make">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-cache-continues-make">
|
||||
<p>
|
||||
Nine months ago, Ihor started working on the org-element cache. The cache has
|
||||
existed for a while now, but it used to be too buggy to be useful.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
This is no longer the case! We’re finally confident enough to flip
|
||||
<code>org-element-use-cache</code>’s default from <code>nil</code> to <code>t</code>. I mentioned some of the
|
||||
improvements in <a href="2021-11-30-element.html#orgff73293">November</a>, however Ihor has continued to make strides with the
|
||||
cache.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Getting the cache right is tough though, and so while the situation is much
|
||||
improved there are still lingering bugs which need to be chased down. If you
|
||||
only take one thing away from the post, I’d like it to be this:
|
||||
</p>
|
||||
|
||||
<div class="info" id="orgb17f9b2">
|
||||
<div style="text-align: left; margin-left: 1rem;">
|
||||
<p>
|
||||
The cache is actively being developed now, for the first time in years, so:
|
||||
</p>
|
||||
<ol class="org-ol">
|
||||
<li>Ignore old advice (like <a href="https://emacs.stackexchange.com/questions/42006/trouble-with-org-mode">this</a>) which suggests disabling the cache
|
||||
<ul class="org-ul">
|
||||
<li>Note that the cache will <i>not</i> stuff anything up, at worst it will emit a warning</li>
|
||||
</ul></li>
|
||||
<li>If you see an org-cache warning <i>please</i> report it to the Org mailing list —
|
||||
<kbd>emacs-orgmode@gnu.org</kbd>.</li>
|
||||
</ol>
|
||||
|
||||
<p>
|
||||
Cache warnings look something like this:
|
||||
</p>
|
||||
<details id='org8ad0fdd' class='code' open>
|
||||
<summary></summary>
|
||||
<div class='gutter'><a href='#org8ad0fdd'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<pre class="example" id="org8ad0fdd">
|
||||
Warning (org-element-cache): org-element--cache: Unregistered buffer modifications detected. Resetting.
|
||||
If this warning appears regularly, please report the warning text to Org mode mailing list (M-x org-submit-bug-report).
|
||||
The buffer is: config.org
|
||||
Current command: (some-buggy-command)
|
||||
Chars modified: 483
|
||||
Buffer modified: 330957
|
||||
Backtrace:
|
||||
...some possibly long backtrace...
|
||||
</pre>
|
||||
|
||||
</details>
|
||||
|
||||
<p>
|
||||
A good way to start is by copying this to your clipboard and then trying <kbd>M-x
|
||||
org-submit-bug-report</kbd>. Regardless of whether you’re using an Emacs mail client,
|
||||
this will collect all the important information (org-mode version, etc.) and
|
||||
populate a buffer with it. Add the warning text, and that will be a great help!
|
||||
After all, it’s quite hard to fix bugs we don’t know about 😆.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<p>
|
||||
As of October 2021, “bulk” heading promotion/demotion operations are now faster
|
||||
thanks to the cache, and there have now been further improvements relating to
|
||||
headings. It used to be the case that every time heading properties changed the
|
||||
entire heading (and contents) were re-parsed. Now, cache heuristics prevent the
|
||||
content from being entirely re-parsed (see
|
||||
<code>org-element--cache-avoid-synchronous-headline-re-parsing</code> for a bit more
|
||||
information). This improvement is particularly noticeable when refiling and
|
||||
archiving headings.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-persisting-data" class="outline-2">
|
||||
<h2 id="persisting-data">Persisting data<a aria-hidden="true" href="#persisting-data">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-persisting-data">
|
||||
<p>
|
||||
In October, Ihor started work on <kbd>org-persist.el</kbd> — a way to <i>persist</i> data across
|
||||
Emacs sessions. You may wonder what sort of data is being persisted. Well,
|
||||
initially org-persist was written to record variable values associated with
|
||||
particular files or buffers — such as the org-element cache. This allows
|
||||
org-mode to load the cache for an Org file and avoid re-parsing much of the
|
||||
content.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Over the past month, Ihor has <i>doubled</i> the total number of commits applied to
|
||||
<kbd>org-persist.el</kbd> and now more kinds of data can be persisted, such as remote files
|
||||
(via. tramp) and online resources. This opens up a lot of new possibilities, and
|
||||
we can begin to see what this will allow for in the next highlight.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-exporting-documents-with" class="outline-2">
|
||||
<h2 id="exporting-documents-with">Exporting documents with remote resources<a aria-hidden="true" href="#exporting-documents-with">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-exporting-documents-with">
|
||||
<p>
|
||||
Ever linked to an online image like
|
||||
<kbd>https://orgmode.org/resources/img/org-mode-unicorn.svg</kbd> in an Org document, seen
|
||||
it look nice in the <span class='acr'>HTML</span> export and then be disappointed to just see a link in
|
||||
LaTeX? Well I have. Thankfully this is no longer the case though, thanks to a
|
||||
helper function <code>org-export-link-localise</code> that’s just been added to <kbd>ox.el</kbd>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Using <kbd>org-persist.el</kbd> this acquires a local copy of the remote resource and
|
||||
substitutes it in for the remote link. This is currently utilised in <kbd>ox-latex.el</kbd>
|
||||
to provide support for not just <span class='acr'>HTTPS</span> links but also tramp files!
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org75c72b5">
|
||||
<img src="figures/ox-latex-image-link-localisation-demo.png" alt="ox-latex-image-link-localisation-demo.png" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 1: </span>A screenshot of a (compiled to <span class='acr'>PDF</span>) LaTeX export, with an <span class='acr'>HTTPS</span> and tramp images.</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
While this is currently only implemented for <kbd>ox-latex</kbd>, this can be applied
|
||||
generally, and so there’s a good chance you’ll hear more about this in the future.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
There are also thoughts of moving this to the links file (<kbd>ol.el</kbd>) which would
|
||||
make this functionality more broadly accessible (e.g. using cached/local
|
||||
versions of a resource in other places, and defining custom downloaders for
|
||||
custom link types).
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-other-improvements" class="outline-2">
|
||||
<h2 id="other-improvements">Other improvements<a aria-hidden="true" href="#other-improvements">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-other-improvements">
|
||||
<ul class="org-ul">
|
||||
<li>Produce less native-comp warnings <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>Add a header to the clock report table <span class="underline">Samim Pezeshki</span></li>
|
||||
<li>More verbose test failure summary <span class="underline">Max Nikulin</span></li>
|
||||
<li>Parallelise <kbd>make</kbd>ing the docs <span class="underline">Marco Wahl</span></li>
|
||||
<li>More org-element tests <span class="underline">Ihor Radchenko</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-bugfixes" class="outline-2">
|
||||
<h2 id="bugfixes">Bugfixes<a aria-hidden="true" href="#bugfixes">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-bugfixes">
|
||||
<ul class="org-ul">
|
||||
<li>Fix formatting in elisp-link prompt <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>Correct some checkdoc and compiler warnings <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>Correct signature for <code>org-element-at-point</code> <span class="underline">Mark A. Hershberger</span></li>
|
||||
<li>Fix the LaTeX macron accent in org-entities <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>Ignore narrowing when tangling a file <span class="underline">Nicolas Goaziou</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,11 +1,10 @@
|
|||
# Created 2024-01-12 Fri 13:39
|
||||
#+title: January 2022
|
||||
#+subtitle: Caching
|
||||
#+author: TEC
|
||||
#+date: 2022-01-31
|
||||
|
||||
#+author: TEC
|
||||
#+subtitle: Caching
|
||||
There are less "obvious user-facing changes" this month, but a lot of good work
|
||||
has been happening 🙂.
|
||||
|
||||
* The cache continues to make strides
|
||||
|
||||
Nine months ago, Ihor started working on the org-element cache. The cache has
|
||||
|
|
@ -30,14 +29,14 @@ The cache is actively being developed now, for the first time in years, so:
|
|||
|
||||
Cache warnings look something like this:
|
||||
#+begin_example
|
||||
Warning (org-element-cache): org-element--cache: Unregistered buffer modifications detected. Resetting.
|
||||
If this warning appears regularly, please report the warning text to Org mode mailing list (M-x org-submit-bug-report).
|
||||
The buffer is: config.org
|
||||
Current command: (some-buggy-command)
|
||||
Chars modified: 483
|
||||
Buffer modified: 330957
|
||||
Backtrace:
|
||||
...some possibly long backtrace...
|
||||
Warning (org-element-cache): org-element--cache: Unregistered buffer modifications detected. Resetting.
|
||||
If this warning appears regularly, please report the warning text to Org mode mailing list (M-x org-submit-bug-report).
|
||||
The buffer is: config.org
|
||||
Current command: (some-buggy-command)
|
||||
Chars modified: 483
|
||||
Buffer modified: 330957
|
||||
Backtrace:
|
||||
...some possibly long backtrace...
|
||||
#+end_example
|
||||
|
||||
A good way to start is by copying this to your clipboard and then trying =M-x
|
||||
|
|
@ -56,44 +55,8 @@ content from being entirely re-parsed (see
|
|||
~org-element--cache-avoid-synchronous-headline-re-parsing~ for a bit more
|
||||
information). This improvement is particularly noticeable when refiling and
|
||||
archiving headings.
|
||||
|
||||
#+begin_src julia :exports none
|
||||
using StatsBase, Dates
|
||||
|
||||
timestamps = read(setenv(`git log --format='%ad' --date=format:'%Y-%m-%dT%H:%M:%S' --author="Ihor Radchenko <yantar92@gmail.com>" --grep=cache`,
|
||||
dir="/home/tec/.emacs.d/.local/straight/repos/org-mode/"), String) |>
|
||||
strip |> split .|> DateTime
|
||||
|
||||
timestamps = DateTime.(timestamps)
|
||||
Dates.month.(timestamps) |> countmap
|
||||
#+end_src
|
||||
|
||||
#+RESULTS:
|
||||
| 1 | 20 |
|
||||
| 12 | 23 |
|
||||
| 10 | 42 |
|
||||
| 11 | 22 |
|
||||
| 5 | 6 |
|
||||
|
||||
* Persisting data
|
||||
|
||||
#+begin_src julia :exports none
|
||||
using StatsBase, Dates
|
||||
|
||||
timestamps = read(setenv(`git log --format='%ad' --date=format:'%Y-%m-%dT%H:%M:%S' -- "lisp/org-persist.el"`,
|
||||
dir="/home/tec/.emacs.d/.local/straight/repos/org-mode/"), String) |>
|
||||
strip |> split .|> DateTime
|
||||
|
||||
timestamps = DateTime.(timestamps)
|
||||
Dates.month.(timestamps) |> countmap
|
||||
#+end_src
|
||||
|
||||
#+RESULTS:
|
||||
| 1 | 28 |
|
||||
| 12 | 4 |
|
||||
| 10 | 19 |
|
||||
| 11 | 4 |
|
||||
|
||||
In October, Ihor started work on =org-persist.el= --- a way to /persist/ data across
|
||||
Emacs sessions. You may wonder what sort of data is being persisted. Well,
|
||||
initially org-persist was written to record variable values associated with
|
||||
|
|
@ -105,7 +68,6 @@ Over the past month, Ihor has /doubled/ the total number of commits applied to
|
|||
=org-persist.el= and now more kinds of data can be persisted, such as remote files
|
||||
(via. tramp) and online resources. This opens up a lot of new possibilities, and
|
||||
we can begin to see what this will allow for in the next highlight.
|
||||
|
||||
* Exporting documents with remote resources
|
||||
|
||||
Ever linked to an online image like
|
||||
|
|
@ -119,7 +81,6 @@ substitutes it in for the remote link. This is currently utilised in =ox-latex.e
|
|||
to provide support for not just HTTPS links but also tramp files!
|
||||
|
||||
#+caption: A screenshot of a (compiled to PDF) LaTeX export, with an HTTPS and tramp images.
|
||||
#+attr_html: :class invertible
|
||||
[[file:figures/ox-latex-image-link-localisation-demo.png]]
|
||||
|
||||
While this is currently only implemented for =ox-latex=, this can be applied
|
||||
|
|
@ -129,17 +90,15 @@ There are also thoughts of moving this to the links file (=ol.el=) which would
|
|||
make this functionality more broadly accessible (e.g. using cached/local
|
||||
versions of a resource in other places, and defining custom downloaders for
|
||||
custom link types).
|
||||
|
||||
* Other improvements
|
||||
+ Produce less native-comp warnings _Ihor Radchenko_
|
||||
+ Add a header to the clock report table _Samim Pezeshki_
|
||||
+ More verbose test failure summary _Max Nikulin_
|
||||
+ Parallelise =make=ing the docs _Marco Wahl_
|
||||
+ More org-element tests _Ihor Radchenko_
|
||||
|
||||
- Produce less native-comp warnings _Ihor Radchenko_
|
||||
- Add a header to the clock report table _Samim Pezeshki_
|
||||
- More verbose test failure summary _Max Nikulin_
|
||||
- Parallelise =make=ing the docs _Marco Wahl_
|
||||
- More org-element tests _Ihor Radchenko_
|
||||
* Bugfixes
|
||||
+ Fix formatting in elisp-link prompt _TEC_
|
||||
+ Correct some checkdoc and compiler warnings _Ihor Radchenko_
|
||||
+ Correct signature for ~org-element-at-point~ _Mark A. Hershberger_
|
||||
+ Fix the LaTeX macron accent in org-entities _TEC_
|
||||
+ Ignore narrowing when tangling a file _Nicolas Goaziou_
|
||||
- Fix formatting in elisp-link prompt _TEC_
|
||||
- Correct some checkdoc and compiler warnings _Ihor Radchenko_
|
||||
- Correct signature for ~org-element-at-point~ _Mark A. Hershberger_
|
||||
- Fix the LaTeX macron accent in org-entities _TEC_
|
||||
- Ignore narrowing when tangling a file _Nicolas Goaziou_
|
||||
|
|
@ -0,0 +1,266 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>2022-01-31-caching.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">January 2022
|
||||
</span><span style="color: #9e9e9e;">#+subtitle:</span> Caching
|
||||
<span style="color: #9e9e9e;">#+author:</span> TEC
|
||||
<span style="color: #9e9e9e;">#+date:</span> 2022-01-31
|
||||
|
||||
There are less "obvious user-facing changes" this month, but a lot of good work
|
||||
has been happening 🙂.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* The cache continues to make strides</span>
|
||||
|
||||
Nine months ago, Ihor started working on the org-element cache. The cache has
|
||||
existed for a while now, but it used to be too buggy to be useful.
|
||||
|
||||
This is no longer the case! We're finally confident enough to flip
|
||||
<span style="color: #9e9e9e;">~org-element-use-cache~</span>'s default from <span style="color: #9e9e9e;">~nil~</span> to <span style="color: #9e9e9e;">~t~</span>. I mentioned some of the
|
||||
improvements in <span style="color: #3b6ea8; font-weight: 700;">[[file:2021-11-30-element.org::Org element parser cache][November]]</span>, however Ihor has continued to make strides with the
|
||||
cache.
|
||||
|
||||
Getting the cache right is tough though, and so while the situation is much
|
||||
improved there are still lingering bugs which need to be chased down. If you
|
||||
only take one thing away from the post, I'd like it to be this:
|
||||
|
||||
<span class="ef-obb">#+begin_info
|
||||
</span>#+html: <div style="text-align: left; margin-left: 1rem;">
|
||||
The cache is actively being developed now, for the first time in years, so:
|
||||
1. Ignore old advice (like <span style="color: #3b6ea8; font-weight: 700;">[[https://emacs.stackexchange.com/questions/42006/trouble-with-org-mode][this]]</span>) which suggests disabling the cache
|
||||
- Note that the cache will <span class="ef-i">/not/</span> stuff anything up, at worst it will emit a warning
|
||||
2. If you see an org-cache warning <span class="ef-i">/please/</span> report it to the Org mailing list ---
|
||||
<span style="color: #9e9e9e;">=emacs-orgmode@gnu.org=</span>.
|
||||
|
||||
Cache warnings look something like this:
|
||||
#+begin_example
|
||||
Warning (org-element-cache): org-element--cache: Unregistered buffer modifications detected. Resetting.
|
||||
If this warning appears regularly, please report the warning text to Org mode mailing list (M-x org-submit-bug-report).
|
||||
The buffer is: config.org
|
||||
Current command: (some-buggy-command)
|
||||
Chars modified: 483
|
||||
Buffer modified: 330957
|
||||
Backtrace:
|
||||
...some possibly long backtrace...
|
||||
#+end_example
|
||||
|
||||
A good way to start is by copying this to your clipboard and then trying <span style="color: #9e9e9e;">=M-x
|
||||
org-submit-bug-report=</span>. Regardless of whether you're using an Emacs mail client,
|
||||
this will collect all the important information (org-mode version, etc.) and
|
||||
populate a buffer with it. Add the warning text, and that will be a great help!
|
||||
After all, it's quite hard to fix bugs we don't know about 😆.
|
||||
#+html: </div>
|
||||
<span class="ef-obe">#+end_info
|
||||
</span>
|
||||
As of October 2021, "bulk" heading promotion/demotion operations are now faster
|
||||
thanks to the cache, and there have now been further improvements relating to
|
||||
headings. It used to be the case that every time heading properties changed the
|
||||
entire heading (and contents) were re-parsed. Now, cache heuristics prevent the
|
||||
content from being entirely re-parsed (see
|
||||
<span style="color: #9e9e9e;">~org-element--cache-avoid-synchronous-headline-re-parsing~</span> for a bit more
|
||||
information). This improvement is particularly noticeable when refiling and
|
||||
archiving headings.
|
||||
|
||||
<span class="ef-obb">#+begin_src julia :exports none
|
||||
</span><span class="ef-ob">using StatsBase, Dates
|
||||
|
||||
timestamps = read(setenv(`git log --format='%ad' --date=format:'%Y-%m-%dT%H:%M:%S' --author="Ihor Radchenko <yantar92@gmail.com>" --grep=cache`,
|
||||
dir="/home/tec/.emacs.d/.local/straight/repos/org-mode/"), String) |>
|
||||
strip |> split .|> DateTime
|
||||
|
||||
timestamps = DateTime.(timestamps)
|
||||
Dates.month.(timestamps) |> countmap
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
<span style="color: #b1b1b1;">#+RESULTS:</span>
|
||||
| 1 | 20 |
|
||||
| 12 | 23 |
|
||||
| 10 | 42 |
|
||||
| 11 | 22 |
|
||||
| 5 | 6 |
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Persisting data</span>
|
||||
|
||||
<span class="ef-obb">#+begin_src julia :exports none
|
||||
</span><span class="ef-ob">using StatsBase, Dates
|
||||
|
||||
timestamps = read(setenv(`git log --format='%ad' --date=format:'%Y-%m-%dT%H:%M:%S' -- "lisp/org-persist.el"`,
|
||||
dir="/home/tec/.emacs.d/.local/straight/repos/org-mode/"), String) |>
|
||||
strip |> split .|> DateTime
|
||||
|
||||
timestamps = DateTime.(timestamps)
|
||||
Dates.month.(timestamps) |> countmap
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
<span style="color: #b1b1b1;">#+RESULTS:</span>
|
||||
| 1 | 28 |
|
||||
| 12 | 4 |
|
||||
| 10 | 19 |
|
||||
| 11 | 4 |
|
||||
|
||||
In October, Ihor started work on <span style="color: #9e9e9e;">=org-persist.el=</span> --- a way to <span class="ef-i">/persist/</span> data across
|
||||
Emacs sessions. You may wonder what sort of data is being persisted. Well,
|
||||
initially org-persist was written to record variable values associated with
|
||||
particular files or buffers --- such as the org-element cache. This allows
|
||||
org-mode to load the cache for an Org file and avoid re-parsing much of the
|
||||
content.
|
||||
|
||||
Over the past month, Ihor has <span class="ef-i">/doubled/</span> the total number of commits applied to
|
||||
<span style="color: #9e9e9e;">=org-persist.el=</span> and now more kinds of data can be persisted, such as remote files
|
||||
(via. tramp) and online resources. This opens up a lot of new possibilities, and
|
||||
we can begin to see what this will allow for in the next highlight.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Exporting documents with remote resources</span>
|
||||
|
||||
Ever linked to an online image like
|
||||
<span style="color: #9e9e9e;">=</span><span style="color: #9e9e9e; font-weight: 700;">https://orgmode.org/resources/img/org-mode-unicorn.svg</span><span style="color: #9e9e9e;">=</span> in an Org document, seen
|
||||
it look nice in the HTML export and then be disappointed to just see a link in
|
||||
LaTeX? Well I have. Thankfully this is no longer the case though, thanks to a
|
||||
helper function <span style="color: #9e9e9e;">~org-export-link-localise~</span> that's just been added to <span style="color: #9e9e9e;">=ox.el=</span>.
|
||||
|
||||
Using <span style="color: #9e9e9e;">=org-persist.el=</span> this acquires a local copy of the remote resource and
|
||||
substitutes it in for the remote link. This is currently utilised in <span style="color: #9e9e9e;">=ox-latex.el=</span>
|
||||
to provide support for not just HTTPS links but also tramp files!
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">A screenshot of a (compiled to PDF) LaTeX export, with an HTTPS and tramp images.</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/ox-latex-image-link-localisation-demo.png]]</span>
|
||||
|
||||
While this is currently only implemented for <span style="color: #9e9e9e;">=ox-latex=</span>, this can be applied
|
||||
generally, and so there's a good chance you'll hear more about this in the future.
|
||||
|
||||
There are also thoughts of moving this to the links file (<span style="color: #9e9e9e;">=ol.el=</span>) which would
|
||||
make this functionality more broadly accessible (e.g. using cached/local
|
||||
versions of a resource in other places, and defining custom downloaders for
|
||||
custom link types).
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Other improvements</span>
|
||||
+ Produce less native-comp warnings _Ihor Radchenko_
|
||||
+ Add a header to the clock report table _Samim Pezeshki_
|
||||
+ More verbose test failure summary _Max Nikulin_
|
||||
+ Parallelise <span style="color: #9e9e9e;">=make=</span>ing the docs _Marco Wahl_
|
||||
+ More org-element tests _Ihor Radchenko_
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Bugfixes</span>
|
||||
+ Fix formatting in elisp-link prompt _TEC_
|
||||
+ Correct some checkdoc and compiler warnings _Ihor Radchenko_
|
||||
+ Correct signature for <span style="color: #9e9e9e;">~org-element-at-point~</span> _Mark A. Hershberger_
|
||||
+ Fix the LaTeX macron accent in org-entities _TEC_
|
||||
+ Ignore narrowing when tangling a file _Nicolas Goaziou_
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,138 @@
|
|||
━━━━━━━━━━━━━━
|
||||
JANUARY 2022
|
||||
Caching
|
||||
|
||||
TEC
|
||||
━━━━━━━━━━━━━━
|
||||
|
||||
|
||||
2022-01-31
|
||||
|
||||
|
||||
There are less “obvious user-facing changes” this month, but a lot of
|
||||
good work has been happening 🙂.
|
||||
|
||||
|
||||
The cache continues to make strides
|
||||
═══════════════════════════════════
|
||||
|
||||
Nine months ago, Ihor started working on the org-element cache. The
|
||||
cache has existed for a while now, but it used to be too buggy to be
|
||||
useful.
|
||||
|
||||
This is no longer the case! We’re finally confident enough to flip
|
||||
`org-element-use-cache'’s default from `nil' to `t'. I mentioned some
|
||||
of the improvements in [November], however Ihor has continued to make
|
||||
strides with the cache.
|
||||
|
||||
Getting the cache right is tough though, and so while the situation is
|
||||
much improved there are still lingering bugs which need to be chased
|
||||
down. If you only take one thing away from the post, I’d like it to be
|
||||
this:
|
||||
|
||||
The cache is actively being developed now, for the first time in
|
||||
years, so:
|
||||
1. Ignore old advice (like [this]) which suggests disabling the cache
|
||||
• Note that the cache will /not/ stuff anything up, at worst it
|
||||
will emit a warning
|
||||
2. If you see an org-cache warning /please/ report it to the Org
|
||||
mailing list — `emacs-orgmode@gnu.org'.
|
||||
|
||||
Cache warnings look something like this:
|
||||
┌────
|
||||
│ Warning (org-element-cache): org-element--cache: Unregistered buffer modifications detected. Resetting.
|
||||
│ If this warning appears regularly, please report the warning text to Org mode mailing list (M-x org-submit-bug-report).
|
||||
│ The buffer is: config.org
|
||||
│ Current command: (some-buggy-command)
|
||||
│ Chars modified: 483
|
||||
│ Buffer modified: 330957
|
||||
│ Backtrace:
|
||||
│ ...some possibly long backtrace...
|
||||
└────
|
||||
|
||||
A good way to start is by copying this to your clipboard and then
|
||||
trying `M-x org-submit-bug-report'. Regardless of whether you’re using
|
||||
an Emacs mail client, this will collect all the important information
|
||||
(org-mode version, etc.) and populate a buffer with it. Add the
|
||||
warning text, and that will be a great help! After all, it’s quite
|
||||
hard to fix bugs we don’t know about 😆.
|
||||
|
||||
As of October 2021, “bulk” heading promotion/demotion operations are
|
||||
now faster thanks to the cache, and there have now been further
|
||||
improvements relating to headings. It used to be the case that every
|
||||
time heading properties changed the entire heading (and contents) were
|
||||
re-parsed. Now, cache heuristics prevent the content from being
|
||||
entirely re-parsed (see
|
||||
`org-element--cache-avoid-synchronous-headline-re-parsing' for a bit
|
||||
more information). This improvement is particularly noticeable when
|
||||
refiling and archiving headings.
|
||||
|
||||
|
||||
[November] <file:2021-11-30-element.org::Org element parser cache>
|
||||
|
||||
[this]
|
||||
<https://emacs.stackexchange.com/questions/42006/trouble-with-org-mode>
|
||||
|
||||
|
||||
Persisting data
|
||||
═══════════════
|
||||
|
||||
In October, Ihor started work on `org-persist.el' — a way to /persist/
|
||||
data across Emacs sessions. You may wonder what sort of data is being
|
||||
persisted. Well, initially org-persist was written to record variable
|
||||
values associated with particular files or buffers — such as the
|
||||
org-element cache. This allows org-mode to load the cache for an Org
|
||||
file and avoid re-parsing much of the content.
|
||||
|
||||
Over the past month, Ihor has /doubled/ the total number of commits
|
||||
applied to `org-persist.el' and now more kinds of data can be
|
||||
persisted, such as remote files (via. tramp) and online
|
||||
resources. This opens up a lot of new possibilities, and we can begin
|
||||
to see what this will allow for in the next highlight.
|
||||
|
||||
|
||||
Exporting documents with remote resources
|
||||
═════════════════════════════════════════
|
||||
|
||||
Ever linked to an online image like
|
||||
`https://orgmode.org/resources/img/org-mode-unicorn.svg' in an Org
|
||||
document, seen it look nice in the HTML export and then be
|
||||
disappointed to just see a link in LaTeX? Well I have. Thankfully this
|
||||
is no longer the case though, thanks to a helper function
|
||||
`org-export-link-localise' that’s just been added to `ox.el'.
|
||||
|
||||
Using `org-persist.el' this acquires a local copy of the remote
|
||||
resource and substitutes it in for the remote link. This is currently
|
||||
utilised in `ox-latex.el' to provide support for not just HTTPS links
|
||||
but also tramp files!
|
||||
|
||||
<file:figures/ox-latex-image-link-localisation-demo.png>
|
||||
|
||||
While this is currently only implemented for `ox-latex', this can be
|
||||
applied generally, and so there’s a good chance you’ll hear more about
|
||||
this in the future.
|
||||
|
||||
There are also thoughts of moving this to the links file (`ol.el')
|
||||
which would make this functionality more broadly accessible
|
||||
(e.g. using cached/local versions of a resource in other places, and
|
||||
defining custom downloaders for custom link types).
|
||||
|
||||
|
||||
Other improvements
|
||||
══════════════════
|
||||
|
||||
⁃ Produce less native-comp warnings _Ihor Radchenko_
|
||||
⁃ Add a header to the clock report table _Samim Pezeshki_
|
||||
⁃ More verbose test failure summary _Max Nikulin_
|
||||
⁃ Parallelise `make'ing the docs _Marco Wahl_
|
||||
⁃ More org-element tests _Ihor Radchenko_
|
||||
|
||||
|
||||
Bugfixes
|
||||
════════
|
||||
|
||||
⁃ Fix formatting in elisp-link prompt _TEC_
|
||||
⁃ Correct some checkdoc and compiler warnings _Ihor Radchenko_
|
||||
⁃ Correct signature for `org-element-at-point' _Mark A. Hershberger_
|
||||
⁃ Fix the LaTeX macron accent in org-entities _TEC_
|
||||
⁃ Ignore narrowing when tangling a file _Nicolas Goaziou_
|
||||
|
|
@ -0,0 +1,487 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-12 Fri 13:39 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>February 2022</title>
|
||||
<meta name="author" content="Kristijan Husak" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="February 2022" />
|
||||
<meta property="og:description" content="An orgmode clone for neovim" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="Kristijan" />
|
||||
<meta property="og:article:author:last_name" content="Husak" />
|
||||
<meta property="og:article:published_time" content="2022-03-02T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2022-03-04T16:30:25+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2022-02-30, Kristijan Husak</div>
|
||||
|
||||
<h1 class="title">February 2022</h1>
|
||||
<p class="subtitle" role="doc-subtitle">An orgmode clone for neovim</p>
|
||||
</header><p>
|
||||
Timothy (<span class='acr'>TEC</span>) here. This month we have a guest post from a different part of the
|
||||
Org ecosystem, to highlight one of the most promising efforts to provide a good
|
||||
experience outside Emacs.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<div class="link-preview"><a href="https://github.com/nvim-orgmode/orgmode"><img src="https://opengraph.githubassets.com/77915b5f9981ebc87709ee51d02ed39c60c1359e31ca75449c487c099f2456f6/nvim-orgmode/orgmode"/><small>github.com</small><p><b>GitHub - nvim-orgmode/orgmode: Orgmode clone written in Lua for Neovim 0.9+.</b></br>Orgmode clone written in Lua for Neovim 0.9+. Contribute to nvim-orgmode/orgmode development by creating an account on GitHub.</p></a></div>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
“But I use Emacs, I don’t care” you may say. In that case, I’d like to point out
|
||||
that wider spread and better Org support enriches the Org ecosystem as a whole.
|
||||
It makes the format more approachable, and <i>useful</i> for other people. This is good
|
||||
for everybody.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Without any further ado, here’s the guest post kindly written by Kristijan.
|
||||
Enjoy!
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
|
||||
<p>
|
||||
Like every beginner Vim user, at some point I ran into a usual editor war post:
|
||||
Vim vs Emacs. At that time, I didn’t have an idea what “Emacs” was.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
A simple Google search yielded something that seemed just like a very simple
|
||||
editor with strange, but more familiar shortcuts. I didn’t bother too much to
|
||||
figure out what it is, because I was already pulled in fairly deep into Vim and
|
||||
its philosophy.
|
||||
</p>
|
||||
<div id="outline-container-note-taking-neovim" class="outline-2">
|
||||
<h2 id="note-taking-neovim">Note taking in (Neo)Vim<a aria-hidden="true" href="#note-taking-neovim">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-note-taking-neovim">
|
||||
<p>
|
||||
At first, I did some note taking only when really necessary, in random
|
||||
plain text files. Most of the things I managed to keep in my head, since
|
||||
I was younger and less busy 🙂.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Once I got into the situation where I needed to keep more notes, <a href="https://github.com/vimwiki/vimwiki">vimwiki</a> was the
|
||||
natural choice.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
That worked very well for a period, until the need for writing quick notes
|
||||
arise. Vimwiki didn’t have anything that would allow that. I could of course
|
||||
have a mapping that opens a specific file where I can add notes, but that just
|
||||
never felt right in my mind. I would keep a bunch of things in the same place,
|
||||
and then later I needed to spend some time organizing them.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
At that point, I wasn’t sure how to achieve what I want. I did a brief look at
|
||||
<a href="https://orgmode.org/">Emacs OrgMode</a> to see what’s all the fuss about, but to me, it seemed just like a
|
||||
different version of Markdown. You put some unordered lists as your notes, and
|
||||
that’s it. I never spent more time trying to see all the neat features. I even
|
||||
tried creating some of my custom note taking tools, but I never managed to
|
||||
finish them because I didn’t have a clear idea of how to solve my problems.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-first-encounter-with" class="outline-2">
|
||||
<h2 id="first-encounter-with">First encounter with Orgmode like tool: vim-dotoo<a aria-hidden="true" href="#first-encounter-with">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-first-encounter-with">
|
||||
<p>
|
||||
One weekend, I was browsing through Vim subreddit, as I usually do at least once
|
||||
a day. There was a post about an “Orgmode like task logging” plugin called
|
||||
<a href="https://github.com/dhruvasagar/vim-dotoo">vim-dotoo</a>. I opened it up, and I didn’t see much at that point. I wasn’t too
|
||||
excited. I went through readme, and noticed that author (<a href="https://github.com/dhruvasagar">dhruvasagar</a>) put a
|
||||
fairly big emphasis on the “Agenda view”. I had no idea what “Agenda view” is.
|
||||
Thankfully, the author also made a <a href="https://www.youtube.com/watch?v=nsv33iOnH34">screencast</a>, which is rather long (1.5h), but
|
||||
I had some time, so I went through it.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
At that point, I was first met with “Capturing” and “Refiling”. <b>My mind was
|
||||
blown!</b> What a simple, yet extremely powerful idea! How had that never crossed my
|
||||
mind? From that point on, this plugin had my full attention.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
I’m always emphasizing that <a href="https://github.com/dhruvasagar">dhruvasagar</a> and his <a href="https://github.com/dhruvasagar/vim-dotoo">vim-dotoo</a> plugin are most
|
||||
deserving for having inspired <a href="https://github.com/nvim-orgmode/orgmode">https://github.com/nvim-orgmode/orgmode</a>, and I
|
||||
can’t thank him enough for that.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-first-steps-with" class="outline-2">
|
||||
<h2 id="first-steps-with">First steps with vim-dotoo and birth of orgmode.nvim<a aria-hidden="true" href="#first-steps-with">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-first-steps-with">
|
||||
<p>
|
||||
For some time, I was using <a href="https://github.com/dhruvasagar/vim-dotoo">vim-dotoo</a>. I moved all of my Vimwiki notes to it. It
|
||||
was a breath of fresh air. Alongside that, I started getting more interest in
|
||||
the original Emacs Orgmode. I started noticing the differences, and some of the
|
||||
missing features that were now looking quite attractive. I made <a href="https://github.com/dhruvasagar/vim-dotoo/pulls?q=is%3Apr+sort%3Aupdated-desc+author%3Akristijanhusak+is%3Aclosed">few
|
||||
contributions</a> to vim-dotoo. As time passed, and my notes started to grow, things
|
||||
began being slow. I did some profiling, and figured out that it’s just a usual
|
||||
Vim problem, Vimscript performance. It was just too slow for certain things that
|
||||
Orgmode provides, and it would hardly get any better as more things are added.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Separately from Vim and Vimscript, <a href="https://github.com/neovim/neovim">Neovim</a> was on a stable <kbd>v0.4</kbd> release, and <kbd>v0.5</kbd>
|
||||
was still being developed. I was using Neovim from version 0.3, and was
|
||||
carefully following the progress on it. Lua was introduced as a first class
|
||||
citizen. A Bunch of new plugins arise from it. All the benchmarks showed that
|
||||
Lua outperforms Vimscript in almost everything. Besides the performance, Lua is
|
||||
a “normal” programming language, which means that support for it is much better.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
At that point, I became curious: Could Lua be the path to the faster Orgmode? I
|
||||
spent several days thinking about it. I wanted to give it a try. My biggest
|
||||
concern was that I had absolutely zero experience writing parsers. I had never
|
||||
written anything more complicated than an averagely complicated regex for
|
||||
purposes of parsing. I noticed that vim-dotoo also used regex to do the parsing,
|
||||
so that eased my mind a bit.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
One weekend, I started working on it. It was really interesting and challenging.
|
||||
I spent a lot of my free time on it. At certain points, it seemed like hacking,
|
||||
since it was not a proper parsing. I tried to learn how to write a proper
|
||||
parser, but it was just too time consuming and complicated. I proceeded with the
|
||||
regex parsing to see how far I can go.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Besides parsing, I had a few more challenges to overcome:
|
||||
</p>
|
||||
</div>
|
||||
<div id="outline-container-understanding-orgmode-syntax" class="outline-3">
|
||||
<h3 id="understanding-orgmode-syntax">Understanding the OrgMode syntax and all the functionality<a aria-hidden="true" href="#understanding-orgmode-syntax">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-understanding-orgmode-syntax">
|
||||
<p>
|
||||
This is still the biggest challenge. I didn’t have any idea how big and robust
|
||||
OrgMode is. If I would know it at that time, I wouldn’t even jump on this train.
|
||||
It’s really hard to grasp all of it. Considering I’ve only used it for around 8
|
||||
months, I think I made some good progress on learning it.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-remote-editing" class="outline-3">
|
||||
<h3 id="remote-editing">Remote editing<a aria-hidden="true" href="#remote-editing">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-remote-editing">
|
||||
<p>
|
||||
By remote editing, I mean automatically updating content in the current
|
||||
or any other file. Few examples: adding/updating properties, managing
|
||||
tags, changing <span class='acr'>TODO</span> states, archiving, refiling, remote editing from
|
||||
agenda view, etc.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
There is no built-in way to update content in another file through the
|
||||
Neovim <span class='acr'>API</span>, without actually opening the file in an editor. I solved
|
||||
this by:
|
||||
</p>
|
||||
|
||||
<ul class="org-ul">
|
||||
<li>Saving as much position information as possible in the internal state,
|
||||
so I can pinpoint the correct location</li>
|
||||
<li>Opening a file in a <kbd>1 row x 1 col</kbd> floating window and doing quick
|
||||
edits there</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-working-with-dates" class="outline-3">
|
||||
<h3 id="working-with-dates">Working with dates<a aria-hidden="true" href="#working-with-dates">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-working-with-dates">
|
||||
<p>
|
||||
From my experience, dates are challenging in all areas of programming,
|
||||
so this is not so surprising. There are some Lua plugins for dates, but
|
||||
those seemed a bit too basic for my use case, and I wanted to keep
|
||||
external plugins to the minimum. I went with a custom solution that uses
|
||||
Lua’s native dates, which has certain limitations, but works out for
|
||||
most of the things.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-highlighting-mostly-agenda" class="outline-3">
|
||||
<h3 id="highlighting-mostly-agenda">Highlighting, mostly in Agenda view<a aria-hidden="true" href="#highlighting-mostly-agenda">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-highlighting-mostly-agenda">
|
||||
<p>
|
||||
Vim’s syntax engine is fairly old, but still very much used, especially
|
||||
in the Vim community. Implementation of tree-sitter slightly improved
|
||||
this experience in Neovim, because “Highlight matches” are found via
|
||||
tree-sitter, instead of a bunch of regexes.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
This helped me out later for the Org file itself, but agenda view is
|
||||
still something that’s built as a custom view. Old Syntax highlight engine
|
||||
would be really hard to add, because the content is too dynamic. I went
|
||||
with the Neovim highlight <span class='acr'>API</span> that allows Highlighting things by their
|
||||
exact position in the buffer. Tree-sitter implementation does something
|
||||
similar in the background for Highlighting.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-keeping-configuration-simple" class="outline-3">
|
||||
<h3 id="keeping-configuration-simple">Keeping configuration simple and familiar to Emacs OrgMode<a aria-hidden="true" href="#keeping-configuration-simple">#</a> </h3>
|
||||
<div class="outline-text-3" id="text-keeping-configuration-simple">
|
||||
<p>
|
||||
Vim-dotoo configuration was mostly Vim style, through some global
|
||||
variables. I wanted to have a configuration that is familiar to an Emacs
|
||||
OrgMode user, by having as many options as possible named completely the
|
||||
same as in Emacs.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For example, Here’s a comparison of few options between Emacs and
|
||||
Neovim:
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Emacs:
|
||||
</p>
|
||||
|
||||
<details id='keeping-configuration-simple,code--1' class='code' open><summary><span class="lang">elisp</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#keeping-configuration-simple,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-elisp">(<span class="org-keyword">setq</span> org-agenda-files '(<span class="org-string">"~/orgmodes"</span>))
|
||||
(<span class="org-keyword">setq</span> org-agenda-skip-scheduled-if-done t)
|
||||
(<span class="org-keyword">setq</span> org-agenda-span 7)
|
||||
(<span class="org-keyword">setq</span> org-hide-leading-stars t)
|
||||
(<span class="org-keyword">setq</span> org-capture-templates
|
||||
'((<span class="org-string">"t"</span> <span class="org-string">"Todo"</span> entry (file <span class="org-string">"~/orgmodes/todos.org"</span>)
|
||||
<span class="org-string">"* TODO %?"</span>)
|
||||
(<span class="org-string">"j"</span> <span class="org-string">"Journal"</span> entry (file <span class="org-string">"~/orgmodes/journal.org"</span>)
|
||||
<span class="org-string">"* %?\nEntered on %U\n %a"</span>)))
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
Neovim:
|
||||
</p>
|
||||
|
||||
<details id='keeping-configuration-simple,code--2' class='code' open><summary><span class="lang">Lua</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#keeping-configuration-simple,code--2'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-lua">require('orgmode').setup({
|
||||
org_agenda_files = { '~/orgmodes' },
|
||||
org_agenda_skip_scheduled_if_done = true,
|
||||
org_agenda_span = 7,
|
||||
org_hide_leading_stars = true
|
||||
org_capture_templates = {
|
||||
t = {
|
||||
description = 'Todo',
|
||||
target = '~/orgmodes/todos.org',
|
||||
template = '* TODO %?',
|
||||
},
|
||||
j = {
|
||||
description = 'Journal',
|
||||
target = '~/orgmodes/journal.org',
|
||||
template = '* %?\nEntered on %U\n %a',
|
||||
}
|
||||
}
|
||||
})
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
One of the most noticeable differences is between the usage of hyphens
|
||||
(<kbd>-</kbd>) and underscores (<kbd>_</kbd>). I did that only for the sake of simplicity,
|
||||
because hyphens is not a valid character in variable names in Lua, so
|
||||
all of the options would need to be wrapped as a string (for example:
|
||||
<kbd>['org-agenda-files']</kbd>).
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-first-release-orgmodenvim" class="outline-2">
|
||||
<h2 id="first-release-orgmodenvim">First release of orgmode.nvim and introduction of tree-sitter parser<a aria-hidden="true" href="#first-release-orgmodenvim">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-first-release-orgmodenvim">
|
||||
<p>
|
||||
After ~1.5 months I <a href="https://www.reddit.com/r/neovim/comments/o8zp0k/orgmodenvim_orgmode_clone_written_in_lua_for/">published the initial version</a>. The focus was on Agenda and
|
||||
capturing (<span class='acr'>GTD</span>), since those are the things I mostly used. It got some traction,
|
||||
and people started testing it and reporting bugs.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
One of the common questions was: <i>“Any plans to introduce tree-sitter parser?”</i>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
I knew about <a href="https://github.com/tree-sitter/tree-sitter">tree-sitter</a> and used it in my day-to-day job for a few programming
|
||||
languages, but I had absolutely no idea how it worked, and especially how to
|
||||
write a tree-sitter parser. I put it aside, and continued working on what I
|
||||
had.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
One day, Emilia (<a href="https://github.com/milisims">milisims</a>) contacted me via email to ask me if I would be
|
||||
willing to try the tree-sitter parser she’s been working on for some time. I
|
||||
gladly accepted. She gave me access to the repository, and I started tinkering
|
||||
with it in a separate branch. No one was aware at that point that tree-sitter
|
||||
support would happen some time soon.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
After some time, I set up a “beta” branch called “tree-sitter” and <a href="https://www.reddit.com/r/neovim/comments/ph2xqc/orgmodenvim_treesitter_support/">announced it
|
||||
for testing</a>. Once the reported bugs slowed to a trickle, I merged it into the
|
||||
“master” branch.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
I believe that tree-sitter grammar for Org could help out other editors to
|
||||
implement their version of Orgmode plugin, but I don’t think it would ever be
|
||||
helpful for Emacs. Emacs parser is the one and only that has it all implemented.
|
||||
Also, as much as tree-sitter is powerful, its main purpose is to parse
|
||||
programming languages, which mostly has “static” patterns to match. Orgmode is
|
||||
by its nature dynamic, which causes a variety of issues for a parser that’s not
|
||||
meant for that kind of usage.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-limitations" class="outline-2">
|
||||
<h2 id="limitations">Limitations<a aria-hidden="true" href="#limitations">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-limitations">
|
||||
<p>
|
||||
(Neo)Vim is a great editor, but it still cannot compare to Emacs in certain
|
||||
things. Manipulating the “View” part of the editor is tricky or impossible for
|
||||
certain things.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
I even <a href="https://github.com/nvim-orgmode/orgmode/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aneovim-dependency">made a label</a> for reported issues where Neovim support for certain things
|
||||
is a blocker. I’m hoping that at least some of these will be available in future
|
||||
Neovim releases.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-features" class="outline-2">
|
||||
<h2 id="features">Features<a aria-hidden="true" href="#features">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-features">
|
||||
<p>
|
||||
I will not go into too many details about the available features, since those
|
||||
can be viewed in <a href="https://github.com/nvim-orgmode/orgmode#features-detailed-breakdown">repository readme</a>, but I want to mention one feature that does
|
||||
not exist as a built/-in feature in the Emacs Orgmode: <a href="https://github.com/nvim-orgmode/orgmode/blob/master/DOCS.md#notifications-experimental">Notifications</a>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
This allows getting a “desktop notification” for tasks that are within
|
||||
the specified threshold for schedule/deadline time. It requires some
|
||||
configuration to set up a cron job, but it’s been working great for me
|
||||
for several months now.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-plans" class="outline-2">
|
||||
<h2 id="plans">Plans<a aria-hidden="true" href="#plans">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-plans">
|
||||
<p>
|
||||
The current state of the project is very usable for me. I’m not lacking any of
|
||||
the major features, mostly because I’m not used to using them. Nevertheless,
|
||||
there are plans to add more things, and I’m getting a lot of help from the
|
||||
community. I want to specifically mention <a href="https://github.com/levouh">levouh</a> and <a href="https://github.com/lukas-reineke">lukas-reineke</a>, since they
|
||||
added a lot of value to the project, and I want to thank them and everyone else
|
||||
who contributed. Their help is much appreciated.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
There are few high priority tasks that I’m hoping to flush out first:
|
||||
</p>
|
||||
|
||||
<ul class="org-ul">
|
||||
<li>Implementing <a href="https://github.com/milisims/tree-sitter-org/issues/13">v1.0.0</a> release of the tree-sitter parser. This should allow for
|
||||
faster and less error-prone parsing.</li>
|
||||
<li><a href="https://github.com/nvim-orgmode/orgmode/issues/26">Infrastructure for plugin developers</a>, to allow other people to build plugins
|
||||
on top of nvim-orgmode.</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
And a long term goal for these:
|
||||
</p>
|
||||
|
||||
<ul class="org-ul">
|
||||
<li>Tables support (and at least basic formulas)</li>
|
||||
<li><a href="https://github.com/nvim-orgmode/orgmode/issues/190">Org Babel like code block evaluation</a> (and hopefully basic support for literate
|
||||
programming)</li>
|
||||
<li><a href="https://github.com/nvim-orgmode/orgmode/issues/195">Diary format dates</a></li>
|
||||
<li><a href="https://github.com/nvim-orgmode/orgmode/issues/135">Custom agenda commands</a></li>
|
||||
<li>More clocking features (reports)</li>
|
||||
<li>File specific configuration via directives (<a href="https://github.com/nvim-orgmode/orgmode/issues/185">todo keywords</a>, properties, etc.)</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-closing-thoughts" class="outline-2">
|
||||
<h2 id="closing-thoughts">Closing thoughts<a aria-hidden="true" href="#closing-thoughts">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-closing-thoughts">
|
||||
<p>
|
||||
When I started working on <a href="https://github.com/nvim-orgmode/orgmode">nvim-orgmode</a>, I didn’t have a clue what I’m jumping
|
||||
into. Every day I learn about more and more Orgmode features that I wasn’t even
|
||||
aware existed.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
I’m certain that this project will never manage to clone the Orgmode
|
||||
functionality completely, but I’m hoping it will get close enough so everyone
|
||||
from Neovim community and Emacsers trying out Neovim will be able to use it for
|
||||
their needs.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Having experienced Orgmode users <a href="https://github.com/nvim-orgmode/orgmode/issues/159">testing</a> it is a huge help, so if anyone is
|
||||
willing to give it a try, feel free to open up an issue and write your thoughts
|
||||
there. Thanks!
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,13 +1,13 @@
|
|||
# Created 2024-01-12 Fri 13:39
|
||||
#+title: February 2022
|
||||
#+subtitle: An orgmode clone for neovim
|
||||
#+author: Kristijan Husak
|
||||
#+date: 2022-02-30
|
||||
|
||||
#+author: Kristijan Husak
|
||||
#+subtitle: An orgmode clone for neovim
|
||||
Timothy (TEC) here. This month we have a guest post from a different part of the
|
||||
Org ecosystem, to highlight one of the most promising efforts to provide a good
|
||||
experience outside Emacs.
|
||||
|
||||
[[Https://github.com/nvim-orgmode/orgmode]]
|
||||
//github.com/nvim-orgmode/orgmode
|
||||
|
||||
"But I use Emacs, I don't care" you may say. In that case, I'd like to point out
|
||||
that wider spread and better Org support enriches the Org ecosystem as a whole.
|
||||
|
|
@ -26,7 +26,6 @@ A simple Google search yielded something that seemed just like a very simple
|
|||
editor with strange, but more familiar shortcuts. I didn't bother too much to
|
||||
figure out what it is, because I was already pulled in fairly deep into Vim and
|
||||
its philosophy.
|
||||
|
||||
* Note taking in (Neo)Vim
|
||||
|
||||
At first, I did some note taking only when really necessary, in random
|
||||
|
|
@ -48,7 +47,6 @@ different version of Markdown. You put some unordered lists as your notes, and
|
|||
that's it. I never spent more time trying to see all the neat features. I even
|
||||
tried creating some of my custom note taking tools, but I never managed to
|
||||
finish them because I didn't have a clear idea of how to solve my problems.
|
||||
|
||||
* First encounter with Orgmode like tool: vim-dotoo
|
||||
|
||||
One weekend, I was browsing through Vim subreddit, as I usually do at least once
|
||||
|
|
@ -66,7 +64,6 @@ mind? From that point on, this plugin had my full attention.
|
|||
I'm always emphasizing that [[https://github.com/dhruvasagar][dhruvasagar]] and his [[https://github.com/dhruvasagar/vim-dotoo][vim-dotoo]] plugin are most
|
||||
deserving for having inspired [[https://github.com/nvim-orgmode/orgmode]], and I
|
||||
can't thank him enough for that.
|
||||
|
||||
* First steps with vim-dotoo and birth of orgmode.nvim
|
||||
|
||||
For some time, I was using [[https://github.com/dhruvasagar/vim-dotoo][vim-dotoo]]. I moved all of my Vimwiki notes to it. It
|
||||
|
|
@ -99,14 +96,12 @@ parser, but it was just too time consuming and complicated. I proceeded with the
|
|||
regex parsing to see how far I can go.
|
||||
|
||||
Besides parsing, I had a few more challenges to overcome:
|
||||
|
||||
** Understanding the OrgMode syntax and all the functionality
|
||||
|
||||
This is still the biggest challenge. I didn't have any idea how big and robust
|
||||
OrgMode is. If I would know it at that time, I wouldn't even jump on this train.
|
||||
It's really hard to grasp all of it. Considering I've only used it for around 8
|
||||
months, I think I made some good progress on learning it.
|
||||
|
||||
** Remote editing
|
||||
|
||||
By remote editing, I mean automatically updating content in the current
|
||||
|
|
@ -122,7 +117,6 @@ this by:
|
|||
so I can pinpoint the correct location
|
||||
- Opening a file in a =1 row x 1 col= floating window and doing quick
|
||||
edits there
|
||||
|
||||
** Working with dates
|
||||
|
||||
From my experience, dates are challenging in all areas of programming,
|
||||
|
|
@ -131,7 +125,6 @@ those seemed a bit too basic for my use case, and I wanted to keep
|
|||
external plugins to the minimum. I went with a custom solution that uses
|
||||
Lua's native dates, which has certain limitations, but works out for
|
||||
most of the things.
|
||||
|
||||
** Highlighting, mostly in Agenda view
|
||||
|
||||
Vim's syntax engine is fairly old, but still very much used, especially
|
||||
|
|
@ -145,7 +138,6 @@ would be really hard to add, because the content is too dynamic. I went
|
|||
with the Neovim highlight API that allows Highlighting things by their
|
||||
exact position in the buffer. Tree-sitter implementation does something
|
||||
similar in the background for Highlighting.
|
||||
|
||||
** Keeping configuration simple and familiar to Emacs OrgMode
|
||||
|
||||
Vim-dotoo configuration was mostly Vim style, through some global
|
||||
|
|
@ -159,38 +151,38 @@ Neovim:
|
|||
Emacs:
|
||||
|
||||
#+begin_src elisp
|
||||
(setq org-agenda-files '("~/orgmodes"))
|
||||
(setq org-agenda-skip-scheduled-if-done t)
|
||||
(setq org-agenda-span 7)
|
||||
(setq org-hide-leading-stars t)
|
||||
(setq org-capture-templates
|
||||
'(("t" "Todo" entry (file "~/orgmodes/todos.org")
|
||||
"* TODO %?")
|
||||
("j" "Journal" entry (file "~/orgmodes/journal.org")
|
||||
"* %?\nEntered on %U\n %a")))
|
||||
(setq org-agenda-files '("~/orgmodes"))
|
||||
(setq org-agenda-skip-scheduled-if-done t)
|
||||
(setq org-agenda-span 7)
|
||||
(setq org-hide-leading-stars t)
|
||||
(setq org-capture-templates
|
||||
'(("t" "Todo" entry (file "~/orgmodes/todos.org")
|
||||
"* TODO %?")
|
||||
("j" "Journal" entry (file "~/orgmodes/journal.org")
|
||||
"* %?\nEntered on %U\n %a")))
|
||||
#+end_src
|
||||
|
||||
Neovim:
|
||||
|
||||
#+begin_src lua
|
||||
require('orgmode').setup({
|
||||
org_agenda_files = { '~/orgmodes' },
|
||||
org_agenda_skip_scheduled_if_done = true,
|
||||
org_agenda_span = 7,
|
||||
org_hide_leading_stars = true
|
||||
org_capture_templates = {
|
||||
t = {
|
||||
description = 'Todo',
|
||||
target = '~/orgmodes/todos.org',
|
||||
template = '* TODO %?',
|
||||
},
|
||||
j = {
|
||||
description = 'Journal',
|
||||
target = '~/orgmodes/journal.org',
|
||||
template = '* %?\nEntered on %U\n %a',
|
||||
}
|
||||
}
|
||||
})
|
||||
require('orgmode').setup({
|
||||
org_agenda_files = { '~/orgmodes' },
|
||||
org_agenda_skip_scheduled_if_done = true,
|
||||
org_agenda_span = 7,
|
||||
org_hide_leading_stars = true
|
||||
org_capture_templates = {
|
||||
t = {
|
||||
description = 'Todo',
|
||||
target = '~/orgmodes/todos.org',
|
||||
template = '* TODO %?',
|
||||
},
|
||||
j = {
|
||||
description = 'Journal',
|
||||
target = '~/orgmodes/journal.org',
|
||||
template = '* %?\nEntered on %U\n %a',
|
||||
}
|
||||
}
|
||||
})
|
||||
#+end_src
|
||||
|
||||
One of the most noticeable differences is between the usage of hyphens
|
||||
|
|
@ -198,7 +190,6 @@ One of the most noticeable differences is between the usage of hyphens
|
|||
because hyphens is not a valid character in variable names in Lua, so
|
||||
all of the options would need to be wrapped as a string (for example:
|
||||
=['org-agenda-files']=).
|
||||
|
||||
* First release of orgmode.nvim and introduction of tree-sitter parser
|
||||
|
||||
After ~1.5 months I [[https://www.reddit.com/r/neovim/comments/o8zp0k/orgmodenvim_orgmode_clone_written_in_lua_for/][published the initial version]]. The focus was on Agenda and
|
||||
|
|
@ -229,7 +220,6 @@ Also, as much as tree-sitter is powerful, its main purpose is to parse
|
|||
programming languages, which mostly has "static" patterns to match. Orgmode is
|
||||
by its nature dynamic, which causes a variety of issues for a parser that's not
|
||||
meant for that kind of usage.
|
||||
|
||||
* Limitations
|
||||
|
||||
(Neo)Vim is a great editor, but it still cannot compare to Emacs in certain
|
||||
|
|
@ -239,7 +229,6 @@ certain things.
|
|||
I even [[https://github.com/nvim-orgmode/orgmode/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aneovim-dependency][made a label]] for reported issues where Neovim support for certain things
|
||||
is a blocker. I'm hoping that at least some of these will be available in future
|
||||
Neovim releases.
|
||||
|
||||
* Features
|
||||
|
||||
I will not go into too many details about the available features, since those
|
||||
|
|
@ -250,7 +239,6 @@ This allows getting a "desktop notification" for tasks that are within
|
|||
the specified threshold for schedule/deadline time. It requires some
|
||||
configuration to set up a cron job, but it's been working great for me
|
||||
for several months now.
|
||||
|
||||
* Plans
|
||||
|
||||
The current state of the project is very usable for me. I'm not lacking any of
|
||||
|
|
@ -276,7 +264,6 @@ And a long term goal for these:
|
|||
- [[https://github.com/nvim-orgmode/orgmode/issues/135][Custom agenda commands]]
|
||||
- More clocking features (reports)
|
||||
- File specific configuration via directives ([[https://github.com/nvim-orgmode/orgmode/issues/185][todo keywords]], properties, etc.)
|
||||
|
||||
* Closing thoughts
|
||||
|
||||
When I started working on [[https://github.com/nvim-orgmode/orgmode][nvim-orgmode]], I didn't have a clue what I'm jumping
|
||||
|
|
@ -0,0 +1,414 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>2022-02-30-orgnvim.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">February 2022
|
||||
</span><span style="color: #9e9e9e;">#+subtitle:</span> An orgmode clone for neovim
|
||||
<span style="color: #9e9e9e;">#+author:</span> Kristijan Husak
|
||||
<span style="color: #9e9e9e;">#+date:</span> 2022-02-30
|
||||
|
||||
Timothy (TEC) here. This month we have a guest post from a different part of the
|
||||
Org ecosystem, to highlight one of the most promising efforts to provide a good
|
||||
experience outside Emacs.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[Https://github.com/nvim-orgmode/orgmode]]</span>
|
||||
|
||||
"But I use Emacs, I don't care" you may say. In that case, I'd like to point out
|
||||
that wider spread and better Org support enriches the Org ecosystem as a whole.
|
||||
It makes the format more approachable, and <span class="ef-i">/useful/</span> for other people. This is good
|
||||
for everybody.
|
||||
|
||||
Without any further ado, here's the guest post kindly written by Kristijan.
|
||||
Enjoy!
|
||||
|
||||
-----
|
||||
|
||||
Like every beginner Vim user, at some point I ran into a usual editor war post:
|
||||
Vim vs Emacs. At that time, I didn't have an idea what "Emacs" was.
|
||||
|
||||
A simple Google search yielded something that seemed just like a very simple
|
||||
editor with strange, but more familiar shortcuts. I didn't bother too much to
|
||||
figure out what it is, because I was already pulled in fairly deep into Vim and
|
||||
its philosophy.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Note taking in (Neo)Vim</span>
|
||||
|
||||
At first, I did some note taking only when really necessary, in random
|
||||
plain text files. Most of the things I managed to keep in my head, since
|
||||
I was younger and less busy 🙂.
|
||||
|
||||
Once I got into the situation where I needed to keep more notes, <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/vimwiki/vimwiki][vimwiki]]</span> was the
|
||||
natural choice.
|
||||
|
||||
That worked very well for a period, until the need for writing quick notes
|
||||
arise. Vimwiki didn't have anything that would allow that. I could of course
|
||||
have a mapping that opens a specific file where I can add notes, but that just
|
||||
never felt right in my mind. I would keep a bunch of things in the same place,
|
||||
and then later I needed to spend some time organizing them.
|
||||
|
||||
At that point, I wasn't sure how to achieve what I want. I did a brief look at
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[https://orgmode.org/][Emacs OrgMode]]</span> to see what's all the fuss about, but to me, it seemed just like a
|
||||
different version of Markdown. You put some unordered lists as your notes, and
|
||||
that's it. I never spent more time trying to see all the neat features. I even
|
||||
tried creating some of my custom note taking tools, but I never managed to
|
||||
finish them because I didn't have a clear idea of how to solve my problems.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* First encounter with Orgmode like tool: vim-dotoo</span>
|
||||
|
||||
One weekend, I was browsing through Vim subreddit, as I usually do at least once
|
||||
a day. There was a post about an "Orgmode like task logging" plugin called
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/dhruvasagar/vim-dotoo][vim-dotoo]]</span>. I opened it up, and I didn't see much at that point. I wasn't too
|
||||
excited. I went through readme, and noticed that author (<span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/dhruvasagar][dhruvasagar]]</span>) put a
|
||||
fairly big emphasis on the "Agenda view". I had no idea what "Agenda view" is.
|
||||
Thankfully, the author also made a <span style="color: #3b6ea8; font-weight: 700;">[[https://www.youtube.com/watch?v=nsv33iOnH34][screencast]]</span>, which is rather long (1.5h), but
|
||||
I had some time, so I went through it.
|
||||
|
||||
At that point, I was first met with "Capturing" and "Refiling". <span class="ef-b">*My mind was
|
||||
blown!*</span> What a simple, yet extremely powerful idea! How had that never crossed my
|
||||
mind? From that point on, this plugin had my full attention.
|
||||
|
||||
I'm always emphasizing that <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/dhruvasagar][dhruvasagar]]</span> and his <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/dhruvasagar/vim-dotoo][vim-dotoo]]</span> plugin are most
|
||||
deserving for having inspired <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/nvim-orgmode/orgmode]]</span>, and I
|
||||
can't thank him enough for that.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* First steps with vim-dotoo and birth of orgmode.nvim</span>
|
||||
|
||||
For some time, I was using <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/dhruvasagar/vim-dotoo][vim-dotoo]]</span>. I moved all of my Vimwiki notes to it. It
|
||||
was a breath of fresh air. Alongside that, I started getting more interest in
|
||||
the original Emacs Orgmode. I started noticing the differences, and some of the
|
||||
missing features that were now looking quite attractive. I made <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/dhruvasagar/vim-dotoo/pulls?q=is%3Apr+sort%3Aupdated-desc+author%3Akristijanhusak+is%3Aclosed][few
|
||||
contributions]]</span> to vim-dotoo. As time passed, and my notes started to grow, things
|
||||
began being slow. I did some profiling, and figured out that it's just a usual
|
||||
Vim problem, Vimscript performance. It was just too slow for certain things that
|
||||
Orgmode provides, and it would hardly get any better as more things are added.
|
||||
|
||||
Separately from Vim and Vimscript, <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/neovim/neovim][Neovim]]</span> was on a stable <span style="color: #9e9e9e;">=v0.4=</span> release, and <span style="color: #9e9e9e;">=v0.5=</span>
|
||||
was still being developed. I was using Neovim from version 0.3, and was
|
||||
carefully following the progress on it. Lua was introduced as a first class
|
||||
citizen. A Bunch of new plugins arise from it. All the benchmarks showed that
|
||||
Lua outperforms Vimscript in almost everything. Besides the performance, Lua is
|
||||
a "normal" programming language, which means that support for it is much better.
|
||||
|
||||
At that point, I became curious: Could Lua be the path to the faster Orgmode? I
|
||||
spent several days thinking about it. I wanted to give it a try. My biggest
|
||||
concern was that I had absolutely zero experience writing parsers. I had never
|
||||
written anything more complicated than an averagely complicated regex for
|
||||
purposes of parsing. I noticed that vim-dotoo also used regex to do the parsing,
|
||||
so that eased my mind a bit.
|
||||
|
||||
One weekend, I started working on it. It was really interesting and challenging.
|
||||
I spent a lot of my free time on it. At certain points, it seemed like hacking,
|
||||
since it was not a proper parsing. I tried to learn how to write a proper
|
||||
parser, but it was just too time consuming and complicated. I proceeded with the
|
||||
regex parsing to see how far I can go.
|
||||
|
||||
Besides parsing, I had a few more challenges to overcome:
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Understanding the OrgMode syntax and all the functionality</span>
|
||||
|
||||
This is still the biggest challenge. I didn't have any idea how big and robust
|
||||
OrgMode is. If I would know it at that time, I wouldn't even jump on this train.
|
||||
It's really hard to grasp all of it. Considering I've only used it for around 8
|
||||
months, I think I made some good progress on learning it.
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Remote editing</span>
|
||||
|
||||
By remote editing, I mean automatically updating content in the current
|
||||
or any other file. Few examples: adding/updating properties, managing
|
||||
tags, changing TODO states, archiving, refiling, remote editing from
|
||||
agenda view, etc.
|
||||
|
||||
There is no built-in way to update content in another file through the
|
||||
Neovim API, without actually opening the file in an editor. I solved
|
||||
this by:
|
||||
|
||||
- Saving as much position information as possible in the internal state,
|
||||
so I can pinpoint the correct location
|
||||
- Opening a file in a <span style="color: #9e9e9e;">=1 row x 1 col=</span> floating window and doing quick
|
||||
edits there
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Working with dates</span>
|
||||
|
||||
From my experience, dates are challenging in all areas of programming,
|
||||
so this is not so surprising. There are some Lua plugins for dates, but
|
||||
those seemed a bit too basic for my use case, and I wanted to keep
|
||||
external plugins to the minimum. I went with a custom solution that uses
|
||||
Lua's native dates, which has certain limitations, but works out for
|
||||
most of the things.
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Highlighting, mostly in Agenda view</span>
|
||||
|
||||
Vim's syntax engine is fairly old, but still very much used, especially
|
||||
in the Vim community. Implementation of tree-sitter slightly improved
|
||||
this experience in Neovim, because "Highlight matches" are found via
|
||||
tree-sitter, instead of a bunch of regexes.
|
||||
|
||||
This helped me out later for the Org file itself, but agenda view is
|
||||
still something that's built as a custom view. Old Syntax highlight engine
|
||||
would be really hard to add, because the content is too dynamic. I went
|
||||
with the Neovim highlight API that allows Highlighting things by their
|
||||
exact position in the buffer. Tree-sitter implementation does something
|
||||
similar in the background for Highlighting.
|
||||
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Keeping configuration simple and familiar to Emacs OrgMode</span>
|
||||
|
||||
Vim-dotoo configuration was mostly Vim style, through some global
|
||||
variables. I wanted to have a configuration that is familiar to an Emacs
|
||||
OrgMode user, by having as many options as possible named completely the
|
||||
same as in Emacs.
|
||||
|
||||
For example, Here's a comparison of few options between Emacs and
|
||||
Neovim:
|
||||
|
||||
Emacs:
|
||||
|
||||
<span class="ef-obb">#+begin_src elisp
|
||||
</span><span class="ef-ob">(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">setq</span><span class="ef-ob"> org-agenda-files '(</span><span style="color: #4f894c; background-color: #e0e0e0;">"~/orgmodes"</span><span class="ef-ob">))
|
||||
(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">setq</span><span class="ef-ob"> org-agenda-skip-scheduled-if-done t)
|
||||
(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">setq</span><span class="ef-ob"> org-agenda-span 7)
|
||||
(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">setq</span><span class="ef-ob"> org-hide-leading-stars t)
|
||||
(</span><span style="color: #3b6ea8; background-color: #e0e0e0;">setq</span><span class="ef-ob"> org-capture-templates
|
||||
'((</span><span style="color: #4f894c; background-color: #e0e0e0;">"t"</span> <span style="color: #4f894c; background-color: #e0e0e0;">"Todo"</span><span class="ef-ob"> entry (file </span><span style="color: #4f894c; background-color: #e0e0e0;">"~/orgmodes/todos.org"</span><span class="ef-ob">)
|
||||
</span><span style="color: #4f894c; background-color: #e0e0e0;">"* TODO %?"</span><span class="ef-ob">)
|
||||
(</span><span style="color: #4f894c; background-color: #e0e0e0;">"j"</span> <span style="color: #4f894c; background-color: #e0e0e0;">"Journal"</span><span class="ef-ob"> entry (file </span><span style="color: #4f894c; background-color: #e0e0e0;">"~/orgmodes/journal.org"</span><span class="ef-ob">)
|
||||
</span><span style="color: #4f894c; background-color: #e0e0e0;">"* %?\nEntered on %U\n %a"</span><span class="ef-ob">)))
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
Neovim:
|
||||
|
||||
<span class="ef-obb">#+begin_src lua
|
||||
</span><span class="ef-ob">require('orgmode').setup({
|
||||
org_agenda_files = { '~/orgmodes' },
|
||||
org_agenda_skip_scheduled_if_done = true,
|
||||
org_agenda_span = 7,
|
||||
org_hide_leading_stars = true
|
||||
org_capture_templates = {
|
||||
t = {
|
||||
description = 'Todo',
|
||||
target = '~/orgmodes/todos.org',
|
||||
template = '* TODO %?',
|
||||
},
|
||||
j = {
|
||||
description = 'Journal',
|
||||
target = '~/orgmodes/journal.org',
|
||||
template = '* %?\nEntered on %U\n %a',
|
||||
}
|
||||
}
|
||||
})
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
One of the most noticeable differences is between the usage of hyphens
|
||||
(<span style="color: #9e9e9e;">=-</span><span style="color: #9e9e9e;">=</span><span style="color: #9e9e9e;">) and underscores (</span><span style="color: #9e9e9e;">=_=</span>). I did that only for the sake of simplicity,
|
||||
because hyphens is not a valid character in variable names in Lua, so
|
||||
all of the options would need to be wrapped as a string (for example:
|
||||
<span style="color: #9e9e9e;">=['org-agenda-files']=</span>).
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* First release of orgmode.nvim and introduction of tree-sitter parser</span>
|
||||
|
||||
After ~1.5 months I <span style="color: #3b6ea8; font-weight: 700;">[[https://www.reddit.com/r/neovim/comments/o8zp0k/orgmodenvim_orgmode_clone_written_in_lua_for/][published the initial version]]</span>. The focus was on Agenda and
|
||||
capturing (GTD), since those are the things I mostly used. It got some traction,
|
||||
and people started testing it and reporting bugs.
|
||||
|
||||
One of the common questions was: <span class="ef-i">/"Any plans to introduce tree-sitter parser?"/</span>.
|
||||
|
||||
I knew about <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/tree-sitter/tree-sitter][tree-sitter]]</span> and used it in my day-to-day job for a few programming
|
||||
languages, but I had absolutely no idea how it worked, and especially how to
|
||||
write a tree-sitter parser. I put it aside, and continued working on what I
|
||||
had.
|
||||
|
||||
One day, Emilia (<span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/milisims][milisims]]</span>) contacted me via email to ask me if I would be
|
||||
willing to try the tree-sitter parser she's been working on for some time. I
|
||||
gladly accepted. She gave me access to the repository, and I started tinkering
|
||||
with it in a separate branch. No one was aware at that point that tree-sitter
|
||||
support would happen some time soon.
|
||||
|
||||
After some time, I set up a "beta" branch called "tree-sitter" and <span style="color: #3b6ea8; font-weight: 700;">[[https://www.reddit.com/r/neovim/comments/ph2xqc/orgmodenvim_treesitter_support/][announced it
|
||||
for testing]]</span>. Once the reported bugs slowed to a trickle, I merged it into the
|
||||
"master" branch.
|
||||
|
||||
I believe that tree-sitter grammar for Org could help out other editors to
|
||||
implement their version of Orgmode plugin, but I don't think it would ever be
|
||||
helpful for Emacs. Emacs parser is the one and only that has it all implemented.
|
||||
Also, as much as tree-sitter is powerful, its main purpose is to parse
|
||||
programming languages, which mostly has "static" patterns to match. Orgmode is
|
||||
by its nature dynamic, which causes a variety of issues for a parser that's not
|
||||
meant for that kind of usage.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Limitations</span>
|
||||
|
||||
(Neo)Vim is a great editor, but it still cannot compare to Emacs in certain
|
||||
things. Manipulating the "View" part of the editor is tricky or impossible for
|
||||
certain things.
|
||||
|
||||
I even <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/nvim-orgmode/orgmode/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aneovim-dependency][made a label]]</span> for reported issues where Neovim support for certain things
|
||||
is a blocker. I'm hoping that at least some of these will be available in future
|
||||
Neovim releases.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Features</span>
|
||||
|
||||
I will not go into too many details about the available features, since those
|
||||
can be viewed in <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/nvim-orgmode/orgmode#features-detailed-breakdown][repository readme]]</span>, but I want to mention one feature that does
|
||||
not exist as a built/-in feature in the Emacs Orgmode: <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/nvim-orgmode/orgmode/blob/master/DOCS.md#notifications-experimental][Notifications]]</span>.
|
||||
|
||||
This allows getting a "desktop notification" for tasks that are within
|
||||
the specified threshold for schedule/deadline time. It requires some
|
||||
configuration to set up a cron job, but it's been working great for me
|
||||
for several months now.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Plans</span>
|
||||
|
||||
The current state of the project is very usable for me. I'm not lacking any of
|
||||
the major features, mostly because I'm not used to using them. Nevertheless,
|
||||
there are plans to add more things, and I'm getting a lot of help from the
|
||||
community. I want to specifically mention <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/levouh][levouh]]</span> and <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/lukas-reineke][lukas-reineke]]</span>, since they
|
||||
added a lot of value to the project, and I want to thank them and everyone else
|
||||
who contributed. Their help is much appreciated.
|
||||
|
||||
There are few high priority tasks that I'm hoping to flush out first:
|
||||
|
||||
- Implementing <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/milisims/tree-sitter-org/issues/13][v1.0.0]]</span> release of the tree-sitter parser. This should allow for
|
||||
faster and less error-prone parsing.
|
||||
- <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/nvim-orgmode/orgmode/issues/26][Infrastructure for plugin developers]]</span>, to allow other people to build plugins
|
||||
on top of nvim-orgmode.
|
||||
|
||||
And a long term goal for these:
|
||||
|
||||
- Tables support (and at least basic formulas)
|
||||
- <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/nvim-orgmode/orgmode/issues/190][Org Babel like code block evaluation]]</span> (and hopefully basic support for literate
|
||||
programming)
|
||||
- <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/nvim-orgmode/orgmode/issues/195][Diary format dates]]</span>
|
||||
- <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/nvim-orgmode/orgmode/issues/135][Custom agenda commands]]</span>
|
||||
- More clocking features (reports)
|
||||
- File specific configuration via directives (<span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/nvim-orgmode/orgmode/issues/185][todo keywords]]</span>, properties, etc.)
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Closing thoughts</span>
|
||||
|
||||
When I started working on <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/nvim-orgmode/orgmode][nvim-orgmode]]</span>, I didn't have a clue what I'm jumping
|
||||
into. Every day I learn about more and more Orgmode features that I wasn't even
|
||||
aware existed.
|
||||
|
||||
I'm certain that this project will never manage to clone the Orgmode
|
||||
functionality completely, but I'm hoping it will get close enough so everyone
|
||||
from Neovim community and Emacsers trying out Neovim will be able to use it for
|
||||
their needs.
|
||||
|
||||
Having experienced Orgmode users <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/nvim-orgmode/orgmode/issues/159][testing]]</span> it is a huge help, so if anyone is
|
||||
willing to give it a try, feel free to open up an issue and write your thoughts
|
||||
there. Thanks!
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,412 @@
|
|||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
FEBRUARY 2022
|
||||
An orgmode clone for neovim
|
||||
|
||||
Kristijan Husak
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
|
||||
2022-02-30
|
||||
|
||||
|
||||
Timothy (TEC) here. This month we have a guest post from a different
|
||||
part of the Org ecosystem, to highlight one of the most promising
|
||||
efforts to provide a good experience outside Emacs.
|
||||
|
||||
//github.com/nvim-orgmode/orgmode
|
||||
|
||||
“But I use Emacs, I don’t care” you may say. In that case, I’d like to
|
||||
point out that wider spread and better Org support enriches the Org
|
||||
ecosystem as a whole. It makes the format more approachable, and
|
||||
/useful/ for other people. This is good for everybody.
|
||||
|
||||
Without any further ado, here’s the guest post kindly written by
|
||||
Kristijan. Enjoy!
|
||||
|
||||
――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
|
||||
|
||||
Like every beginner Vim user, at some point I ran into a usual editor
|
||||
war post: Vim vs Emacs. At that time, I didn’t have an idea what “Emacs”
|
||||
was.
|
||||
|
||||
A simple Google search yielded something that seemed just like a very
|
||||
simple editor with strange, but more familiar shortcuts. I didn’t bother
|
||||
too much to figure out what it is, because I was already pulled in
|
||||
fairly deep into Vim and its philosophy.
|
||||
|
||||
|
||||
Note taking in (Neo)Vim
|
||||
═══════════════════════
|
||||
|
||||
At first, I did some note taking only when really necessary, in random
|
||||
plain text files. Most of the things I managed to keep in my head,
|
||||
since I was younger and less busy 🙂.
|
||||
|
||||
Once I got into the situation where I needed to keep more notes,
|
||||
[vimwiki] was the natural choice.
|
||||
|
||||
That worked very well for a period, until the need for writing quick
|
||||
notes arise. Vimwiki didn’t have anything that would allow that. I
|
||||
could of course have a mapping that opens a specific file where I can
|
||||
add notes, but that just never felt right in my mind. I would keep a
|
||||
bunch of things in the same place, and then later I needed to spend
|
||||
some time organizing them.
|
||||
|
||||
At that point, I wasn’t sure how to achieve what I want. I did a brief
|
||||
look at [Emacs OrgMode] to see what’s all the fuss about, but to me,
|
||||
it seemed just like a different version of Markdown. You put some
|
||||
unordered lists as your notes, and that’s it. I never spent more time
|
||||
trying to see all the neat features. I even tried creating some of my
|
||||
custom note taking tools, but I never managed to finish them because I
|
||||
didn’t have a clear idea of how to solve my problems.
|
||||
|
||||
|
||||
[vimwiki] <https://github.com/vimwiki/vimwiki>
|
||||
|
||||
[Emacs OrgMode] <https://orgmode.org/>
|
||||
|
||||
|
||||
First encounter with Orgmode like tool: vim-dotoo
|
||||
═════════════════════════════════════════════════
|
||||
|
||||
One weekend, I was browsing through Vim subreddit, as I usually do at
|
||||
least once a day. There was a post about an “Orgmode like task
|
||||
logging” plugin called [vim-dotoo]. I opened it up, and I didn’t see
|
||||
much at that point. I wasn’t too excited. I went through readme, and
|
||||
noticed that author ([dhruvasagar]) put a fairly big emphasis on the
|
||||
“Agenda view”. I had no idea what “Agenda view” is. Thankfully, the
|
||||
author also made a [screencast], which is rather long (1.5h), but I
|
||||
had some time, so I went through it.
|
||||
|
||||
At that point, I was first met with “Capturing” and “Refiling”. *My
|
||||
mind was blown!* What a simple, yet extremely powerful idea! How had
|
||||
that never crossed my mind? From that point on, this plugin had my
|
||||
full attention.
|
||||
|
||||
I’m always emphasizing that [dhruvasagar] and his [vim-dotoo] plugin
|
||||
are most deserving for having inspired
|
||||
<https://github.com/nvim-orgmode/orgmode>, and I can’t thank him
|
||||
enough for that.
|
||||
|
||||
|
||||
[vim-dotoo] <https://github.com/dhruvasagar/vim-dotoo>
|
||||
|
||||
[dhruvasagar] <https://github.com/dhruvasagar>
|
||||
|
||||
[screencast] <https://www.youtube.com/watch?v=nsv33iOnH34>
|
||||
|
||||
|
||||
First steps with vim-dotoo and birth of orgmode.nvim
|
||||
════════════════════════════════════════════════════
|
||||
|
||||
For some time, I was using [vim-dotoo]. I moved all of my Vimwiki
|
||||
notes to it. It was a breath of fresh air. Alongside that, I started
|
||||
getting more interest in the original Emacs Orgmode. I started
|
||||
noticing the differences, and some of the missing features that were
|
||||
now looking quite attractive. I made [few contributions] to
|
||||
vim-dotoo. As time passed, and my notes started to grow, things began
|
||||
being slow. I did some profiling, and figured out that it’s just a
|
||||
usual Vim problem, Vimscript performance. It was just too slow for
|
||||
certain things that Orgmode provides, and it would hardly get any
|
||||
better as more things are added.
|
||||
|
||||
Separately from Vim and Vimscript, [Neovim] was on a stable `v0.4'
|
||||
release, and `v0.5' was still being developed. I was using Neovim from
|
||||
version 0.3, and was carefully following the progress on it. Lua was
|
||||
introduced as a first class citizen. A Bunch of new plugins arise from
|
||||
it. All the benchmarks showed that Lua outperforms Vimscript in almost
|
||||
everything. Besides the performance, Lua is a “normal” programming
|
||||
language, which means that support for it is much better.
|
||||
|
||||
At that point, I became curious: Could Lua be the path to the faster
|
||||
Orgmode? I spent several days thinking about it. I wanted to give it a
|
||||
try. My biggest concern was that I had absolutely zero experience
|
||||
writing parsers. I had never written anything more complicated than an
|
||||
averagely complicated regex for purposes of parsing. I noticed that
|
||||
vim-dotoo also used regex to do the parsing, so that eased my mind a
|
||||
bit.
|
||||
|
||||
One weekend, I started working on it. It was really interesting and
|
||||
challenging. I spent a lot of my free time on it. At certain points,
|
||||
it seemed like hacking, since it was not a proper parsing. I tried to
|
||||
learn how to write a proper parser, but it was just too time consuming
|
||||
and complicated. I proceeded with the regex parsing to see how far I
|
||||
can go.
|
||||
|
||||
Besides parsing, I had a few more challenges to overcome:
|
||||
|
||||
|
||||
[vim-dotoo] <https://github.com/dhruvasagar/vim-dotoo>
|
||||
|
||||
[few contributions]
|
||||
<https://github.com/dhruvasagar/vim-dotoo/pulls?q=is%3Apr+sort%3Aupdated-desc+author%3Akristijanhusak+is%3Aclosed>
|
||||
|
||||
[Neovim] <https://github.com/neovim/neovim>
|
||||
|
||||
Understanding the OrgMode syntax and all the functionality
|
||||
──────────────────────────────────────────────────────────
|
||||
|
||||
This is still the biggest challenge. I didn’t have any idea how big
|
||||
and robust OrgMode is. If I would know it at that time, I wouldn’t
|
||||
even jump on this train. It’s really hard to grasp all of
|
||||
it. Considering I’ve only used it for around 8 months, I think I made
|
||||
some good progress on learning it.
|
||||
|
||||
|
||||
Remote editing
|
||||
──────────────
|
||||
|
||||
By remote editing, I mean automatically updating content in the
|
||||
current or any other file. Few examples: adding/updating properties,
|
||||
managing tags, changing TODO states, archiving, refiling, remote
|
||||
editing from agenda view, etc.
|
||||
|
||||
There is no built-in way to update content in another file through the
|
||||
Neovim API, without actually opening the file in an editor. I solved
|
||||
this by:
|
||||
|
||||
• Saving as much position information as possible in the internal
|
||||
state, so I can pinpoint the correct location
|
||||
• Opening a file in a `1 row x 1 col' floating window and doing quick
|
||||
edits there
|
||||
|
||||
|
||||
Working with dates
|
||||
──────────────────
|
||||
|
||||
From my experience, dates are challenging in all areas of programming,
|
||||
so this is not so surprising. There are some Lua plugins for dates,
|
||||
but those seemed a bit too basic for my use case, and I wanted to keep
|
||||
external plugins to the minimum. I went with a custom solution that
|
||||
uses Lua’s native dates, which has certain limitations, but works out
|
||||
for most of the things.
|
||||
|
||||
|
||||
Highlighting, mostly in Agenda view
|
||||
───────────────────────────────────
|
||||
|
||||
Vim’s syntax engine is fairly old, but still very much used,
|
||||
especially in the Vim community. Implementation of tree-sitter
|
||||
slightly improved this experience in Neovim, because “Highlight
|
||||
matches” are found via tree-sitter, instead of a bunch of regexes.
|
||||
|
||||
This helped me out later for the Org file itself, but agenda view is
|
||||
still something that’s built as a custom view. Old Syntax highlight
|
||||
engine would be really hard to add, because the content is too
|
||||
dynamic. I went with the Neovim highlight API that allows Highlighting
|
||||
things by their exact position in the buffer. Tree-sitter
|
||||
implementation does something similar in the background for
|
||||
Highlighting.
|
||||
|
||||
|
||||
Keeping configuration simple and familiar to Emacs OrgMode
|
||||
──────────────────────────────────────────────────────────
|
||||
|
||||
Vim-dotoo configuration was mostly Vim style, through some global
|
||||
variables. I wanted to have a configuration that is familiar to an
|
||||
Emacs OrgMode user, by having as many options as possible named
|
||||
completely the same as in Emacs.
|
||||
|
||||
For example, Here’s a comparison of few options between Emacs and
|
||||
Neovim:
|
||||
|
||||
Emacs:
|
||||
|
||||
┌────
|
||||
│ (setq org-agenda-files '("~/orgmodes"))
|
||||
│ (setq org-agenda-skip-scheduled-if-done t)
|
||||
│ (setq org-agenda-span 7)
|
||||
│ (setq org-hide-leading-stars t)
|
||||
│ (setq org-capture-templates
|
||||
│ '(("t" "Todo" entry (file "~/orgmodes/todos.org")
|
||||
│ "* TODO %?")
|
||||
│ ("j" "Journal" entry (file "~/orgmodes/journal.org")
|
||||
│ "* %?\nEntered on %U\n %a")))
|
||||
└────
|
||||
|
||||
Neovim:
|
||||
|
||||
┌────
|
||||
│ require('orgmode').setup({
|
||||
│ org_agenda_files = { '~/orgmodes' },
|
||||
│ org_agenda_skip_scheduled_if_done = true,
|
||||
│ org_agenda_span = 7,
|
||||
│ org_hide_leading_stars = true
|
||||
│ org_capture_templates = {
|
||||
│ t = {
|
||||
│ description = 'Todo',
|
||||
│ target = '~/orgmodes/todos.org',
|
||||
│ template = '* TODO %?',
|
||||
│ },
|
||||
│ j = {
|
||||
│ description = 'Journal',
|
||||
│ target = '~/orgmodes/journal.org',
|
||||
│ template = '* %?\nEntered on %U\n %a',
|
||||
│ }
|
||||
│ }
|
||||
│ })
|
||||
└────
|
||||
|
||||
One of the most noticeable differences is between the usage of hyphens
|
||||
(`-') and underscores (`_'). I did that only for the sake of
|
||||
simplicity, because hyphens is not a valid character in variable names
|
||||
in Lua, so all of the options would need to be wrapped as a string
|
||||
(for example: `['org-agenda-files']').
|
||||
|
||||
|
||||
First release of orgmode.nvim and introduction of tree-sitter parser
|
||||
════════════════════════════════════════════════════════════════════
|
||||
|
||||
After ~1.5 months I [published the initial version]. The focus was on
|
||||
Agenda and capturing (GTD), since those are the things I mostly
|
||||
used. It got some traction, and people started testing it and
|
||||
reporting bugs.
|
||||
|
||||
One of the common questions was: /“Any plans to introduce tree-sitter
|
||||
parser?”/.
|
||||
|
||||
I knew about [tree-sitter] and used it in my day-to-day job for a few
|
||||
programming languages, but I had absolutely no idea how it worked, and
|
||||
especially how to write a tree-sitter parser. I put it aside, and
|
||||
continued working on what I had.
|
||||
|
||||
One day, Emilia ([milisims]) contacted me via email to ask me if I
|
||||
would be willing to try the tree-sitter parser she’s been working on
|
||||
for some time. I gladly accepted. She gave me access to the
|
||||
repository, and I started tinkering with it in a separate branch. No
|
||||
one was aware at that point that tree-sitter support would happen some
|
||||
time soon.
|
||||
|
||||
After some time, I set up a “beta” branch called “tree-sitter” and
|
||||
[announced it for testing]. Once the reported bugs slowed to a
|
||||
trickle, I merged it into the “master” branch.
|
||||
|
||||
I believe that tree-sitter grammar for Org could help out other
|
||||
editors to implement their version of Orgmode plugin, but I don’t
|
||||
think it would ever be helpful for Emacs. Emacs parser is the one and
|
||||
only that has it all implemented. Also, as much as tree-sitter is
|
||||
powerful, its main purpose is to parse programming languages, which
|
||||
mostly has “static” patterns to match. Orgmode is by its nature
|
||||
dynamic, which causes a variety of issues for a parser that’s not
|
||||
meant for that kind of usage.
|
||||
|
||||
|
||||
[published the initial version]
|
||||
<https://www.reddit.com/r/neovim/comments/o8zp0k/orgmodenvim_orgmode_clone_written_in_lua_for/>
|
||||
|
||||
[tree-sitter] <https://github.com/tree-sitter/tree-sitter>
|
||||
|
||||
[milisims] <https://github.com/milisims>
|
||||
|
||||
[announced it for testing]
|
||||
<https://www.reddit.com/r/neovim/comments/ph2xqc/orgmodenvim_treesitter_support/>
|
||||
|
||||
|
||||
Limitations
|
||||
═══════════
|
||||
|
||||
(Neo)Vim is a great editor, but it still cannot compare to Emacs in
|
||||
certain things. Manipulating the “View” part of the editor is tricky
|
||||
or impossible for certain things.
|
||||
|
||||
I even [made a label] for reported issues where Neovim support for
|
||||
certain things is a blocker. I’m hoping that at least some of these
|
||||
will be available in future Neovim releases.
|
||||
|
||||
|
||||
[made a label]
|
||||
<https://github.com/nvim-orgmode/orgmode/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aneovim-dependency>
|
||||
|
||||
|
||||
Features
|
||||
════════
|
||||
|
||||
I will not go into too many details about the available features,
|
||||
since those can be viewed in [repository readme], but I want to
|
||||
mention one feature that does not exist as a built/-in feature in the
|
||||
Emacs Orgmode: [Notifications].
|
||||
|
||||
This allows getting a “desktop notification” for tasks that are within
|
||||
the specified threshold for schedule/deadline time. It requires some
|
||||
configuration to set up a cron job, but it’s been working great for me
|
||||
for several months now.
|
||||
|
||||
|
||||
[repository readme]
|
||||
<https://github.com/nvim-orgmode/orgmode#features-detailed-breakdown>
|
||||
|
||||
[Notifications]
|
||||
<https://github.com/nvim-orgmode/orgmode/blob/master/DOCS.md#notifications-experimental>
|
||||
|
||||
|
||||
Plans
|
||||
═════
|
||||
|
||||
The current state of the project is very usable for me. I’m not
|
||||
lacking any of the major features, mostly because I’m not used to
|
||||
using them. Nevertheless, there are plans to add more things, and I’m
|
||||
getting a lot of help from the community. I want to specifically
|
||||
mention [levouh] and [lukas-reineke], since they added a lot of value
|
||||
to the project, and I want to thank them and everyone else who
|
||||
contributed. Their help is much appreciated.
|
||||
|
||||
There are few high priority tasks that I’m hoping to flush out first:
|
||||
|
||||
• Implementing [v1.0.0] release of the tree-sitter parser. This should
|
||||
allow for faster and less error-prone parsing.
|
||||
• [Infrastructure for plugin developers], to allow other people to
|
||||
build plugins on top of nvim-orgmode.
|
||||
|
||||
And a long term goal for these:
|
||||
|
||||
• Tables support (and at least basic formulas)
|
||||
• [Org Babel like code block evaluation] (and hopefully basic support
|
||||
for literate programming)
|
||||
• [Diary format dates]
|
||||
• [Custom agenda commands]
|
||||
• More clocking features (reports)
|
||||
• File specific configuration via directives ([todo keywords],
|
||||
properties, etc.)
|
||||
|
||||
|
||||
[levouh] <https://github.com/levouh>
|
||||
|
||||
[lukas-reineke] <https://github.com/lukas-reineke>
|
||||
|
||||
[v1.0.0] <https://github.com/milisims/tree-sitter-org/issues/13>
|
||||
|
||||
[Infrastructure for plugin developers]
|
||||
<https://github.com/nvim-orgmode/orgmode/issues/26>
|
||||
|
||||
[Org Babel like code block evaluation]
|
||||
<https://github.com/nvim-orgmode/orgmode/issues/190>
|
||||
|
||||
[Diary format dates]
|
||||
<https://github.com/nvim-orgmode/orgmode/issues/195>
|
||||
|
||||
[Custom agenda commands]
|
||||
<https://github.com/nvim-orgmode/orgmode/issues/135>
|
||||
|
||||
[todo keywords] <https://github.com/nvim-orgmode/orgmode/issues/185>
|
||||
|
||||
|
||||
Closing thoughts
|
||||
════════════════
|
||||
|
||||
When I started working on [nvim-orgmode], I didn’t have a clue what
|
||||
I’m jumping into. Every day I learn about more and more Orgmode
|
||||
features that I wasn’t even aware existed.
|
||||
|
||||
I’m certain that this project will never manage to clone the Orgmode
|
||||
functionality completely, but I’m hoping it will get close enough so
|
||||
everyone from Neovim community and Emacsers trying out Neovim will be
|
||||
able to use it for their needs.
|
||||
|
||||
Having experienced Orgmode users [testing] it is a huge help, so if
|
||||
anyone is willing to give it a try, feel free to open up an issue and
|
||||
write your thoughts there. Thanks!
|
||||
|
||||
|
||||
[nvim-orgmode] <https://github.com/nvim-orgmode/orgmode>
|
||||
|
||||
[testing] <https://github.com/nvim-orgmode/orgmode/issues/159>
|
||||
|
|
@ -0,0 +1,117 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-12 Fri 13:39 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>Special Announcement</title>
|
||||
<meta name="author" content="TEC" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="Special Announcement" />
|
||||
<meta property="og:description" content="Throwing in the towel and jumping on the bandwagon" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="TEC" />
|
||||
<meta property="og:article:published_time" content="2022-04-01T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2022-04-02T00:37:30+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2022-04-01, <span class='acr'>TEC</span></div>
|
||||
|
||||
<h1 class="title">Special Announcement</h1>
|
||||
<p class="subtitle" role="doc-subtitle">Throwing in the towel and jumping on the bandwagon</p>
|
||||
</header><p>
|
||||
It <b>h</b>as become apparent to the Org Mode developers that Org is suffering from a
|
||||
severe lack of enterprise adoption. To r<b>e</b>ctify this, we will be leveraging our
|
||||
collective decades working on holistic human-markup interaction tools to rapid<b>l</b>y
|
||||
pivot to what we believe to be the <i>true</i> markup format of the future —
|
||||
<a href="https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html">Confluence Wiki Markup</a>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
With this <b>p</b>aradigm shift, you can look forward to a much more intuitive syntax,
|
||||
empowering you to create next-generation agile documents.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
To assist you in this <b>t</b>ransition, we’ll give you a brief overview of the changes
|
||||
you can expect. Text formatting is almost unaffected, with a few sensible
|
||||
changes made to the surrounding c<b>h</b>aracters.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org3ee46f3">
|
||||
<img src="figures/org-markup-to-confluence.svg" alt="org-markup-to-confluence.svg" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 1: </span>Translation between Org’s syntax and our new Confluence overlords’s equivalents</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
We’d like to thank the <span class='acr'>FSF</span> for giving the Org project the space and support to
|
||||
grow to become a world-class proj<b>e</b>ct. In our new venture, cop<b>y</b>right assignment
|
||||
to t<b>h</b>e <span class='acr'>FSF</span> is no longer required. Inste<b>a</b>d, copyright must be assigned to
|
||||
Atlassian prior to contributing.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
This new partnership enables new and exciting integrations with Atlassian’s
|
||||
proprietary technologies. O<b>v</b>er the next f<b>e</b>w months we will <b>b</b>e transforming Org
|
||||
to a cloud-n<b>a</b>tive serverless profes<b>s</b>ional markup offering. Unlike Confluence, we
|
||||
will allow you to bo<b>t</b>h write <i>and edit</i> documents using pla<b>i</b>ntext markup. We
|
||||
believe that by unlocking the synergy between plaintext and Confluence the Org
|
||||
project will become a thought leader in hyp<b>e</b>r-scale markup solutions.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The shift to Confluence wiki markup will come as a surprise to many of you, but
|
||||
after doing a deep dive into the scalability of Org we realised that there were
|
||||
no low-hanging fruit available — only out of the box thinking will allow for the
|
||||
in<b>n</b>ovation so many of our users crave.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
We hope this change will not just disrupt your documents, but the entire markup
|
||||
industry.
|
||||
</p>
|
||||
</div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,41 +1,40 @@
|
|||
# Created 2024-01-12 Fri 13:39
|
||||
#+title: Special Announcement
|
||||
#+subtitle: Throwing in the towel and jumping on the bandwagon
|
||||
#+author: TEC
|
||||
#+date: 2022-04-01
|
||||
|
||||
It *h*as become apparent to the Org Mode developers that Org is suffering from a
|
||||
severe lack of enterprise adoption. To r*e*ctify this, we will be leveraging our
|
||||
collective decades working on holistic human-markup interaction tools to rapid*l*y
|
||||
#+author: TEC
|
||||
#+subtitle: Throwing in the towel and jumping on the bandwagon
|
||||
It *h*as become apparent to the Org Mode developers that Org is suffering from a
|
||||
severe lack of enterprise adoption. To r*e*ctify this, we will be leveraging our
|
||||
collective decades working on holistic human-markup interaction tools to rapid*l*y
|
||||
pivot to what we believe to be the /true/ markup format of the future ---
|
||||
[[https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html][Confluence Wiki Markup]].
|
||||
|
||||
With this *p*aradigm shift, you can look forward to a much more intuitive syntax,
|
||||
With this *p*aradigm shift, you can look forward to a much more intuitive syntax,
|
||||
empowering you to create next-generation agile documents.
|
||||
|
||||
To assist you in this *t*ransition, we'll give you a brief overview of the changes
|
||||
To assist you in this *t*ransition, we'll give you a brief overview of the changes
|
||||
you can expect. Text formatting is almost unaffected, with a few sensible
|
||||
changes made to the surrounding c*h*aracters.
|
||||
changes made to the surrounding c*h*aracters.
|
||||
|
||||
#+caption: Translation between Org's syntax and our new Confluence overlords's equivalents
|
||||
#+attr_html: :class invertible
|
||||
[[file:figures/org-markup-to-confluence.svg]]
|
||||
|
||||
We'd like to thank the FSF for giving the Org project the space and support to
|
||||
grow to become a world-class proj*e*ct. In our new venture, cop*y*right assignment
|
||||
to t*h*e FSF is no longer required. Inste*a*d, copyright must be assigned to
|
||||
grow to become a world-class proj*e*ct. In our new venture, cop*y*right assignment
|
||||
to t*h*e FSF is no longer required. Inste*a*d, copyright must be assigned to
|
||||
Atlassian prior to contributing.
|
||||
|
||||
This new partnership enables new and exciting integrations with Atlassian's
|
||||
proprietary technologies. O*v*er the next f*e*w months we will *b*e transforming Org
|
||||
to a cloud-n*a*tive serverless profes*s*ional markup offering. Unlike Confluence, we
|
||||
will allow you to bo*t*h write /and edit/ documents using pla*i*ntext markup. We
|
||||
proprietary technologies. O*v*er the next f*e*w months we will *b*e transforming Org
|
||||
to a cloud-n*a*tive serverless profes*s*ional markup offering. Unlike Confluence, we
|
||||
will allow you to bo*t*h write /and edit/ documents using pla*i*ntext markup. We
|
||||
believe that by unlocking the synergy between plaintext and Confluence the Org
|
||||
project will become a thought leader in hyp*e*r-scale markup solutions.
|
||||
project will become a thought leader in hyp*e*r-scale markup solutions.
|
||||
|
||||
The shift to Confluence wiki markup will come as a surprise to many of you, but
|
||||
after doing a deep dive into the scalability of Org we realised that there were
|
||||
no low-hanging fruit available --- only out of the box thinking will allow for the
|
||||
in*n*ovation so many of our users crave.
|
||||
in*n*ovation so many of our users crave.
|
||||
|
||||
We hope this change will not just disrupt your documents, but the entire markup
|
||||
industry.
|
||||
|
|
@ -0,0 +1,162 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>2022-04-01-confluence.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">Special Announcement
|
||||
</span><span style="color: #9e9e9e;">#+subtitle:</span> Throwing in the towel and jumping on the bandwagon
|
||||
<span style="color: #9e9e9e;">#+author:</span> TEC
|
||||
<span style="color: #9e9e9e;">#+date:</span> 2022-04-01
|
||||
|
||||
It <span class="ef-b">*h*</span>as become apparent to the Org Mode developers that Org is suffering from a
|
||||
severe lack of enterprise adoption. To r<span class="ef-b">*e*</span>ctify this, we will be leveraging our
|
||||
collective decades working on holistic human-markup interaction tools to rapid<span class="ef-b">*l*</span>y
|
||||
pivot to what we believe to be the <span class="ef-i">/true/</span> markup format of the future ---
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html][Confluence Wiki Markup]]</span>.
|
||||
|
||||
With this <span class="ef-b">*p*</span>aradigm shift, you can look forward to a much more intuitive syntax,
|
||||
empowering you to create next-generation agile documents.
|
||||
|
||||
To assist you in this <span class="ef-b">*t*</span>ransition, we'll give you a brief overview of the changes
|
||||
you can expect. Text formatting is almost unaffected, with a few sensible
|
||||
changes made to the surrounding c<span class="ef-b">*h*</span>aracters.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Translation between Org's syntax and our new Confluence overlords's equivalents</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/org-markup-to-confluence.svg]]</span>
|
||||
|
||||
We'd like to thank the FSF for giving the Org project the space and support to
|
||||
grow to become a world-class proj<span class="ef-b">*e*</span>ct. In our new venture, cop<span class="ef-b">*y*</span>right assignment
|
||||
to t<span class="ef-b">*h*</span>e FSF is no longer required. Inste<span class="ef-b">*a*</span>d, copyright must be assigned to
|
||||
Atlassian prior to contributing.
|
||||
|
||||
This new partnership enables new and exciting integrations with Atlassian's
|
||||
proprietary technologies. O<span class="ef-b">*v*</span>er the next f<span class="ef-b">*e*</span>w months we will <span class="ef-b">*b*</span>e transforming Org
|
||||
to a cloud-n<span class="ef-b">*a*</span>tive serverless profes<span class="ef-b">*s*</span>ional markup offering. Unlike Confluence, we
|
||||
will allow you to bo<span class="ef-b">*t*</span>h write <span class="ef-i">/and edit/</span> documents using pla<span class="ef-b">*i*</span>ntext markup. We
|
||||
believe that by unlocking the synergy between plaintext and Confluence the Org
|
||||
project will become a thought leader in hyp<span class="ef-b">*e*</span>r-scale markup solutions.
|
||||
|
||||
The shift to Confluence wiki markup will come as a surprise to many of you, but
|
||||
after doing a deep dive into the scalability of Org we realised that there were
|
||||
no low-hanging fruit available --- only out of the box thinking will allow for the
|
||||
in<span class="ef-b">*n*</span>ovation so many of our users crave.
|
||||
|
||||
We hope this change will not just disrupt your documents, but the entire markup
|
||||
industry.
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
SPECIAL ANNOUNCEMENT
|
||||
Throwing in the towel and jumping on the
|
||||
bandwagon
|
||||
|
||||
TEC
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
|
||||
2022-04-01
|
||||
|
||||
|
||||
It *h*as become apparent to the Org Mode developers that Org is
|
||||
suffering from a severe lack of enterprise adoption. To r*e*ctify this,
|
||||
we will be leveraging our collective decades working on holistic
|
||||
human-markup interaction tools to rapid*l*y pivot to what we believe to
|
||||
be the /true/ markup format of the future — [Confluence Wiki Markup].
|
||||
|
||||
With this *p*aradigm shift, you can look forward to a much more
|
||||
intuitive syntax, empowering you to create next-generation agile
|
||||
documents.
|
||||
|
||||
To assist you in this *t*ransition, we’ll give you a brief overview of
|
||||
the changes you can expect. Text formatting is almost unaffected, with a
|
||||
few sensible changes made to the surrounding c*h*aracters.
|
||||
|
||||
<file:figures/org-markup-to-confluence.svg>
|
||||
|
||||
We’d like to thank the FSF for giving the Org project the space and
|
||||
support to grow to become a world-class proj*e*ct. In our new venture,
|
||||
cop*y*right assignment to t*h*e FSF is no longer required. Inste*a*d,
|
||||
copyright must be assigned to Atlassian prior to contributing.
|
||||
|
||||
This new partnership enables new and exciting integrations with
|
||||
Atlassian’s proprietary technologies. O*v*er the next f*e*w months we
|
||||
will *b*e transforming Org to a cloud-n*a*tive serverless profes*s*ional
|
||||
markup offering. Unlike Confluence, we will allow you to bo*t*h write
|
||||
/and edit/ documents using pla*i*ntext markup. We believe that by
|
||||
unlocking the synergy between plaintext and Confluence the Org project
|
||||
will become a thought leader in hyp*e*r-scale markup solutions.
|
||||
|
||||
The shift to Confluence wiki markup will come as a surprise to many of
|
||||
you, but after doing a deep dive into the scalability of Org we realised
|
||||
that there were no low-hanging fruit available — only out of the box
|
||||
thinking will allow for the in*n*ovation so many of our users crave.
|
||||
|
||||
We hope this change will not just disrupt your documents, but the entire
|
||||
markup industry.
|
||||
|
||||
|
||||
[Confluence Wiki Markup]
|
||||
<https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html>
|
||||
|
|
@ -0,0 +1,434 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-12 Fri 13:39 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>May 2022</title>
|
||||
<meta name="author" content="TEC" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="May 2022" />
|
||||
<meta property="og:description" content="Folding more improvement into Org" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="TEC" />
|
||||
<meta property="og:article:published_time" content="2022-05-31T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2022-06-02T00:52:03+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
<script>
|
||||
MathJax = {
|
||||
chtml: {
|
||||
scale: 1
|
||||
},
|
||||
svg: {
|
||||
scale: 1,
|
||||
fontCache: "global"
|
||||
},
|
||||
tex: {
|
||||
tags: "%AUTONUMBER",
|
||||
multlineWidth: "85%",
|
||||
tagSide: "right",
|
||||
tagIndent: ".8em"
|
||||
}
|
||||
};
|
||||
</script>
|
||||
<script id="MathJax-script" async
|
||||
src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2022-05-31, <span class='acr'>TEC</span></div>
|
||||
|
||||
<h1 class="title">May 2022</h1>
|
||||
<p class="subtitle" role="doc-subtitle">Folding more improvement into Org</p>
|
||||
</header><p>
|
||||
Finding time as of late has been more difficult than I anticipated, and on top
|
||||
of that, just as I was thinking of writing last month’s post, I got distracted
|
||||
by an exciting patchset that has been in the works for over a year finally
|
||||
getting sorted out and landing. So, I hope that some of the fun developments in
|
||||
this post will make up the absense of the last one 🙂.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Since it’s been longer than I thought since the last standard post, we’ve got a
|
||||
fair few commits to catch up on — about 200. Most of these are miscellaneous
|
||||
minor improvements and bugfixes, but a few notable changes have arrived too.
|
||||
</p>
|
||||
<div id="outline-container-folding" class="outline-2">
|
||||
<h2 id="folding">Folding<a aria-hidden="true" href="#folding">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-folding">
|
||||
<p>
|
||||
The fabulous new folding engine (<kbd>org-fold-core</kbd>) should noticeably improve Org’s
|
||||
performance with large files. It contains a number of key optimisations to
|
||||
improve speed, namely:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li>Deferring fontification of folded regions</li>
|
||||
<li>Using text properties (\(\mathcal{O}(n \log n)\)) instead of overlays (\(\mathcal{O}(n^2)\)) for folded regions</li>
|
||||
<li>A collection of aggressive optimisations available under <code>org-fold-core--optimise-for-huge-buffers</code></li>
|
||||
<li>Convert text properties to overlays for <kbd>isearch</kbd> (which currently only supports overlays)</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
How noticeable is the overall performance impact? Well, I poked Ihor and he was
|
||||
kind enough to whip up some benchmarks.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org7c32a15">
|
||||
<img src="figures/org-fold-perf-shifttab-contents.svg" alt="org-fold-perf-shifttab-contents.svg" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 1: </span>The scaling of <code>org-shifttab</code> showing file contents, as file size increases, with and without org-fold.</figcaption>
|
||||
</figure>
|
||||
|
||||
|
||||
<figure id="orgcaf3374">
|
||||
<img src="figures/org-fold-perf-shifttab-showall.svg" alt="org-fold-perf-shifttab-showall.svg" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 2: </span>The scaling of <code>org-shifttab</code> showing the entire file, as file size increases, with and without org-fold.</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
Well this looks very promising<sup><a id="fnr.1" class="footref" href="#fn.1" role="doc-backlink">1</a></sup>! Let’s see how much of an improvement this is overall.
|
||||
</p>
|
||||
|
||||
<div id='folding,table--1' class='table'>
|
||||
<div class='gutter'><a href='#folding,table--1'>#</a></div>
|
||||
<div class='tabular'>
|
||||
<table>
|
||||
<caption class="t-above"><span class="table-number">Table 1:</span> Time to run <kbd>org-shifttab</kbd> twice, cycling through all three display modes (in seconds).</caption>
|
||||
|
||||
<colgroup>
|
||||
<col class="org-right">
|
||||
|
||||
<col class="org-right">
|
||||
|
||||
<col class="org-right">
|
||||
|
||||
<col class="org-right">
|
||||
|
||||
<col class="org-right">
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr>
|
||||
<th scope="col" class="org-right">File size (Mb)</th>
|
||||
<th scope="col" class="org-right">Headings (thousands)</th>
|
||||
<th scope="col" class="org-right">Bugfix (no org-fold)</th>
|
||||
<th scope="col" class="org-right">Main (with org-fold)</th>
|
||||
<th scope="col" class="org-right">Improvement</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td class="org-right">18</td>
|
||||
<td class="org-right">36</td>
|
||||
<td class="org-right">115.31</td>
|
||||
<td class="org-right">0.89</td>
|
||||
<td class="org-right">99%</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-right">8.8</td>
|
||||
<td class="org-right">24</td>
|
||||
<td class="org-right">19.03</td>
|
||||
<td class="org-right">0.48</td>
|
||||
<td class="org-right">97%</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-right">4.4</td>
|
||||
<td class="org-right">5</td>
|
||||
<td class="org-right">3.79</td>
|
||||
<td class="org-right">0.13</td>
|
||||
<td class="org-right">97%</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-right">2.2</td>
|
||||
<td class="org-right">2</td>
|
||||
<td class="org-right">1.29</td>
|
||||
<td class="org-right">0.08</td>
|
||||
<td class="org-right">94%</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td class="org-right">1.1</td>
|
||||
<td class="org-right">1</td>
|
||||
<td class="org-right">0.50</td>
|
||||
<td class="org-right">0.045</td>
|
||||
<td class="org-right">91%</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div></div>
|
||||
|
||||
<p>
|
||||
To be clear, even the smallest file in this data — a 1.1 Mb Org file with around
|
||||
a thousand headings, is fairly large. So, it’s unlikely you’ll notice much of a
|
||||
difference with small–medium files, but if you a few large+ files this should
|
||||
be a <i>fantastic</i> improvement. Once again, thanks Ihor!
|
||||
</p>
|
||||
|
||||
<div class="warning" id="orgab1bff5">
|
||||
<p>
|
||||
The change to text properties instead of overlays breaks a number of third party
|
||||
packages like <kbd>evil-search</kbd> and <kbd>consult</kbd>’s <code>consult-line</code>.
|
||||
If you are involved in any packages affected by this, you’ll either want to
|
||||
consider supporting invisible text, or look at <code>isearch-filter-predicate</code> and
|
||||
<code>isearch-mode-end-hook</code>, which <kbd>org-fold</kbd> now uses.
|
||||
If you’re an end-user, perhaps politely make an issue on the repo for a project
|
||||
<i>if no issue currently exists</i>, and either:
|
||||
</p>
|
||||
<ul class="org-ul">
|
||||
<li>Stay off Org’s bleeding edge till the package ecosystem has adapted to this change</li>
|
||||
<li>Help the packages you use adapt to this change</li>
|
||||
<li>Set <code>org-fold-core-style</code> to <code>overlays</code> to restore the old behaviour</li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container--engraved-source" class="outline-2">
|
||||
<h2 id="-engraved-source"><i>Engraved</i> source code blocks in LaTeX<a aria-hidden="true" href="#-engraved-source">#</a> </h2>
|
||||
<div class="outline-text-2" id="text--engraved-source">
|
||||
<p>
|
||||
All too often exporting code to LaTeX has been a disappointment, with lovely
|
||||
syntax highlighting from Emacs major modes replaced with a markedly inferior
|
||||
attempt by pygments (setting <code>org-latex-listings</code> to <code>minted</code>) in a colour scheme I
|
||||
don’t really like.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
A bit over a year ago, a project called <a href="https://github.com/tecosaur/engrave-faces">engrave-faces</a> started with the aim of
|
||||
making Emacs’ font-lock more exportable, like a generalised <kbd>htmlize.el</kbd>. This has
|
||||
recently been used to provide a new option for inline and block source code
|
||||
exports in LaTeX.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="orgf152c8a">
|
||||
<img src="figures/engraved-faces-sample.png" alt="engraved-faces-sample.png" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 3: </span>A screenshot of an Org code block, exported to a <span class='acr'>PDF</span>, using <kbd>engrave-faces</kbd> and the <kbd>doom-one-light</kbd> theme.</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
To use this, simply install the package and set <code>org-latex-src-block-backend</code> (a
|
||||
rename of <code>org-latex-listings</code> to better reflect its usage) to <code>engraved</code>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
While this is sufficient to get started, this new backend also allows for some
|
||||
new options. The theme used for <i>engraving</i> a source block can be set globally
|
||||
with the new variable <code>org-latex-engraved-theme</code>, or per-file with the
|
||||
<kbd>#+latex_engraved_theme</kbd> keyword. It takes either the name of a theme, or the
|
||||
symbol <kbd>t</kbd> as a stand-in for the current theme.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The theme can also be set on a per-block level using the LaTeX attribute
|
||||
<kbd>:engraved-theme</kbd>.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="orgeceade1">
|
||||
<img src="figures/engraved-faces-multitheme.png" alt="engraved-faces-multitheme.png">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 4: </span>Seven code blocks exported to LaTeX, each with a different engrave-faces theme.</figcaption>
|
||||
</figure>
|
||||
|
||||
<p>
|
||||
Here’s what using these new capabilities looks like in practice.
|
||||
</p>
|
||||
|
||||
<details id='-engraved-source,code--1' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#-engraved-source,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-document-info-keyword">#+title:</span> <span class="org-org-document-title">Engraving source blocks</span>
|
||||
<span class="org-org-meta-line">#+latex_engraved_theme: modus-operandi</span>
|
||||
|
||||
<span class="org-org-block-begin-line">#+begin_src emacs-lisp</span>
|
||||
<span class="org-org-block">(message </span><span class="org-org-block"><span class="org-string">"look ma, some %s"</span></span><span class="org-org-block"> 'code)</span>
|
||||
<span class="org-org-block-end-line">#+end_src</span>
|
||||
|
||||
<span class="org-org-meta-line">#+attr_latex: :engraved-theme modus-viviandi</span>
|
||||
<span class="org-org-block-begin-line">#+begin_src shell</span>
|
||||
<span class="org-org-block"><span class="org-builtin">echo</span></span><span class="org-org-block"> </span><span class="org-org-block"><span class="org-string">"This is shell code"</span></span>
|
||||
<span class="org-org-block-end-line">#+end_src</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<p>
|
||||
This may well be the best syntax-highlighting solution available for <span class='acr'>PDF</span><small>s</small>/LaTeX
|
||||
currently available, but I am a tad biased 😛.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-texinfo-export-improvements" class="outline-2">
|
||||
<h2 id="texinfo-export-improvements">TexInfo export improvements<a aria-hidden="true" href="#texinfo-export-improvements">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-texinfo-export-improvements">
|
||||
<p>
|
||||
Jonas Bernoulli has been using a custom TexInfo backend for Magit’s
|
||||
documentation for a while now, and over the past few months he’s worked the
|
||||
features he was missing into Org’s built-in TexInfo exporter.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Upstreaming like this always takes a fair bit of effort, so thank you Jonas for
|
||||
going through with this!
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-toggle-noweb-prefix" class="outline-2">
|
||||
<h2 id="toggle-noweb-prefix">Toggle noweb prefix handling<a aria-hidden="true" href="#toggle-noweb-prefix">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-toggle-noweb-prefix">
|
||||
<p>
|
||||
Previously, whenever a noweb reference appeared on a non-empty line, a
|
||||
multi-line replacement would duplicate the content before the noweb reference.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Clearly, this is not always desirable, and this behaviour can now be turned of
|
||||
by setting the new header argument <kbd>:noweb-prefix no</kbd>.
|
||||
</p>
|
||||
|
||||
<details id='toggle-noweb-prefix,code--1' class='code' open><summary><span class="lang">Org mode</span></summary>
|
||||
<div class='gutter'>
|
||||
<a href='#toggle-noweb-prefix,code--1'>#</a>
|
||||
<button title='Copy to clipboard' onclick='copyPreToClipbord(this)'>⎘</button></div>
|
||||
<div class="org-src-container">
|
||||
<pre class="src src-org"><span class="org-org-block-begin-line">#+begin_src emacs-lisp :noweb yes :noweb-prefix no</span>
|
||||
<span class="org-org-block">(</span><span class="org-org-block"><span class="org-keyword">setq</span></span><span class="org-org-block"> example-data </span><span class="org-org-block"><span class="org-string">"<<example>>"</span></span><span class="org-org-block">)</span>
|
||||
<span class="org-org-block-end-line">#+end_src</span>
|
||||
|
||||
Will now expand to
|
||||
|
||||
<span class="org-org-block-begin-line">#+begin_src emacs-lisp</span>
|
||||
<span class="org-org-block">(</span><span class="org-org-block"><span class="org-keyword">setq</span></span><span class="org-org-block"> example-data </span><span class="org-org-block"><span class="org-string">"some</span></span>
|
||||
<span class="org-org-block"><span class="org-string">multi-line</span></span>
|
||||
<span class="org-org-block"><span class="org-string">content"</span></span><span class="org-org-block">)</span>
|
||||
<span class="org-org-block-end-line">#+end_src</span>
|
||||
|
||||
Instead of
|
||||
|
||||
<span class="org-org-block-begin-line">#+begin_src emacs-lisp</span>
|
||||
<span class="org-org-block">(</span><span class="org-org-block"><span class="org-keyword">setq</span></span><span class="org-org-block"> example-data </span><span class="org-org-block"><span class="org-string">"some</span></span>
|
||||
<span class="org-org-block"><span class="org-string">(setq example-data "</span></span><span class="org-org-block">multiline</span>
|
||||
<span class="org-org-block">(</span><span class="org-org-block"><span class="org-keyword">setq</span></span><span class="org-org-block"> example-data </span><span class="org-org-block"><span class="org-string">"content"</span></span><span class="org-org-block">)</span>
|
||||
<span class="org-org-block-end-line">#+end_src</span>
|
||||
</pre>
|
||||
</div>
|
||||
</details>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-package-highlight-org" class="outline-2">
|
||||
<h2 id="package-highlight-org">Package highlight: org-modern<a aria-hidden="true" href="#package-highlight-org">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-package-highlight-org">
|
||||
<p>
|
||||
I think we’ve all <a href="https://github.com/integral-dw/org-superstar-mode">seen</a> <a href="https://github.com/sabof/org-bullets">plenty</a> of <kbd>org-mode</kbd> <a href="https://github.com/Fuco1/org-pretty-table">prettification</a> <a href="https://github.com/harrybournis/org-fancy-priorities">packages</a> <a href="https://gitlab.com/marcowahl/org-pretty-tags">before</a>, so
|
||||
what makes Minad’s <a href="https://github.com/minad/org-modern">org-modern</a> special? It’s actually doing something similar to
|
||||
Ihor’s org-fold improvements, switching out slower overlay-based approaches for
|
||||
text properties. I can confirm that switching out <kbd>org-superstar-mode</kbd> for
|
||||
<kbd>org-modern</kbd> has made a substantial improvement in my experience, halving the
|
||||
first-load time of my <kbd>config.org</kbd> to around 20 seconds. If you’re a fan of Org
|
||||
prettification and haven’t taken a look at this package, I highly recommend
|
||||
giving it a shot.
|
||||
</p>
|
||||
|
||||
|
||||
<figure id="org7ef011c">
|
||||
<img src="figures/org-modern-readme-demo.gif" alt="org-modern-readme-demo.gif" class="invertible">
|
||||
|
||||
<figcaption><span class="figure-number">Figure 5: </span>A demonstration of org-modern taken from the project <span class='acr'>README</span>.</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-other-improvements" class="outline-2">
|
||||
<h2 id="other-improvements">Other improvements<a aria-hidden="true" href="#other-improvements">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-other-improvements">
|
||||
<ul class="org-ul">
|
||||
<li>Clean up some magic numbers in <kbd>org-attach</kbd> <span class="underline">Marco Wahl</span></li>
|
||||
<li>Allow <i>any</i> command form in <code>org-attach-commands</code> (including keyboard macros)
|
||||
<span class="underline">Marco Wahl</span></li>
|
||||
<li>Allow <kbd>dest</kbd> in <code>org-list-send-item</code> to be a buffer position <span class="underline">Sacha Chua</span></li>
|
||||
<li>Improve <span class='acr'>CSL</span>-<span class='acr'>JSON</span> date handling in <kbd>oc-basic</kbd> <span class="underline">David Lukes</span></li>
|
||||
<li>Add <kbd>TOML</kbd> and <kbd>desktop</kbd> language aliases <span class="underline"><span class='acr'>TEC</span></span></li>
|
||||
<li>Speed up cached bibliography retrieval in <kbd>oc-basic</kbd> <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>Allow setting PlantUML jar arguments <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>Allow for customisation of property separators with <code>org-property-separators</code>
|
||||
<span class="underline">Tyler Grinn</span></li>
|
||||
<li>New <kbd>ox-latex</kbd> maintainer, Daniel Fleischer</li>
|
||||
<li>More unit tests <span class="underline">Kyle Keyer, Nick Dokos</span></li>
|
||||
<li>Documentation improvements <span class="underline">Kyle Meyer, Juan Manuel Macias, Bastien, Karl
|
||||
Fogel, Cody Harris</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-bugfixes" class="outline-2">
|
||||
<h2 id="bugfixes">Bugfixes<a aria-hidden="true" href="#bugfixes">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-bugfixes">
|
||||
<ul class="org-ul">
|
||||
<li>An Emacs <28 bug in <kbd>org-persist</kbd> <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>Author extraction in <kbd>oc-basic</kbd> <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Fix behaviour of <code>org-copy-visible</code> with adjacent tex and
|
||||
<code>buffer-invisibility-spec</code> <span class="underline">Kyle Meyer</span></li>
|
||||
<li>Parsing of inline footnotes with parentheses <span class="underline">Nicolas Goaziou</span></li>
|
||||
<li>Honor <code>default-directory</code> in <kbd>ob-gnuplot</kbd> <span class="underline">Ihor Radchenko</span></li>
|
||||
<li>Heading fontification bug <span class="underline">Anders Johansson</span></li>
|
||||
<li>Template expansion where one key is a substring of another <span class="underline">Andrew Arensburger</span></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div id="footnotes">
|
||||
<h2 class="footnotes">Footnotes: </h2>
|
||||
<div id="text-footnotes">
|
||||
|
||||
<div class="footdef"><sup><a id="fn.1" class="footnum" href="#fnr.1" role="doc-backlink">1</a></sup> <div class="footpara" role="doc-footnote"><p class="footpara">Note the difference in scale, org-fold makes
|
||||
the most difference in the graph where the times are an order of magnitude
|
||||
more.</p></div></div>
|
||||
|
||||
|
||||
</div>
|
||||
</div></div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,9 +1,8 @@
|
|||
# -*- org-plot/gnuplot-term-extra: "background rgb '#fafafa' size 800,500 font 'Alegreya Sans, 16'"; -*-
|
||||
# Created 2024-01-12 Fri 13:39
|
||||
#+title: May 2022
|
||||
#+subtitle: Folding more improvement into Org
|
||||
#+author: TEC
|
||||
#+date: 2022-05-31
|
||||
|
||||
#+author: TEC
|
||||
#+subtitle: Folding more improvement into Org
|
||||
Finding time as of late has been more difficult than I anticipated, and on top
|
||||
of that, just as I was thinking of writing last month's post, I got distracted
|
||||
by an exciting patchset that has been in the works for over a year finally
|
||||
|
|
@ -13,26 +12,23 @@ this post will make up the absense of the last one 🙂.
|
|||
Since it's been longer than I thought since the last standard post, we've got a
|
||||
fair few commits to catch up on --- about 200. Most of these are miscellaneous
|
||||
minor improvements and bugfixes, but a few notable changes have arrived too.
|
||||
|
||||
* Folding
|
||||
|
||||
The fabulous new folding engine (=org-fold-core=) should noticeably improve Org's
|
||||
performance with large files. It contains a number of key optimisations to
|
||||
improve speed, namely:
|
||||
+ Deferring fontification of folded regions
|
||||
+ Using text properties (\(\mathcal{O}(n \log n)\)) instead of overlays (\(\mathcal{O}(n^2)\)) for folded regions
|
||||
+ A collection of aggressive optimisations available under ~org-fold-core--optimise-for-huge-buffers~
|
||||
+ Convert text properties to overlays for =isearch= (which currently only supports overlays)
|
||||
- Deferring fontification of folded regions
|
||||
- Using text properties (\(\mathcal{O}(n \log n)\)) instead of overlays (\(\mathcal{O}(n^2)\)) for folded regions
|
||||
- A collection of aggressive optimisations available under ~org-fold-core--optimise-for-huge-buffers~
|
||||
- Convert text properties to overlays for =isearch= (which currently only supports overlays)
|
||||
|
||||
How noticeable is the overall performance impact? Well, I poked Ihor and he was
|
||||
kind enough to whip up some benchmarks.
|
||||
|
||||
#+caption: The scaling of ~org-shifttab~ showing file contents, as file size increases, with and without org-fold.
|
||||
#+attr_html: :class invertible
|
||||
[[file:figures/org-fold-perf-shifttab-contents.svg]]
|
||||
|
||||
#+caption: The scaling of ~org-shifttab~ showing the entire file, as file size increases, with and without org-fold.
|
||||
#+attr_html: :class invertible
|
||||
[[file:figures/org-fold-perf-shifttab-showall.svg]]
|
||||
|
||||
Well this looks very promising[fn::Note the difference in scale, org-fold makes
|
||||
|
|
@ -62,37 +58,10 @@ consider supporting invisible text, or look at ~isearch-filter-predicate~ and
|
|||
~isearch-mode-end-hook~, which =org-fold= now uses.
|
||||
If you're an end-user, perhaps politely make an issue on the repo for a project
|
||||
/if no issue currently exists/, and either:
|
||||
+ Stay off Org's bleeding edge till the package ecosystem has adapted to this change
|
||||
+ Help the packages you use adapt to this change
|
||||
+ Set ~org-fold-core-style~ to ~overlays~ to restore the old behaviour
|
||||
- Stay off Org's bleeding edge till the package ecosystem has adapted to this change
|
||||
- Help the packages you use adapt to this change
|
||||
- Set ~org-fold-core-style~ to ~overlays~ to restore the old behaviour
|
||||
#+end_warning
|
||||
|
||||
** Benchmark data :noexport:
|
||||
|
||||
#+plot: ind:2 deps:(3 4) with:linespoints file:"figures/org-fold-perf-shifttab-contents.svg"
|
||||
#+plot: set:"title '{/*1.6 Running org-shifttab to CONTENTS}'" set:"xlabel '{/*1.2 File size (Mb)}'" set:"ylabel '{/*1.2 Load time (seconds)}'"
|
||||
#+plot: set:"logscale x" set:"logscale y" set:"linetype 1 pt 5" set:"linetype 2 pt 7"
|
||||
| Headings (k) | File Size (Mb) | Bugfix (no org-fold) | Main (org-fold) |
|
||||
|--------------+----------------+----------------------+-----------------|
|
||||
| 217 | 150 | 173.28 | 10.73 |
|
||||
| 36 | 18 | 1.97 | 0.92 |
|
||||
| 24 | 8.8 | 0.81 | 0.46 |
|
||||
| 5 | 4.4 | 0.09 | 0.21 |
|
||||
| 2 | 2.2 | 0.03 | 0.07 |
|
||||
| 1 | 1.1 | 0.02 | 0.04 |
|
||||
|
||||
#+plot: ind:2 deps:(3 4) with:linespoints file:"figures/org-fold-perf-shifttab-showall.svg"
|
||||
#+plot: set:"title '{/*1.6 Running org-shifttab to SHOW-ALL}'" set:"xlabel '{/*1.2 File size (Mb)}'" set:"ylabel '{/*1.2 Load time (seconds)}'"
|
||||
#+plot: set:"logscale x" set:"logscale y" set:"linetype 1 pt 5" set:"linetype 2 pt 7"
|
||||
| Headings (k) | File Size (Mb) | Bugfix (no org-fold) | Main (org-fold) |
|
||||
|--------------+----------------+----------------------+-----------------|
|
||||
| 217 | 150 | 8921.02 | 0.09 |
|
||||
| 36 | 18 | 100.96 | 0.02 |
|
||||
| 24 | 8.8 | 17.35 | 0.01 |
|
||||
| 5 | 4.4 | 3.79 | 0.005 |
|
||||
| 2 | 2.2 | 1.20 | 0.003 |
|
||||
| 1 | 1.1 | 0.49 | 0.003 |
|
||||
|
||||
* /Engraved/ source code blocks in LaTeX
|
||||
|
||||
All too often exporting code to LaTeX has been a disappointment, with lovely
|
||||
|
|
@ -107,7 +76,6 @@ exports in LaTeX.
|
|||
|
||||
#+caption: A screenshot of an Org code block, exported to a PDF,
|
||||
#+caption: using =engrave-faces= and the =doom-one-light= theme.
|
||||
#+attr_html: :class invertible
|
||||
[[file:figures/engraved-faces-sample.png]]
|
||||
|
||||
To use this, simply install the package and set ~org-latex-src-block-backend~ (a
|
||||
|
|
@ -128,22 +96,21 @@ The theme can also be set on a per-block level using the LaTeX attribute
|
|||
Here's what using these new capabilities looks like in practice.
|
||||
|
||||
#+begin_src org
|
||||
,#+title: Engraving source blocks
|
||||
,#+latex_engraved_theme: modus-operandi
|
||||
,#+title: Engraving source blocks
|
||||
,#+latex_engraved_theme: modus-operandi
|
||||
|
||||
,#+begin_src emacs-lisp
|
||||
(message "look ma, some %s" 'code)
|
||||
,#+end_src
|
||||
,#+begin_src emacs-lisp
|
||||
(message "look ma, some %s" 'code)
|
||||
,#+end_src
|
||||
|
||||
,#+attr_latex: :engraved-theme modus-viviandi
|
||||
,#+begin_src shell
|
||||
echo "This is shell code"
|
||||
,#+end_src
|
||||
,#+attr_latex: :engraved-theme modus-viviandi
|
||||
,#+begin_src shell
|
||||
echo "This is shell code"
|
||||
,#+end_src
|
||||
#+end_src
|
||||
|
||||
This may well be the best syntax-highlighting solution available for PDFs/LaTeX
|
||||
currently available, but I am a tad biased 😛.
|
||||
|
||||
* TexInfo export improvements
|
||||
|
||||
Jonas Bernoulli has been using a custom TexInfo backend for Magit's
|
||||
|
|
@ -152,7 +119,6 @@ features he was missing into Org's built-in TexInfo exporter.
|
|||
|
||||
Upstreaming like this always takes a fair bit of effort, so thank you Jonas for
|
||||
going through with this!
|
||||
|
||||
* Toggle noweb prefix handling
|
||||
|
||||
Previously, whenever a noweb reference appeared on a non-empty line, a
|
||||
|
|
@ -162,27 +128,26 @@ Clearly, this is not always desirable, and this behaviour can now be turned of
|
|||
by setting the new header argument =:noweb-prefix no=.
|
||||
|
||||
#+begin_src org
|
||||
,#+begin_src emacs-lisp :noweb yes :noweb-prefix no
|
||||
(setq example-data "<<example>>")
|
||||
,#+end_src
|
||||
,#+begin_src emacs-lisp :noweb yes :noweb-prefix no
|
||||
(setq example-data "<<example>>")
|
||||
,#+end_src
|
||||
|
||||
Will now expand to
|
||||
Will now expand to
|
||||
|
||||
,#+begin_src emacs-lisp
|
||||
(setq example-data "some
|
||||
multi-line
|
||||
content")
|
||||
,#+end_src
|
||||
,#+begin_src emacs-lisp
|
||||
(setq example-data "some
|
||||
multi-line
|
||||
content")
|
||||
,#+end_src
|
||||
|
||||
Instead of
|
||||
Instead of
|
||||
|
||||
,#+begin_src emacs-lisp
|
||||
(setq example-data "some
|
||||
(setq example-data "multiline
|
||||
(setq example-data "content")
|
||||
,#+end_src
|
||||
,#+begin_src emacs-lisp
|
||||
(setq example-data "some
|
||||
(setq example-data "multiline
|
||||
(setq example-data "content")
|
||||
,#+end_src
|
||||
#+end_src
|
||||
|
||||
* Package highlight: org-modern
|
||||
I think we've all [[https://github.com/integral-dw/org-superstar-mode][seen]] [[https://github.com/sabof/org-bullets][plenty]] of =org-mode= [[https://github.com/Fuco1/org-pretty-table][prettification]] [[https://github.com/harrybournis/org-fancy-priorities][packages]] [[https://gitlab.com/marcowahl/org-pretty-tags][before]], so
|
||||
what makes Minad's [[https://github.com/minad/org-modern][org-modern]] special? It's actually doing something similar to
|
||||
|
|
@ -194,31 +159,28 @@ prettification and haven't taken a look at this package, I highly recommend
|
|||
giving it a shot.
|
||||
|
||||
#+caption: A demonstration of org-modern taken from the project README.
|
||||
#+attr_html: :class invertible
|
||||
[[file:figures/org-modern-readme-demo.gif]]
|
||||
|
||||
* Other improvements
|
||||
+ Clean up some magic numbers in =org-attach= _Marco Wahl_
|
||||
+ Allow /any/ command form in ~org-attach-commands~ (including keyboard macros)
|
||||
- Clean up some magic numbers in =org-attach= _Marco Wahl_
|
||||
- Allow /any/ command form in ~org-attach-commands~ (including keyboard macros)
|
||||
_Marco Wahl_
|
||||
+ Allow =dest= in ~org-list-send-item~ to be a buffer position _Sacha Chua_
|
||||
+ Improve CSL-JSON date handling in =oc-basic= _David Lukes_
|
||||
+ Add =TOML= and =desktop= language aliases _TEC_
|
||||
+ Speed up cached bibliography retrieval in =oc-basic= _Ihor Radchenko_
|
||||
+ Allow setting PlantUML jar arguments _Ihor Radchenko_
|
||||
+ Allow for customisation of property separators with ~org-property-separators~
|
||||
- Allow =dest= in ~org-list-send-item~ to be a buffer position _Sacha Chua_
|
||||
- Improve CSL-JSON date handling in =oc-basic= _David Lukes_
|
||||
- Add =TOML= and =desktop= language aliases _TEC_
|
||||
- Speed up cached bibliography retrieval in =oc-basic= _Ihor Radchenko_
|
||||
- Allow setting PlantUML jar arguments _Ihor Radchenko_
|
||||
- Allow for customisation of property separators with ~org-property-separators~
|
||||
_Tyler Grinn_
|
||||
+ New =ox-latex= maintainer, Daniel Fleischer
|
||||
+ More unit tests _Kyle Keyer, Nick Dokos_
|
||||
+ Documentation improvements _Kyle Meyer, Juan Manuel Macias, Bastien, Karl
|
||||
- New =ox-latex= maintainer, Daniel Fleischer
|
||||
- More unit tests _Kyle Keyer, Nick Dokos_
|
||||
- Documentation improvements _Kyle Meyer, Juan Manuel Macias, Bastien, Karl
|
||||
Fogel, Cody Harris_
|
||||
|
||||
* Bugfixes
|
||||
+ An Emacs <28 bug in =org-persist= _Ihor Radchenko_
|
||||
+ Author extraction in =oc-basic= _Nicolas Goaziou_
|
||||
+ Fix behaviour of ~org-copy-visible~ with adjacent tex and
|
||||
- An Emacs <28 bug in =org-persist= _Ihor Radchenko_
|
||||
- Author extraction in =oc-basic= _Nicolas Goaziou_
|
||||
- Fix behaviour of ~org-copy-visible~ with adjacent tex and
|
||||
~buffer-invisibility-spec~ _Kyle Meyer_
|
||||
+ Parsing of inline footnotes with parentheses _Nicolas Goaziou_
|
||||
+ Honor ~default-directory~ in =ob-gnuplot= _Ihor Radchenko_
|
||||
+ Heading fontification bug _Anders Johansson_
|
||||
+ Template expansion where one key is a substring of another _Andrew Arensburger_
|
||||
- Parsing of inline footnotes with parentheses _Nicolas Goaziou_
|
||||
- Honor ~default-directory~ in =ob-gnuplot= _Ihor Radchenko_
|
||||
- Heading fontification bug _Anders Johansson_
|
||||
- Template expansion where one key is a substring of another _Andrew Arensburger_
|
||||
|
|
@ -0,0 +1,345 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>2022-05-31-folding.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span class="ef-c"># -*- org-plot/gnuplot-term-extra: "background rgb '#fafafa' size 800,500 font 'Alegreya Sans, 16'"; -*-</span>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">May 2022
|
||||
</span><span style="color: #9e9e9e;">#+subtitle:</span> Folding more improvement into Org
|
||||
<span style="color: #9e9e9e;">#+author:</span> TEC
|
||||
<span style="color: #9e9e9e;">#+date:</span> 2022-05-31
|
||||
|
||||
Finding time as of late has been more difficult than I anticipated, and on top
|
||||
of that, just as I was thinking of writing last month's post, I got distracted
|
||||
by an exciting patchset that has been in the works for over a year finally
|
||||
getting sorted out and landing. So, I hope that some of the fun developments in
|
||||
this post will make up the absense of the last one 🙂.
|
||||
|
||||
Since it's been longer than I thought since the last standard post, we've got a
|
||||
fair few commits to catch up on --- about 200. Most of these are miscellaneous
|
||||
minor improvements and bugfixes, but a few notable changes have arrived too.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Folding</span>
|
||||
|
||||
The fabulous new folding engine (<span style="color: #9e9e9e;">=org-fold-core=</span>) should noticeably improve Org's
|
||||
performance with large files. It contains a number of key optimisations to
|
||||
improve speed, namely:
|
||||
+ Deferring fontification of folded regions
|
||||
+ Using text properties (\(\mathcal{O}(n \log n)\)) instead of overlays (\(\mathcal{O}(n^2)\)) for folded regions
|
||||
+ A collection of aggressive optimisations available under <span style="color: #9e9e9e;">~org-fold-core--optimise-for-huge-buffers~</span>
|
||||
+ Convert text properties to overlays for <span style="color: #9e9e9e;">=isearch=</span> (which currently only supports overlays)
|
||||
|
||||
How noticeable is the overall performance impact? Well, I poked Ihor and he was
|
||||
kind enough to whip up some benchmarks.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">The scaling of ~org-shifttab~ showing file contents, as file size increases, with and without org-fold.</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/org-fold-perf-shifttab-contents.svg]]</span>
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">The scaling of ~org-shifttab~ showing the entire file, as file size increases, with and without org-fold.</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/org-fold-perf-shifttab-showall.svg]]</span>
|
||||
|
||||
Well this looks very promising[fn::Note the difference in scale, org-fold makes
|
||||
the most difference in the graph where the times are an order of magnitude
|
||||
more.]! Let's see how much of an improvement this is overall.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Time to run =org-shifttab= twice, cycling through all three display modes (in seconds).</span>
|
||||
| File size (Mb) | Headings (thousands) | Bugfix (no org-fold) | Main (with org-fold) | Improvement |
|
||||
|----------------+----------------------+----------------------+----------------------+-------------|
|
||||
| 18 | 36 | 115.31 | 0.89 | 99% |
|
||||
| 8.8 | 24 | 19.03 | 0.48 | 97% |
|
||||
| 4.4 | 5 | 3.79 | 0.13 | 97% |
|
||||
| 2.2 | 2 | 1.29 | 0.08 | 94% |
|
||||
| 1.1 | 1 | 0.50 | 0.045 | 91% |
|
||||
<span style="color: #b1b1b1;">#+TBLFM: $5=100*(1 - $4/$3) ; %.0f%%</span>
|
||||
|
||||
To be clear, even the smallest file in this data --- a 1.1 Mb Org file with around
|
||||
a thousand headings, is fairly large. So, it's unlikely you'll notice much of a
|
||||
difference with small--medium files, but if you a few large+ files this should
|
||||
be a <span class="ef-i">/fantastic/</span> improvement. Once again, thanks Ihor!
|
||||
|
||||
<span class="ef-obb">#+begin_warning
|
||||
</span>The change to text properties instead of overlays breaks a number of third party
|
||||
packages like <span style="color: #9e9e9e;">=evil-search=</span> and <span style="color: #9e9e9e;">=consult=</span>'s <span style="color: #9e9e9e;">~consult-line~</span>.
|
||||
If you are involved in any packages affected by this, you'll either want to
|
||||
consider supporting invisible text, or look at <span style="color: #9e9e9e;">~isearch-filter-predicate~</span> and
|
||||
<span style="color: #9e9e9e;">~isearch-mode-end-hook~</span>, which <span style="color: #9e9e9e;">=org-fold=</span> now uses.
|
||||
If you're an end-user, perhaps politely make an issue on the repo for a project
|
||||
<span class="ef-i">/if no issue currently exists/</span>, and either:
|
||||
+ Stay off Org's bleeding edge till the package ecosystem has adapted to this change
|
||||
+ Help the packages you use adapt to this change
|
||||
+ Set <span style="color: #9e9e9e;">~org-fold-core-style~</span> to <span style="color: #9e9e9e;">~overlays~</span> to restore the old behaviour
|
||||
<span class="ef-obe">#+end_warning
|
||||
</span>
|
||||
<span style="color: #97365b; font-weight: 700; font-size: 1.15em">** Benchmark data </span><span style="color: #97365b; font-weight: 700; font-size: 1.15em">:noexport:</span>
|
||||
|
||||
<span style="color: #b1b1b1;">#+plot: ind:2 deps:(3 4) with:linespoints file:"figures/org-fold-perf-shifttab-contents.svg"</span>
|
||||
<span style="color: #b1b1b1;">#+plot: set:"title '{/*1.6 Running org-shifttab to CONTENTS}'" set:"xlabel '{/*1.2 File size (Mb)}'" set:"ylabel '{/*1.2 Load time (seconds)}'"</span>
|
||||
<span style="color: #b1b1b1;">#+plot: set:"logscale x" set:"logscale y" set:"linetype 1 pt 5" set:"linetype 2 pt 7"</span>
|
||||
| Headings (k) | File Size (Mb) | Bugfix (no org-fold) | Main (org-fold) |
|
||||
|--------------+----------------+----------------------+-----------------|
|
||||
| 217 | 150 | 173.28 | 10.73 |
|
||||
| 36 | 18 | 1.97 | 0.92 |
|
||||
| 24 | 8.8 | 0.81 | 0.46 |
|
||||
| 5 | 4.4 | 0.09 | 0.21 |
|
||||
| 2 | 2.2 | 0.03 | 0.07 |
|
||||
| 1 | 1.1 | 0.02 | 0.04 |
|
||||
|
||||
<span style="color: #b1b1b1;">#+plot: ind:2 deps:(3 4) with:linespoints file:"figures/org-fold-perf-shifttab-showall.svg"</span>
|
||||
<span style="color: #b1b1b1;">#+plot: set:"title '{/*1.6 Running org-shifttab to SHOW-ALL}'" set:"xlabel '{/*1.2 File size (Mb)}'" set:"ylabel '{/*1.2 Load time (seconds)}'"</span>
|
||||
<span style="color: #b1b1b1;">#+plot: set:"logscale x" set:"logscale y" set:"linetype 1 pt 5" set:"linetype 2 pt 7"</span>
|
||||
| Headings (k) | File Size (Mb) | Bugfix (no org-fold) | Main (org-fold) |
|
||||
|--------------+----------------+----------------------+-----------------|
|
||||
| 217 | 150 | 8921.02 | 0.09 |
|
||||
| 36 | 18 | 100.96 | 0.02 |
|
||||
| 24 | 8.8 | 17.35 | 0.01 |
|
||||
| 5 | 4.4 | 3.79 | 0.005 |
|
||||
| 2 | 2.2 | 1.20 | 0.003 |
|
||||
| 1 | 1.1 | 0.49 | 0.003 |
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* </span><span style="color: #3b6ea8; text-decoration: italic; font-weight: nil; font-size: 1.25em">/Engraved/</span><span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em"> source code blocks in LaTeX</span>
|
||||
|
||||
All too often exporting code to LaTeX has been a disappointment, with lovely
|
||||
syntax highlighting from Emacs major modes replaced with a markedly inferior
|
||||
attempt by pygments (setting <span style="color: #9e9e9e;">~org-latex-listings~</span> to <span style="color: #9e9e9e;">~minted~</span>) in a colour scheme I
|
||||
don't really like.
|
||||
|
||||
A bit over a year ago, a project called <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/tecosaur/engrave-faces][engrave-faces]]</span> started with the aim of
|
||||
making Emacs' font-lock more exportable, like a generalised <span style="color: #9e9e9e;">=htmlize.el=</span>. This has
|
||||
recently been used to provide a new option for inline and block source code
|
||||
exports in LaTeX.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">A screenshot of an Org code block, exported to a PDF,</span>
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">using =engrave-faces= and the =doom-one-light= theme.</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/engraved-faces-sample.png]]</span>
|
||||
|
||||
To use this, simply install the package and set <span style="color: #9e9e9e;">~org-latex-src-block-backend~</span> (a
|
||||
rename of <span style="color: #9e9e9e;">~org-latex-listings~</span> to better reflect its usage) to <span style="color: #9e9e9e;">~engraved~</span>.
|
||||
|
||||
While this is sufficient to get started, this new backend also allows for some
|
||||
new options. The theme used for <span class="ef-i">/engraving/</span> a source block can be set globally
|
||||
with the new variable <span style="color: #9e9e9e;">~org-latex-engraved-theme~</span>, or per-file with the
|
||||
<span style="color: #9e9e9e;">=#+latex_engraved_theme=</span> keyword. It takes either the name of a theme, or the
|
||||
symbol <span style="color: #9e9e9e;">=t=</span> as a stand-in for the current theme.
|
||||
|
||||
The theme can also be set on a per-block level using the LaTeX attribute
|
||||
<span style="color: #9e9e9e;">=:engraved-theme=</span>.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">Seven code blocks exported to LaTeX, each with a different engrave-faces theme.</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/engraved-faces-multitheme.png]]</span>
|
||||
|
||||
Here's what using these new capabilities looks like in practice.
|
||||
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+title: Engraving source blocks
|
||||
,#+latex_engraved_theme: modus-operandi
|
||||
|
||||
,#+begin_src emacs-lisp
|
||||
(message "look ma, some %s" 'code)
|
||||
,#+end_src
|
||||
|
||||
,#+attr_latex: :engraved-theme modus-viviandi
|
||||
,#+begin_src shell
|
||||
echo "This is shell code"
|
||||
,#+end_src
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
This may well be the best syntax-highlighting solution available for PDFs/LaTeX
|
||||
currently available, but I am a tad biased 😛.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* TexInfo export improvements</span>
|
||||
|
||||
Jonas Bernoulli has been using a custom TexInfo backend for Magit's
|
||||
documentation for a while now, and over the past few months he's worked the
|
||||
features he was missing into Org's built-in TexInfo exporter.
|
||||
|
||||
Upstreaming like this always takes a fair bit of effort, so thank you Jonas for
|
||||
going through with this!
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Toggle noweb prefix handling</span>
|
||||
|
||||
Previously, whenever a noweb reference appeared on a non-empty line, a
|
||||
multi-line replacement would duplicate the content before the noweb reference.
|
||||
|
||||
Clearly, this is not always desirable, and this behaviour can now be turned of
|
||||
by setting the new header argument <span style="color: #9e9e9e;">=:noweb-prefix no=</span>.
|
||||
|
||||
<span class="ef-obb">#+begin_src org
|
||||
</span><span class="ef-ob">,#+begin_src emacs-lisp :noweb yes :noweb-prefix no
|
||||
(setq example-data "</span><span style="color: #9e9e9e; background-color: #e0e0e0;"><<example>></span><span class="ef-ob">")
|
||||
,#+end_src
|
||||
|
||||
Will now expand to
|
||||
|
||||
,#+begin_src emacs-lisp
|
||||
(setq example-data "some
|
||||
multi-line
|
||||
content")
|
||||
,#+end_src
|
||||
|
||||
Instead of
|
||||
|
||||
,#+begin_src emacs-lisp
|
||||
(setq example-data "some
|
||||
(setq example-data "multiline
|
||||
(setq example-data "content")
|
||||
,#+end_src
|
||||
</span><span class="ef-obe">#+end_src
|
||||
</span>
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Package highlight: org-modern</span>
|
||||
I think we've all <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/integral-dw/org-superstar-mode][seen]]</span> <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/sabof/org-bullets][plenty]]</span> of <span style="color: #9e9e9e;">=org-mode=</span> <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/Fuco1/org-pretty-table][prettification]]</span> <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/harrybournis/org-fancy-priorities][packages]]</span> <span style="color: #3b6ea8; font-weight: 700;">[[https://gitlab.com/marcowahl/org-pretty-tags][before]]</span>, so
|
||||
what makes Minad's <span style="color: #3b6ea8; font-weight: 700;">[[https://github.com/minad/org-modern][org-modern]]</span> special? It's actually doing something similar to
|
||||
Ihor's org-fold improvements, switching out slower overlay-based approaches for
|
||||
text properties. I can confirm that switching out <span style="color: #9e9e9e;">=org-superstar-mode=</span> for
|
||||
<span style="color: #9e9e9e;">=org-modern=</span> has made a substantial improvement in my experience, halving the
|
||||
first-load time of my <span style="color: #9e9e9e;">=config.org=</span> to around 20 seconds. If you're a fan of Org
|
||||
prettification and haven't taken a look at this package, I highly recommend
|
||||
giving it a shot.
|
||||
|
||||
<span style="color: #b1b1b1;">#+caption:</span> <span class="ef-ob">A demonstration of org-modern taken from the project README.</span>
|
||||
<span style="color: #b1b1b1;">#+attr_html: :class invertible</span>
|
||||
<span style="color: #3b6ea8; font-weight: 700;">[[file:figures/org-modern-readme-demo.gif]]</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Other improvements</span>
|
||||
+ Clean up some magic numbers in <span style="color: #9e9e9e;">=org-attach=</span> _Marco Wahl_
|
||||
+ Allow <span class="ef-i">/any/</span> command form in <span style="color: #9e9e9e;">~org-attach-commands~</span> (including keyboard macros)
|
||||
_Marco Wahl_
|
||||
+ Allow <span style="color: #9e9e9e;">=dest=</span> in <span style="color: #9e9e9e;">~org-list-send-item~</span> to be a buffer position _Sacha Chua_
|
||||
+ Improve CSL-JSON date handling in <span style="color: #9e9e9e;">=oc-basic=</span> _David Lukes_
|
||||
+ Add <span style="color: #9e9e9e;">=TOML=</span> and <span style="color: #9e9e9e;">=desktop=</span> language aliases _TEC_
|
||||
+ Speed up cached bibliography retrieval in <span style="color: #9e9e9e;">=oc-basic=</span> _Ihor Radchenko_
|
||||
+ Allow setting PlantUML jar arguments _Ihor Radchenko_
|
||||
+ Allow for customisation of property separators with <span style="color: #9e9e9e;">~org-property-separators~</span>
|
||||
_Tyler Grinn_
|
||||
+ New <span style="color: #9e9e9e;">=ox-latex=</span> maintainer, Daniel Fleischer
|
||||
+ More unit tests _Kyle Keyer, Nick Dokos_
|
||||
+ Documentation improvements _Kyle Meyer, Juan Manuel Macias, Bastien, Karl
|
||||
Fogel, Cody Harris_
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Bugfixes</span>
|
||||
+ An Emacs <28 bug in <span style="color: #9e9e9e;">=org-persist=</span> _Ihor Radchenko_
|
||||
+ Author extraction in <span style="color: #9e9e9e;">=oc-basic=</span> _Nicolas Goaziou_
|
||||
+ Fix behaviour of <span style="color: #9e9e9e;">~org-copy-visible~</span> with adjacent tex and
|
||||
<span style="color: #9e9e9e;">~buffer-invisibility-spec~</span> _Kyle Meyer_
|
||||
+ Parsing of inline footnotes with parentheses _Nicolas Goaziou_
|
||||
+ Honor <span style="color: #9e9e9e;">~default-directory~</span> in <span style="color: #9e9e9e;">=ob-gnuplot=</span> _Ihor Radchenko_
|
||||
+ Heading fontification bug _Anders Johansson_
|
||||
+ Template expansion where one key is a substring of another _Andrew Arensburger_
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,249 @@
|
|||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
MAY 2022
|
||||
Folding more improvement into Org
|
||||
|
||||
TEC
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
|
||||
2022-05-31
|
||||
|
||||
|
||||
Finding time as of late has been more difficult than I anticipated, and
|
||||
on top of that, just as I was thinking of writing last month’s post, I
|
||||
got distracted by an exciting patchset that has been in the works for
|
||||
over a year finally getting sorted out and landing. So, I hope that some
|
||||
of the fun developments in this post will make up the absense of the
|
||||
last one 🙂.
|
||||
|
||||
Since it’s been longer than I thought since the last standard post,
|
||||
we’ve got a fair few commits to catch up on — about 200. Most of these
|
||||
are miscellaneous minor improvements and bugfixes, but a few notable
|
||||
changes have arrived too.
|
||||
|
||||
|
||||
Folding
|
||||
═══════
|
||||
|
||||
The fabulous new folding engine (`org-fold-core') should noticeably
|
||||
improve Org’s performance with large files. It contains a number of
|
||||
key optimisations to improve speed, namely:
|
||||
⁃ Deferring fontification of folded regions
|
||||
⁃ Using text properties (𝒪(n log n)) instead of overlays (𝒪(n^2)) for
|
||||
folded regions
|
||||
⁃ A collection of aggressive optimisations available under
|
||||
`org-fold-core--optimise-for-huge-buffers'
|
||||
⁃ Convert text properties to overlays for `isearch' (which currently
|
||||
only supports overlays)
|
||||
|
||||
How noticeable is the overall performance impact? Well, I poked Ihor
|
||||
and he was kind enough to whip up some benchmarks.
|
||||
|
||||
<file:figures/org-fold-perf-shifttab-contents.svg>
|
||||
|
||||
<file:figures/org-fold-perf-shifttab-showall.svg>
|
||||
|
||||
Well this looks very promising[1]! Let’s see how much of an
|
||||
improvement this is overall.
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
File size (Mb) Headings (thousands) Bugfix (no org-fold) Main (with org-fold) Improvement
|
||||
───────────────────────────────────────────────────────────────────────────────────────────────
|
||||
18 36 115.31 0.89 99%
|
||||
8.8 24 19.03 0.48 97%
|
||||
4.4 5 3.79 0.13 97%
|
||||
2.2 2 1.29 0.08 94%
|
||||
1.1 1 0.50 0.045 91%
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Table 1: Time to run `org-shifttab' twice, cycling through all three
|
||||
display modes (in seconds).
|
||||
|
||||
To be clear, even the smallest file in this data — a 1.1 Mb Org file
|
||||
with around a thousand headings, is fairly large. So, it’s unlikely
|
||||
you’ll notice much of a difference with small–medium files, but if you
|
||||
a few large+ files this should be a /fantastic/ improvement. Once
|
||||
again, thanks Ihor!
|
||||
|
||||
The change to text properties instead of overlays breaks a number of
|
||||
third party packages like `evil-search' and `consult'’s
|
||||
`consult-line'. If you are involved in any packages affected by this,
|
||||
you’ll either want to consider supporting invisible text, or look at
|
||||
`isearch-filter-predicate' and `isearch-mode-end-hook', which
|
||||
`org-fold' now uses. If you’re an end-user, perhaps politely make an
|
||||
issue on the repo for a project /if no issue currently exists/, and
|
||||
either:
|
||||
⁃ Stay off Org’s bleeding edge till the package ecosystem has adapted
|
||||
to this change
|
||||
⁃ Help the packages you use adapt to this change
|
||||
⁃ Set `org-fold-core-style' to `overlays' to restore the old behaviour
|
||||
|
||||
|
||||
/Engraved/ source code blocks in LaTeX
|
||||
══════════════════════════════════════
|
||||
|
||||
All too often exporting code to LaTeX has been a disappointment, with
|
||||
lovely syntax highlighting from Emacs major modes replaced with a
|
||||
markedly inferior attempt by pygments (setting `org-latex-listings' to
|
||||
`minted') in a colour scheme I don’t really like.
|
||||
|
||||
A bit over a year ago, a project called [engrave-faces] started with
|
||||
the aim of making Emacs’ font-lock more exportable, like a generalised
|
||||
`htmlize.el'. This has recently been used to provide a new option for
|
||||
inline and block source code exports in LaTeX.
|
||||
|
||||
<file:figures/engraved-faces-sample.png>
|
||||
|
||||
To use this, simply install the package and set
|
||||
`org-latex-src-block-backend' (a rename of `org-latex-listings' to
|
||||
better reflect its usage) to `engraved'.
|
||||
|
||||
While this is sufficient to get started, this new backend also allows
|
||||
for some new options. The theme used for /engraving/ a source block
|
||||
can be set globally with the new variable `org-latex-engraved-theme',
|
||||
or per-file with the `#+latex_engraved_theme' keyword. It takes either
|
||||
the name of a theme, or the symbol `t' as a stand-in for the current
|
||||
theme.
|
||||
|
||||
The theme can also be set on a per-block level using the LaTeX
|
||||
attribute `:engraved-theme'.
|
||||
|
||||
<file:figures/engraved-faces-multitheme.png>
|
||||
|
||||
Here’s what using these new capabilities looks like in practice.
|
||||
|
||||
┌────
|
||||
│ #+title: Engraving source blocks
|
||||
│ #+latex_engraved_theme: modus-operandi
|
||||
│
|
||||
│ #+begin_src emacs-lisp
|
||||
│ (message "look ma, some %s" 'code)
|
||||
│ #+end_src
|
||||
│
|
||||
│ #+attr_latex: :engraved-theme modus-viviandi
|
||||
│ #+begin_src shell
|
||||
│ echo "This is shell code"
|
||||
│ #+end_src
|
||||
└────
|
||||
|
||||
This may well be the best syntax-highlighting solution available for
|
||||
PDFs/LaTeX currently available, but I am a tad biased 😛.
|
||||
|
||||
|
||||
[engrave-faces] <https://github.com/tecosaur/engrave-faces>
|
||||
|
||||
|
||||
TexInfo export improvements
|
||||
═══════════════════════════
|
||||
|
||||
Jonas Bernoulli has been using a custom TexInfo backend for Magit’s
|
||||
documentation for a while now, and over the past few months he’s
|
||||
worked the features he was missing into Org’s built-in TexInfo
|
||||
exporter.
|
||||
|
||||
Upstreaming like this always takes a fair bit of effort, so thank you
|
||||
Jonas for going through with this!
|
||||
|
||||
|
||||
Toggle noweb prefix handling
|
||||
════════════════════════════
|
||||
|
||||
Previously, whenever a noweb reference appeared on a non-empty line, a
|
||||
multi-line replacement would duplicate the content before the noweb
|
||||
reference.
|
||||
|
||||
Clearly, this is not always desirable, and this behaviour can now be
|
||||
turned of by setting the new header argument `:noweb-prefix no'.
|
||||
|
||||
┌────
|
||||
│ #+begin_src emacs-lisp :noweb yes :noweb-prefix no
|
||||
│ (setq example-data "<<example>>")
|
||||
│ #+end_src
|
||||
│
|
||||
│ Will now expand to
|
||||
│
|
||||
│ #+begin_src emacs-lisp
|
||||
│ (setq example-data "some
|
||||
│ multi-line
|
||||
│ content")
|
||||
│ #+end_src
|
||||
│
|
||||
│ Instead of
|
||||
│
|
||||
│ #+begin_src emacs-lisp
|
||||
│ (setq example-data "some
|
||||
│ (setq example-data "multiline
|
||||
│ (setq example-data "content")
|
||||
│ #+end_src
|
||||
└────
|
||||
|
||||
|
||||
Package highlight: org-modern
|
||||
═════════════════════════════
|
||||
|
||||
I think we’ve all [seen] [plenty] of `org-mode' [prettification]
|
||||
[packages] [before], so what makes Minad’s [org-modern] special? It’s
|
||||
actually doing something similar to Ihor’s org-fold improvements,
|
||||
switching out slower overlay-based approaches for text properties. I
|
||||
can confirm that switching out `org-superstar-mode' for `org-modern'
|
||||
has made a substantial improvement in my experience, halving the
|
||||
first-load time of my `config.org' to around 20 seconds. If you’re a
|
||||
fan of Org prettification and haven’t taken a look at this package, I
|
||||
highly recommend giving it a shot.
|
||||
|
||||
<file:figures/org-modern-readme-demo.gif>
|
||||
|
||||
|
||||
[seen] <https://github.com/integral-dw/org-superstar-mode>
|
||||
|
||||
[plenty] <https://github.com/sabof/org-bullets>
|
||||
|
||||
[prettification] <https://github.com/Fuco1/org-pretty-table>
|
||||
|
||||
[packages] <https://github.com/harrybournis/org-fancy-priorities>
|
||||
|
||||
[before] <https://gitlab.com/marcowahl/org-pretty-tags>
|
||||
|
||||
[org-modern] <https://github.com/minad/org-modern>
|
||||
|
||||
|
||||
Other improvements
|
||||
══════════════════
|
||||
|
||||
⁃ Clean up some magic numbers in `org-attach' _Marco Wahl_
|
||||
⁃ Allow /any/ command form in `org-attach-commands' (including
|
||||
keyboard macros) _Marco Wahl_
|
||||
⁃ Allow `dest' in `org-list-send-item' to be a buffer position _Sacha
|
||||
Chua_
|
||||
⁃ Improve CSL-JSON date handling in `oc-basic' _David Lukes_
|
||||
⁃ Add `TOML' and `desktop' language aliases _TEC_
|
||||
⁃ Speed up cached bibliography retrieval in `oc-basic' _Ihor
|
||||
Radchenko_
|
||||
⁃ Allow setting PlantUML jar arguments _Ihor Radchenko_
|
||||
⁃ Allow for customisation of property separators with
|
||||
`org-property-separators' _Tyler Grinn_
|
||||
⁃ New `ox-latex' maintainer, Daniel Fleischer
|
||||
⁃ More unit tests _Kyle Keyer, Nick Dokos_
|
||||
⁃ Documentation improvements _Kyle Meyer, Juan Manuel Macias, Bastien,
|
||||
Karl Fogel, Cody Harris_
|
||||
|
||||
|
||||
Bugfixes
|
||||
════════
|
||||
|
||||
⁃ An Emacs <28 bug in `org-persist' _Ihor Radchenko_
|
||||
⁃ Author extraction in `oc-basic' _Nicolas Goaziou_
|
||||
⁃ Fix behaviour of `org-copy-visible' with adjacent tex and
|
||||
`buffer-invisibility-spec' _Kyle Meyer_
|
||||
⁃ Parsing of inline footnotes with parentheses _Nicolas Goaziou_
|
||||
⁃ Honor `default-directory' in `ob-gnuplot' _Ihor Radchenko_
|
||||
⁃ Heading fontification bug _Anders Johansson_
|
||||
⁃ Template expansion where one key is a substring of another _Andrew
|
||||
Arensburger_
|
||||
|
||||
|
||||
|
||||
Footnotes
|
||||
─────────
|
||||
|
||||
[1] Note the difference in scale, org-fold makes the most difference in
|
||||
the graph where the times are an order of magnitude more.
|
||||
|
|
@ -0,0 +1,61 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>404</title>
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="404" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:published_time" content="2021-04-25T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2021-04-26T13:49:55+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header">
|
||||
<h1 class="title">404</h1>
|
||||
</header><p>
|
||||
Ooops, looks like you took a wrong turn somewhere.
|
||||
</p>
|
||||
</div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,83 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-16 Tue 00:23 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>February 2023: Part 1</title>
|
||||
<meta name="author" content="TEC" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="February 2023: Part 1" />
|
||||
<meta property="og:description" content="Long time, no see" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="TEC" />
|
||||
<meta property="og:article:published_time" content="2024-02-01T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2024-01-16T00:23:15+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2024-02-01, <span class='acr'>TEC</span></div>
|
||||
|
||||
<h1 class="title">February 2023: Part 1</h1>
|
||||
<p class="subtitle" role="doc-subtitle">Long time, no see</p>
|
||||
</header><div id="outline-container-m74sd-foreword-t" class="outline-2">
|
||||
<h2 id="m74sd-foreword-t">Foreword on the T<i>M</i>iO schedule<a aria-hidden="true" href="#m74sd-foreword-t">#</a> </h2>
|
||||
</div>
|
||||
|
||||
<div id="outline-container-org-liberapay" class="outline-2">
|
||||
<h2 id="org-liberapay">Org on LiberaPay<a aria-hidden="true" href="#org-liberapay">#</a> </h2>
|
||||
</div>
|
||||
|
||||
<div id="outline-container-latex-fragments-overhaul" class="outline-2">
|
||||
<h2 id="latex-fragments-overhaul">LaTeX fragments overhaul<a aria-hidden="true" href="#latex-fragments-overhaul">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-latex-fragments-overhaul">
|
||||
<p>
|
||||
Put this in a separate post
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-other-stuff" class="outline-2">
|
||||
<h2 id="other-stuff">Other stuff<a aria-hidden="true" href="#other-stuff">#</a> </h2>
|
||||
</div>
|
||||
</div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
# Created 2024-01-16 Tue 00:23
|
||||
#+title: February 2023: Part 1
|
||||
#+date: 2024-02-01
|
||||
#+author: TEC
|
||||
#+subtitle: Long time, no see
|
||||
* Foreword on the T/M/iO schedule
|
||||
|
||||
* Org on LiberaPay
|
||||
|
||||
* LaTeX fragments overhaul
|
||||
|
||||
Put this in a separate post
|
||||
* Other stuff
|
||||
|
|
@ -0,0 +1,135 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>DRAFT-2024-02-01-update.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">February 2023: Part 1
|
||||
</span><span style="color: #9e9e9e;">#+subtitle:</span> Long time, no see
|
||||
<span style="color: #9e9e9e;">#+author:</span> TEC
|
||||
<span style="color: #9e9e9e;">#+date:</span> 2024-02-01
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Foreword on the T</span><span style="color: #3b6ea8; text-decoration: italic; font-weight: nil; font-size: 1.25em">/M/</span><span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">iO schedule</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Org on LiberaPay</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* LaTeX fragments overhaul</span>
|
||||
|
||||
Put this in a separate post
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Other stuff</span>
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
━━━━━━━━━━━━━━━━━━━━━━━
|
||||
FEBRUARY 2023: PART 1
|
||||
Long time, no see
|
||||
|
||||
TEC
|
||||
━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
|
||||
2024-02-01
|
||||
|
||||
|
||||
Foreword on the T/M/iO schedule
|
||||
═══════════════════════════════
|
||||
|
||||
|
||||
Org on LiberaPay
|
||||
════════════════
|
||||
|
||||
|
||||
LaTeX fragments overhaul
|
||||
════════════════════════
|
||||
|
||||
Put this in a separate post
|
||||
|
||||
|
||||
Other stuff
|
||||
═══════════
|
||||
|
|
@ -0,0 +1,106 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- 2024-01-16 Tue 00:23 -->
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>February 2023: Part 2</title>
|
||||
<meta name="author" content="TEC" />
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="February 2023: Part 2" />
|
||||
<meta property="og:description" content="Fabulously Fancy Fragments" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:author:first_name" content="TEC" />
|
||||
<meta property="og:article:published_time" content="2024-02-02T00:00:00+0800" />
|
||||
<meta property="og:article:modified_time" content="2024-01-16T00:23:15+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header"><div class="page-meta">2024-02-02, <span class='acr'>TEC</span></div>
|
||||
|
||||
<h1 class="title">February 2023: Part 2</h1>
|
||||
<p class="subtitle" role="doc-subtitle">Fabulously Fancy Fragments</p>
|
||||
</header><p>
|
||||
In <a href="2021-07-31-citations.html">July 2021</a> I was thrilled to announce the long-awaited feature of citation
|
||||
syntax. Today I get to announce a feature a bit closer to my heart, a dramatic
|
||||
improvement (actually a complete overhaul of) Org’s system for generating LaTeX
|
||||
previews!
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<fancy image here>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
In late 2021, Karthik and I embarked on a project to improve the status quo by
|
||||
ripping out the entire LaTeX preview implementation, and then building something
|
||||
better in its place. After hundreds of hours (each), and just over a year, I
|
||||
think it’s fair to say we’ve succeeded.
|
||||
</p>
|
||||
<div id="outline-container-status-quo" class="outline-2">
|
||||
<h2 id="status-quo">The Status Quo<a aria-hidden="true" href="#status-quo">#</a> </h2>
|
||||
<div class="outline-text-2" id="text-status-quo">
|
||||
<figure>
|
||||
<video width="100%" height="auto" muted class="doom-opera-light">
|
||||
<source src="figures/latex-preview-race.webm" type="video/webm" />
|
||||
</video>
|
||||
<figcaption>
|
||||
<span class="figure-number">Figure 1:</span>
|
||||
A race between the new and old preview systems with a short document.
|
||||
</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
</div>
|
||||
<div id="outline-container-major-features-overhaul" class="outline-2">
|
||||
<h2 id="major-features-overhaul">Major features of the overhaul<a aria-hidden="true" href="#major-features-overhaul">#</a> </h2>
|
||||
</div>
|
||||
|
||||
<div id="outline-container-making-most-new" class="outline-2">
|
||||
<h2 id="making-most-new">Making the most of the new library<a aria-hidden="true" href="#making-most-new">#</a> </h2>
|
||||
</div>
|
||||
|
||||
<div id="outline-container-broad-strokes-implementation" class="outline-2">
|
||||
<h2 id="broad-strokes-implementation">The broad strokes of the implementation<a aria-hidden="true" href="#broad-strokes-implementation">#</a> </h2>
|
||||
</div>
|
||||
</div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
# Created 2024-01-16 Tue 00:23
|
||||
#+title: February 2023: Part 2
|
||||
#+date: 2024-02-02
|
||||
#+author: TEC
|
||||
#+subtitle: Fabulously Fancy Fragments
|
||||
In [[file:2021-07-31-citations.org][July 2021]] I was thrilled to announce the long-awaited feature of citation
|
||||
syntax. Today I get to announce a feature a bit closer to my heart, a dramatic
|
||||
improvement (actually a complete overhaul of) Org's system for generating LaTeX
|
||||
previews!
|
||||
|
||||
<fancy image here>
|
||||
|
||||
In late 2021, Karthik and I embarked on a project to improve the status quo by
|
||||
ripping out the entire LaTeX preview implementation, and then building something
|
||||
better in its place. After hundreds of hours (each), and just over a year, I
|
||||
think it's fair to say we've succeeded.
|
||||
* The Status Quo
|
||||
* Major features of the overhaul
|
||||
|
||||
* Making the most of the new library
|
||||
|
||||
* The broad strokes of the implementation
|
||||
|
|
@ -0,0 +1,167 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>DRAFT-2024-02-02-previewing.org.html</title>
|
||||
<style>
|
||||
body { background: #fafafa; color: #2a2a2a; }
|
||||
pre {
|
||||
font-size: 1rem;
|
||||
max-width: min(100rem, 100%);
|
||||
width: max-content;
|
||||
white-space: pre-wrap;
|
||||
margin: auto; }
|
||||
.ef-D {
|
||||
color: #2a2a2a; background-color: #fafafa; font-weight: 400; }
|
||||
.ef-b {
|
||||
font-weight: 700; }
|
||||
.ef-i {
|
||||
text-decoration: italic; }
|
||||
.ef-vp {
|
||||
}
|
||||
.ef-h {
|
||||
color: #9e9e9e; }
|
||||
.ef-sc {
|
||||
color: #4f894c; }
|
||||
.ef-w {
|
||||
color: #9a7500; }
|
||||
.ef-e {
|
||||
color: #99324b; }
|
||||
.ef-l {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-lv {
|
||||
color: #8b008b; font-weight: 700; }
|
||||
.ef-hi {
|
||||
color: #fafafa; background-color: #3b6ea8; }
|
||||
.ef-c {
|
||||
color: #b1b1b1; }
|
||||
.ef-cd {
|
||||
color: #b1b1b1; }
|
||||
.ef-s {
|
||||
color: #4f894c; }
|
||||
.ef-d {
|
||||
color: #b6b6b6; }
|
||||
.ef-m {
|
||||
color: #97365b; }
|
||||
.ef-k {
|
||||
color: #3b6ea8; }
|
||||
.ef-bi {
|
||||
color: #29838d; }
|
||||
.ef-f {
|
||||
color: #29838d; }
|
||||
.ef-v {
|
||||
color: #cb9aad; }
|
||||
.ef-t {
|
||||
color: #9a7500; }
|
||||
.ef-o {
|
||||
color: #97365b; }
|
||||
.ef-wr {
|
||||
color: #9a7500; }
|
||||
.ef-nc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-pp {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rc {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-rb {
|
||||
color: #3b6ea8; font-weight: 700; }
|
||||
.ef-ob {
|
||||
background-color: #e0e0e0; }
|
||||
.ef-obb {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-obe {
|
||||
color: #b1b1b1; background-color: #e0e0e0; }
|
||||
.ef-Oa {
|
||||
color: #3b6ea8; font-weight: nil; font-size: 1.25em }
|
||||
.ef-Ob {
|
||||
color: #97365b; font-weight: 700; font-size: 1.15em }
|
||||
.ef-Oc {
|
||||
color: #842879; font-weight: 700; font-size: 1.12em }
|
||||
.ef-Od {
|
||||
color: #6c92bd; font-weight: 600; font-size: 1.09em }
|
||||
.ef-Oe {
|
||||
color: #b16883; font-weight: 600; font-size: 1.06em }
|
||||
.ef-Of {
|
||||
color: #9db6d3; font-weight: 600; font-size: 1.03em }
|
||||
.ef-Og {
|
||||
color: #cb9aad; font-weight: 700; }
|
||||
.ef-Oh {
|
||||
color: #d7e2ed; font-weight: 600; }
|
||||
.ef-hn {
|
||||
color: #97365b; font-weight: 700; }
|
||||
.ef-hq {
|
||||
color: #3b6ea8; }
|
||||
.ef-hs {
|
||||
color: #9a7500; }
|
||||
.ef-rda {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdb {
|
||||
color: #97365b; }
|
||||
.ef-rdc {
|
||||
color: #4f894c; }
|
||||
.ef-rdd {
|
||||
color: #842879; }
|
||||
.ef-rde {
|
||||
color: #29838d; }
|
||||
.ef-rdf {
|
||||
color: #3b6ea8; }
|
||||
.ef-rdg {
|
||||
color: #97365b; }
|
||||
.ef-rdh {
|
||||
color: #4f894c; }
|
||||
.ef-rdi {
|
||||
color: #842879; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<pre>
|
||||
<span style="color: #9e9e9e;">#+title:</span> <span style="font-weight: 700;">February 2023: Part 2
|
||||
</span><span style="color: #9e9e9e;">#+subtitle:</span> Fabulously Fancy Fragments
|
||||
<span style="color: #9e9e9e;">#+author:</span> TEC
|
||||
<span style="color: #9e9e9e;">#+date:</span> 2024-02-02
|
||||
|
||||
<span class="ef-c"># Current planned structure:</span>
|
||||
<span class="ef-c"># - bang! impressive pretty stuff all going on at once</span>
|
||||
<span class="ef-c"># - hey, look it's a bit faster</span>
|
||||
<span class="ef-c"># - and a bit prettier</span>
|
||||
<span class="ef-c"># - and zoom/theme matching</span>
|
||||
<span class="ef-c"># - faster? lots faster</span>
|
||||
<span class="ef-c"># - so fast we can do live previews</span>
|
||||
<span class="ef-c"># - implemented in a way that other modes can re-use</span>
|
||||
<span class="ef-c"># - taster of implementation details + link to your post</span>
|
||||
|
||||
In <span style="color: #3b6ea8; font-weight: 700;">[[file:2021-07-31-citations.org][July 2021]]</span> I was thrilled to announce the long-awaited feature of citation
|
||||
syntax. Today I get to announce a feature a bit closer to my heart, a dramatic
|
||||
improvement (actually a complete overhaul of) Org's system for generating LaTeX
|
||||
previews!
|
||||
|
||||
<fancy image here>
|
||||
|
||||
In late 2021, Karthik and I embarked on a project to improve the status quo by
|
||||
ripping out the entire LaTeX preview implementation, and then building something
|
||||
better in its place. After hundreds of hours (each), and just over a year, I
|
||||
think it's fair to say we've succeeded.
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* The Status Quo</span>
|
||||
|
||||
<span class="ef-obb">#+begin_export html
|
||||
</span><span style="color: #9e9e9e; background-color: #e0e0e0;"><figure>
|
||||
<video width="100%" height="auto" muted class="doom-opera-light">
|
||||
<source src="figures/latex-preview-race.webm" type="video/webm" />
|
||||
</video>
|
||||
<figcaption>
|
||||
<span class="figure-number">Figure 1:</span>
|
||||
A race between the new and old preview systems with a short document.
|
||||
</figcaption>
|
||||
</figure>
|
||||
</span><span class="ef-obe">#+end_export
|
||||
</span>
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Major features of the overhaul</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* Making the most of the new library</span>
|
||||
|
||||
<span style="color: #3b6ea8; font-weight: nil; font-size: 1.25em">* The broad strokes of the implementation</span>
|
||||
|
||||
</pre>
|
||||
<body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
FEBRUARY 2023: PART 2
|
||||
Fabulously Fancy Fragments
|
||||
|
||||
TEC
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
|
||||
2024-02-02
|
||||
|
||||
|
||||
In [July 2021] I was thrilled to announce the long-awaited feature of
|
||||
citation syntax. Today I get to announce a feature a bit closer to my
|
||||
heart, a dramatic improvement (actually a complete overhaul of) Org’s
|
||||
system for generating LaTeX previews!
|
||||
|
||||
<fancy image here>
|
||||
|
||||
In late 2021, Karthik and I embarked on a project to improve the status
|
||||
quo by ripping out the entire LaTeX preview implementation, and then
|
||||
building something better in its place. After hundreds of hours (each),
|
||||
and just over a year, I think it’s fair to say we’ve succeeded.
|
||||
|
||||
|
||||
[July 2021] <file:2021-07-31-citations.org>
|
||||
|
||||
|
||||
The Status Quo
|
||||
══════════════
|
||||
|
||||
|
||||
Major features of the overhaul
|
||||
══════════════════════════════
|
||||
|
||||
|
||||
Making the most of the new library
|
||||
══════════════════════════════════
|
||||
|
||||
|
||||
The broad strokes of the implementation
|
||||
═══════════════════════════════════════
|
||||
22
LICENSE
22
LICENSE
|
|
@ -1,22 +0,0 @@
|
|||
The MIT License (MIT)
|
||||
|
||||
Copyright (c) 2021 TEC
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of this software and associated documentation files (the
|
||||
"Software"), to deal in the Software without restriction, including
|
||||
without limitation the rights to use, copy, modify, merge, publish,
|
||||
distribute, sublicense, and/or sell copies of the Software, and to
|
||||
permit persons to whom the Software is furnished to do so, subject to
|
||||
the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be
|
||||
included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||||
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||||
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
||||
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||||
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
18
README.org
18
README.org
|
|
@ -1,18 +0,0 @@
|
|||
#+title: This Month in Org
|
||||
#+author: TEC
|
||||
#+date: 2021-04-24
|
||||
|
||||
#+html: <a href="https://orgmode.org"><img src="https://img.shields.io/badge/Made_with_Org-77aa99?style=flat-square&logo=org&logoColor=587e72"/></a>
|
||||
#+html: <a href="https://www.buymeacoffee.com/tecosaur"><img src="https://img.shields.io/badge/Buy_me_a_coffee-FFDD00?style=flat-square&logo=buy-me-a-coffee&logoColor=black"></a>
|
||||
|
||||
A monthly blog on Org developments.
|
||||
|
||||
* Components
|
||||
This is built with the following components:
|
||||
+ Org, and Org's export backends for the file generation
|
||||
+ My (Doom) Emacs config, for configuring the export to make it prettier
|
||||
+ Org publish for orchestrating the process
|
||||
|
||||
* Licensing
|
||||
+ The content for the blog ([[file:content/][content/]] and [[file:assets/figures/][assets/figures/]]) is under the [[https://creativecommons.org/publicdomain/zero/1.0/][CC0]] license
|
||||
+ The framework for the blog itself ([[file:publish.el][publish.el]] and [[file:assets/][assets/]]) is under the [[https://opensource.org/licenses/MIT][MIT]] license
|
||||
|
|
@ -0,0 +1,74 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>Archive</title>
|
||||
<meta name="generator" content="org mode" />
|
||||
<meta name="theme-color" content="#77aa99" />
|
||||
<meta property="og:type" content="article" />
|
||||
<meta property="og:title" content="Archive" />
|
||||
<meta property="og:image" content="https://blog.tecosaur.net/tmio/org-icon.png" />
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<meta property="og:image:width" content="464" />
|
||||
<meta property="og:image:height" content="512" />
|
||||
<meta property="og:image:alt" content="Org unicorn logo" />
|
||||
<meta property="og:article:published_time" content="2024-01-11T17:58:27+0800" />
|
||||
<meta property="og:article:modified_time" content="2024-01-11T17:58:27+0800" />
|
||||
<link rel="alternate" type="application/atom+xml" title="This Month in Org" href="rss.xml" />
|
||||
<link rel="icon" type="image/ico" href="favicon.ico?v=3">
|
||||
<link rel="stylesheet" type="text/css" href="org-style.css">
|
||||
<link rel="stylesheet" type="text/css" href="blog.css">
|
||||
<script src="org-style.js"></script>
|
||||
<style> a { background-size: 0 !important; } li a { text-decoration: none; } </style>
|
||||
</head>
|
||||
<body>
|
||||
<input type='checkbox' id='theme-switch'><div id='page'><label id='switch-label' for='theme-switch'></label><div id="preamble" class="status">
|
||||
<header>
|
||||
<h4><a href="https://orgmode.org" class="orgicorn"><img src="org-icon-monochrome.svg" class="invertible"></a>
|
||||
<a href="https://blog.tecosaur.net/tmio/" class="title">
|
||||
This Month in Org</a>
|
||||
<a href="rss.xml" title="RSS Feed" type="application/rss+xml" class="rss">
|
||||
<img src="rss.svg" alt="RSS icon" />
|
||||
</a></h4>
|
||||
</header>
|
||||
</div>
|
||||
<div id="content">
|
||||
<header class="page-header">
|
||||
<h1 class="title">Archive</h1>
|
||||
</header><ul class="org-ul">
|
||||
<li><a href='2022-05-31-folding.html'> <b>2022-05-31</b> Folding more improvement into Org <span class="underline">1090 words</span> </a></li>
|
||||
<li><a href='2022-04-01-confluence.html'> <b>2022-04-01</b> Throwing in the towel and jumping on the bandwagon <span class="underline">320 words</span> </a></li>
|
||||
<li><a href='2022-02-30-orgnvim.html'> <b>2022-02-30</b> An orgmode clone for neovim <span class="underline">2070 words</span> </a></li>
|
||||
<li><a href='2022-01-31-caching.html'> <b>2022-01-31</b> Caching <span class="underline">770 words</span> </a></li>
|
||||
<li><a href='2021-12-31-retrospection.html'> <b>2021-12-31</b> Looking back on my first year of blogging <span class="underline">540 words</span> </a></li>
|
||||
<li><a href='2021-11-30-element.html'> <b>2021-11-30</b> Elementary improvements <span class="underline">1830 words</span> </a></li>
|
||||
<li><a href='2021-10-31-release.html'> <b>2021-10-31</b> Release 9.5 <span class="underline">640 words</span> </a></li>
|
||||
<li><a href='2021-08-38-roaming.html'> <b>2021-08-38</b> Roaming around <span class="underline">620 words</span> </a></li>
|
||||
<li><a href='2021-07-31-citations.html'> <b>2021-07-31</b> Introducing citations! <span class="underline">1710 words</span> </a></li>
|
||||
<li><a href='2021-06-34-relaxed.html'> <b>2021-06-34</b> A relaxed month <span class="underline">1250 words</span> </a></li>
|
||||
<li><a href='2021-05-31-async.html'> <b>2021-05-31</b> Asynchronous code execution <span class="underline">1090 words</span> </a></li>
|
||||
<li><a href='2021-04-30-export-plot.html'> <b>2021-04-30</b> Export <i>&</i> plot in style <span class="underline">860 words</span> </a></li>
|
||||
<li><a href='2021-04-26-Welcome.html'> <b>2021-04-26</b> Welcome <span class="underline">930 words</span> </a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div id="postamble" class="status">
|
||||
<footer>
|
||||
<p xmlns:dct="http://purl.org/dc/terms/" xmlns:vcard="http://www.w3.org/2001/vcard-rdf/3.0#">
|
||||
<a rel="license" class="external" rel="nofollow" href="http://creativecommons.org/publicdomain/zero/1.0/">
|
||||
<img src="cc0.svg" alt="CC0" class="invertible" style="position:relative;bottom:-0.2em"/>
|
||||
</a>
|
||||
To the extent possible under law,
|
||||
<a rel="dct:publisher"
|
||||
href="https://blog.tecosaur.net/">
|
||||
<span property="dct:title">TEC</span></a>
|
||||
has waived all copyright and related or neighboring rights to
|
||||
<span property="dct:title" style="font-style:italic">This Month in Org</span>.
|
||||
</p>
|
||||
</footer>
|
||||
|
||||
<script src="theme-switcher.js"></script>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,94 +0,0 @@
|
|||
header {
|
||||
position: relative;
|
||||
& > h4 > a {
|
||||
text-decoration: none;
|
||||
color: inherit;
|
||||
&.orgicorn img {
|
||||
height: 1.5em;
|
||||
top: 0.25em;
|
||||
opacity: 0.85;
|
||||
position: relative;
|
||||
}
|
||||
&.rss {
|
||||
float: right;
|
||||
& img {
|
||||
position: relative;
|
||||
top: -0.2em;
|
||||
filter: invert(0.6);
|
||||
&:hover {
|
||||
opacity: 1;
|
||||
filter: invert(38%) sepia(98%) saturate(1640%) hue-rotate(11deg) contrast(98%);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@media (min-width: 1000px) {
|
||||
#content {
|
||||
margin: auto;
|
||||
}
|
||||
header {
|
||||
margin: 0 auto -2rem;
|
||||
h4 > a.orgicorn {
|
||||
display: inherit; // I have no idea why this is needed, but it seems to be
|
||||
img {
|
||||
position: absolute;
|
||||
top: -0.3em;
|
||||
transform: translateX(-100%) translateX(-0.8rem);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
#postamble {
|
||||
display: block;
|
||||
}
|
||||
footer {
|
||||
display: block;
|
||||
text-align: center;
|
||||
font-size: 0.8rem;
|
||||
padding: 1rem 0;
|
||||
font-family: sans;
|
||||
color: #666;
|
||||
& a {
|
||||
color: #777;
|
||||
font-weight: bold;
|
||||
background-image: none !important;
|
||||
opacity: 0.65;
|
||||
}
|
||||
}
|
||||
#content {
|
||||
min-height: calc(100vh - 10rem - 48px); /* because of the header */
|
||||
}
|
||||
.doom-one { /* make doom-one screenshots match the blog */
|
||||
filter: invert(5%) sepia(3%);
|
||||
}
|
||||
#theme-switch:checked ~ #page .doom-one {
|
||||
filter: invert(91.5%) hue-rotate(180deg) sepia(1%)
|
||||
}
|
||||
.underline { /* repurpose to show off contributors */
|
||||
color: var(--text-medium);
|
||||
border-radius: .8em;
|
||||
padding: .5em .4em .2em;
|
||||
height: 0;
|
||||
font-size: .9em;
|
||||
font-family: "Open Sans",sans;
|
||||
&:last-child {
|
||||
float: right;
|
||||
white-space: break-spaces;
|
||||
line-height: 1;
|
||||
}
|
||||
}
|
||||
|
||||
/* click on a figure to enlarge it */
|
||||
figure {
|
||||
transition-property: left width;
|
||||
left: 0;
|
||||
width: 90%;
|
||||
transition-duration: 0ms;
|
||||
&:active {
|
||||
position: relative;
|
||||
left: #{"min(0px, 720px - 60vw)"};
|
||||
width: 80vw;
|
||||
transition-duration: 150ms;
|
||||
}
|
||||
}
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:12b9a81ef4aa491af60ea8dda8cfa9011650dd1c866429ddbca1cfb2578bfd4f
|
||||
size 109387
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:73f9724896e0b2fc0ca1d2d19b2dd976edb0c9f5b01b634c69ecfedc459267e9
|
||||
size 73914
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:cdf3d2e64b835a61bd40e9250ae88239e4e99cf534ddd97537d531550f68a3ce
|
||||
size 154385
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:8e72f5504f7f8f2271ac59f5d0ddebfe9bff2291341b106ec6d38b9b2f6d1beb
|
||||
size 181451
|
||||
BIN
assets/figures/engraved-faces-multitheme.png (Stored with Git LFS)
BIN
assets/figures/engraved-faces-multitheme.png (Stored with Git LFS)
Binary file not shown.
BIN
assets/figures/engraved-faces-sample.png (Stored with Git LFS)
BIN
assets/figures/engraved-faces-sample.png (Stored with Git LFS)
Binary file not shown.
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:2aa4f6e921b76a4d9d13b4bf2af3afca2a64259a616b3ce1def1e4697537516f
|
||||
size 81608
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:832f876314f73db299bb2d032447730fa093a07bd59dac816eb7aac13029f746
|
||||
size 65154
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:981319c679cd78a1679075636dd8d9c5704ebf7fe3055a53e2e1c5509bf68b21
|
||||
size 26620
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:d4563fc3617bafbbb6d35b19b7bd56c306df4429ba5182d315b9d6c4ad41e90b
|
||||
size 76531
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:24ceae16f688ce15935a795c207c57863f7b2114d2a15c89c55b7a0b06579f86
|
||||
size 73341
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:5b7e41b41e17f8846b34567e2aac4db6e37b4c2c901f79676ed2d94e5926bad5
|
||||
size 47511
|
||||
BIN
assets/figures/org-fold-perf-shifttab-contents.svg (Stored with Git LFS)
BIN
assets/figures/org-fold-perf-shifttab-contents.svg (Stored with Git LFS)
Binary file not shown.
BIN
assets/figures/org-fold-perf-shifttab-showall.svg (Stored with Git LFS)
BIN
assets/figures/org-fold-perf-shifttab-showall.svg (Stored with Git LFS)
Binary file not shown.
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:0e74ea4b2c97de7d3ea5d16cfbcc224884078e209f13f81e0eafbd1eb4a95a0a
|
||||
size 144374
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:0b41ce681229fb8fe6019080f82c843273122f4179d87d5302fd0ce19109c6f9
|
||||
size 140218
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:ea80b88b326496f4c4ef48f7712e8c92b4f10c980b43e3a7daebc3e64628421e
|
||||
size 47304
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:60fcbb374cf19654f5d3adf64b4ec833940dd60515cd82e9959359604182ed77
|
||||
size 45473
|
||||
BIN
assets/figures/org-markup-to-confluence.svg (Stored with Git LFS)
BIN
assets/figures/org-markup-to-confluence.svg (Stored with Git LFS)
Binary file not shown.
BIN
assets/figures/org-modern-readme-demo.gif (Stored with Git LFS)
BIN
assets/figures/org-modern-readme-demo.gif (Stored with Git LFS)
Binary file not shown.
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:135dbd08b0dc5955b0e894efc61178b34e4b9c846a9e2d9d0f541ca8d9170ee8
|
||||
size 229967
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:75128413936b6f84edcbbe9775eb4444a5933efab1f01b955f796ab591ee5df7
|
||||
size 104322
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:2f095b0fdb2894cfd38f59999c9d0db511d6bbe2edf39f8235ee9c548e9bbd4b
|
||||
size 1312061
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:6573d2a75ed87ca277aa36519b673b00a597f5de9e86cdae4ccb07013c9aaae4
|
||||
size 291865
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:50e4f88d92c981a79efb53e004fed62c89a4ab1a21cd8e0fde9a2e2f255d3d16
|
||||
size 87816
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:bceb92d115bf5c88e127c69d40a45cb44ae6819695d33aecfbb304c7eb16d2a7
|
||||
size 72441
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:6d23e7188451d791a3bc0c31b94f58dddfcdadc8483464ff790b0d055cc93ef4
|
||||
size 95149
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:3c560af2dda08a14a6bcf6af5f40660dafa072570b7b4ac1af83ae06defb2ead
|
||||
size 133357
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:195652247651ad27a0c49f14cdbd8cbf27bb5d426d85e18be5e1060a49090843
|
||||
size 628696
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:94568835edc86657139d29ff83320431d4b91269bb27ca7464dbe6dbfa47472c
|
||||
size 415019
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:a76c06e0557cdd021ed3cc6aeecd502053e771213e5922517c9c9c15fd296f02
|
||||
size 204789
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue