Tag: Org

My Blog Workflow

This blog, which I started in 2013, is hosted on wordpress.com. WordPress sites are both websites and blogs, and in late 2020 I translated my website over to this same domain name (nhigham.com).

org2blog_logo-color-multi.png

The whole site is maintained as Emacs Org mode files that I export to WordPress using the Emacs org2blog package. I do not use the WordPress editor, except occasionally to copy the html for a figure back into an Org file for tweaking and re-exporting as html (usually in order to have text next to an image, as here).

WordPress supports \LaTeX math mode, which must be typed within single dollar signs with the word “latex” right after the first dollar sign. Emacs Org mode supports \LaTeX equations and Org2blog does an excellent job of exporting to WordPress with the necessary conversions. For example, to produce the displayed equation

\notag X = \begin{bmatrix} a_{11} & a_{12} \\ a_{12} & a_{22} \end{bmatrix}^{-1}

I type

\begin{equation}\notag
 X =  \begin{bmatrix}
       a_{11} & a_{12} \\ 
       a_{12} & a_{22} 
      \end{bmatrix}^{-1}
\end{equation}

in my source and this is converted into

wordpress_eqn_example.jpg

in WordPress. (This fragment is included as an image because if I include the text directly I cannot stop WordPress interpreting it as \LaTeX!)

The beauty of this workflow is that I can export this same source to html, \LaTeX (then PDF), or even a Word file using Org mode’s export dispatcher. This is how I produce the PDF versions of the posts in the What Is series.

Advantages of this workflow are

  • I can work almost entirely in Emacs and avoid using the WordPress editor.
  • Org mode files are very readable and easy to edit.
  • Org2blog automatically uploads images into the WordPress media library and links to them.
  • Raw html can be included.

Drawbacks of the workflow are

  • \LaTeX macros cannot be defined, so \LaTeX commands must always be typed in full.
  • Displayed equations must be typed in an equation environment for reliable results.
  • All math is formatted in text style, so \displaystyle must be put in front of every \frac, \sum, etc. to obtain display style (so that formulas in fractions are not set in a smaller font, for example).
  • Inline math has awkward vertical spacing.
  • In the current version of org2blog, equation* (for an unnumbered equation) is not supported.

The latter three disadvantages would be avoided if the \LaTeX was interpreted by MathJax, but this requires a MathJax plugin, and the Business Plan is needed to be able to install plugins (I have the Premium plan).

Here is what the Emacs Org mode source code looks like for the post What Is the Sylvester Equation? After the properties drawer, which contains information about the post on WordPress, the text looks like standard \LaTeX, with the exception that a comment line begins with the # symbol rather than %.

what-is-kron_src.jpg

Org Mode Syntax Cheat Sheet

org_mode_logo.jpg

I’m a keen user of Emacs and Org mode for a variety of tasks, including

  • note taking,
  • generating documents for exporting to LaTeX, Word, or html.
  • creating blog posts (notably for this blog, using Org2blog).

Although Org mode is usually associated with Emacs, it is a markup language in its own right, and one that is far more powerful and more standardized than the Markdown language.

I recently came across the excellent blog post Org-Mode Is One of the Most Reasonable Markup Language to Use for Text by Org enthusiast Karl Voit. In the post he includes a simple example displaying some of the most important aspects of Org syntax. I was struck by how much information can be conveyed in a short piece of Org code. I have adapted Karl’s example into this longer version:

#+TITLE: Org Mode Syntax Cheat Sheet
#+OPTIONS: toc:nil 
# Adapted from http://karl-voit.at/2017/09/23/orgmode-as-markup-only/

* Top Level Heading
** Second Level Heading
*** Third Level Heading

# A comment line.  This line will not be exported.

Paragraphs are separated by at least one empty line.

*bold* /italic/ _underlined_ +strikethrough+ =monospaced=

[[https://nickhigham.wordpress.com/][Link description]]

https://nickhigham.wordpress.com/ A link without a description.

A DOI (digital object identifier) link: 
[[doi:10.1093/comnet/cnv016][Matching Exponential-Based and Resolvent-Based Centrality Measures]]

A horizontal line, fill-width across the page:
-----

- First item in a list.
- Second item.
  - Sub-item
    1. Numbered item.
    2. Another item.
- [ ] Item yet to be done.
- [X] Item that has been done.  

LaTeX macros can be included: $x_2 = \alpha + \beta^2 - \gamma$.

**** TODO A todo item.
**** DONE A todo item that has been done.

#+BEGIN_QUOTE
This text will be indented on both the left margin and the right margin.
#+END_QUOTE

: Text to be displayed verbatim (as-is), without markup 
: (*bold* does not change font), e.g., for source code. 
: Line breaks are respected. 

Some MATLAB source code:
#+BEGIN_SRC matlab
>> rand(1,3)
ans =
   5.5856e-01   7.5663e-01   9.9548e-01
#+END_SRC

Some arbitrary text to be typeset verbatim in monospace font:
#+BEGIN_SRC text
Apples, oranges,
cucumbers, tomatoes
#+END_SRC

# Table and spreadsheet.  The column headed "Ratio" is automatically
# calculated by hitting C-c C-c in Emacs on the #+TBLFM line.

|----------------+-----------+-----------+-------|
| Country        | Abstracts | Downloads | Ratio |
|----------------+-----------+-----------+-------|
| United States  |         7 |       497 |  71.0 |
| Unknown        |         4 |        83 |  20.8 |
| United Kingdom |         3 |        41 |  13.7 |
| Germany        |         3 |        29 |   9.7 |
| Netherlands    |         2 |        21 |  10.5 |
| Japan          |         1 |        18 |  18.0 |
|----------------+-----------+-----------+-------|
#+TBLFM: $4=$3/$2;%.1f

Include an image:
file:nickhighamwordpress.jpg

I have put the source on GitHub along with the results of exporting the file to txt, LaTeX, PDF (direct link), and html. I include conversions done two ways:

  • With Emacs: the recommended way.
  • With Pandoc. This is useful if you do not use Emacs or want an easy way to automate the conversions. However, Pandoc does not support all Org syntax and has different defaults, so the conversions are not identical.

For more about Org see my previous writings and videos such as Using Emacs 2 – org and Getting Started With Org Mode.

Emacs and Org Mode: What People are Saying

For a couple of years I’ve been collecting tweets about Emacs and Org mode. With the Twitter app’s new ability to provide code to embed tweets I decided to create a post listing the collection. If you are not an existing user of Emacs or Org mode these tweets should give you a feel for whether you might want to explore further. If you are already a convert then many of the sentiments expressed here will be familiar. Note that the links and hashtags below are clickable. (Like all of this Blog, this post was written in Org mode.)

https://twitter.com/K1Hedayati/status/504539678310424576

https://twitter.com/NeilDunbar66/status/364698349166800896

https://twitter.com/rodet/status/326667805497901059

Emacs Org Mode Version 8: Upgrading and Some Tips

As I mentioned in my post Emacs: The Ultimate Editor?, one of the things I love about Emacs is Org mode, which provides excellent facilities for working with plain text and exporting it to a variety of other formats. Recently I’ve used Org mode to prepare a number of tables within documents that I then export to \LaTeX and compile to PDF. Key here is Org’s ability to easily add or remove rows and columns, sort rows, and even transpose a table (see below). This blog is written in Org mode and exported to WordPress using org2blog.

A couple of months ago, version 8 of Org was released. It has many improvements over earlier versions but also some changes in syntax. In particular, the export engine has been rewritten. These changes are quite likely to break older Org files. Indeed the release notes say Org 8.0 is the most disruptive major version of Org.

Here is a list of problems I’ve experienced and the fixes. I’m currently using Org 8.0.3.

  • Export to Beamer didn’t work until I added 
    (require 'ox-beamer)

    to my .emacs.

  • org2blog was broken in Org 8. A new branch for Org 8 was released at https://github.com/ptrv/org2blog/tree/org-8-support. In my tests org2blog/wp-post-subtree did not work properly: the title was being copied as a section heading. This was quickly fixed by author Peter Vasil earlier this week and org2blog is now working fine for me with Org 8.
  • The syntax for \LaTeX table alignments has changed. In Org <8: 
    #+ATTR_LaTeX: align = |l|...

    In Org 8: 

    #+ATTR_LaTeX: :align |l|...

Finally, here are a couple of useful, but easy to miss, features of Org.

Table Transpose

A new command org-table-transpose-table-at-point in Org 8 provides the array transpose function. With the cursor in the table

a11 a12 a13 a14
a21 a22 a23 a24
a31 a32 a33 a34

M-x org-table-transpose-table-at-point produces

a11 a21 a31
a12 a22 a32
a13 a23 a33
a14 a24 a34

This could be particularly useful in a \LaTeX file, provided orgtbl-mode is being used, as there is no easy way to transpose a \LaTeX table.

Shortcuts

I’m not sure if this is new to ORG 8, but in any case it’s new to me. Type <s followed by tab and an empty source block magically appears: 

#+BEGIN_SRC 
#+END_SRC

Very useful! The following table shows all the available expansions: 

|----------+------------------|
| Sequence | Expands to       |
|----------+------------------|
| <s       | #+BEGIN_SRC      |
| <e       | #+BEGIN_EXAMPLE  |
| <q       | #+BEGIN_QUOTE    |
| <v       | #+BEGIN_VERSE    |
| <V       | #+BEGIN_VERBATIM |
| <c       | #+BEGIN_CENTER   |
| <l       | #+BEGIN_LaTeX    |
| <L       | #+LaTeX          |
| <h       | #+BEGIN_HTML     |
| <H       | #+HTML           |
| <a       | #+BEGIN_ASCII    |
| <A       | #+ASCII:         |
| <i       | #+INDEX:         |
| <I       | #+INCLUDE:       |
|----------+------------------|