Monthly Archives: September 2015

Search with OS X Spotlight from emacs

I wrote previously about an idea to use the spotlight search tool in Mac OS X from within emacs. At the time, I put together some pretty crude code to do this, but I have now improved it into a package that I am quite pleased with.

The package is spotlight and is available now to install through MELPA.

The package gives you a powerful way to call spotlight from emacs. You can do a live search for a string in the text of a file, filter the file list by file name and then open the selected file with a swiper search for your query text.

Here is an example of my using it. In the animation below, I use M-x spotlight to run a spotlight search for “tomatoes”. Notice how the number of matches updates as I type or delete the last couple of characters. I then use M-RET to narrow the list of matching files using the string “docs org$” which narrows the list to files with “doc” in their full name, and with names ending in “org”. Finally once I select the file I want, swiper takes me to the matches of my original “tomatoes” query.

spotlight.gif

See the README on github for more details.

The package relies on the excellent ivy and swiper libraries to do the hard work, and benefited greatly from useful comments by redditors at /r/emacs.

Org-mode basics IV: formatting text and source code

This is a continuation of my series of introductory posts on org-mode that are focussed on simple text-based notes. We looked already at structuring your notes and adding tables and links and images to your notes. In this post we will look at formatting the text in your notes.

For today we will look at the effect of formatting on the plain text view of your notes, but very soon we will come to exporting your notes to html and pdf and we’ll see that the formatting is applied to the exported documents very nicely.

We will also look at including executable code in your notes. Hopefully you can see that by putting all these pieces together you can build a very powerful document of your research containing your data, notes, relevant links, source code and results.

As before I suggest adding the notes below to your growing org file. For technical reasons I have to display the notes as plain text below but if you paste them into your org file you’ll see them nicely formatted and coloured like this:

* Formatting text
** Simple formatting
You can apply simple formatting to your text by enclosing words in
special characters. These include
 - /italicised text/
 - *bold text*
 - _underlines_
 - =literal text=
 - ~code~ (generally appears the same as literal text)

Here are the full notes:

* Formatting text
** Simple formatting
You can apply simple formatting to your text by enclosing words in
special characters. These include
 - /italicised text/
 - *bold text*
 - _underlines_
 - =literal text=
 - ~code~ (generally appears the same as literal text)

** Formatted blocks of text
For longer pieces of text you can enclose the text in blocks marking
it as a specific sort of text. I commonly use these ones

#+BEGIN_EXAMPLE
This is an example block into which you can type text that you don't want org to mess with like a [[link]]. This will typically be rendered in a monospace font when exported.
#+END_EXAMPLE

#+BEGIN_QUOTE
This block encloses text that you want to appear as a quotation.
#+END_QUOTE

#+BEGIN_CENTER
This text will be centred when it is exported.
#+END_CENTER

You can save time typing out the block wrapper by using shortcuts. Go
to the start of a new line and type <e and press TAB and it will
expand to an example block. The same works for <q for quote and <c for
centre.

** LaTeX
Org-mode does a good job of understanding snippets of LaTeX (a
[[https://www.latex-project.org/][powerful typesetting language]] used in scientific and other technical
documents). For example, it will correctly export simple superscripts
x^2 or subscripts x_0 or symbols like \alpha, \beta, \gamma.

Org also understands more complex LaTeX like this

\begin{eqnarray}
x^2 + \left(\frac{y}{z}\right)^4 = 0
\end{eqnarray}

but for longer bits of LaTeX it is better to use a LaTeX block. You
start one with <l and TAB

#+BEGIN_LaTeX
LaTeX code goes here
#+END_LaTeX

** Source code blocks
It is also handy to include source code in your notes - on a new line
type <s and TAB to create a source block. You can tell org what type
of code is contained - in this case we'll put in some simple shell
code, so well put "sh" at the top of the block.

#+BEGIN_SRC sh
  echo "Hello $USER! Today is `date`"
  exit
#+END_SRC

You can get org to syntax highlight the text in the block by adding
the following to your [[http://pragmaticemacs.com/emacs/editing-your-emacs-config-file/][emacs config file]] (without the source block
wrapper of course).

#+BEGIN_SRC elisp
;;syntax highlight code blocks
(setq org-src-fontify-natively t)
#+END_SRC

What is more, when the cursor is inside a SRC block, you can use C-c '
to create a new temporary buffer in the major mode of the programming
language you have specified. Type some code in, and then type C-c '
again to come back to this buffer.

** Executing source code blocks
Org-mode can execute your source code blocks and add the output to
your file. This part of org-mode is called babel. I'll write more
about this later, but it is too cool not to mention here.

For example, take the simple code block we had above:

#+BEGIN_SRC sh
  echo "Hello $USER! Today is `date`"
  exit
#+END_SRC

Put the cursor inside the block and hit C-c C-c to execute it. You
will be asked to confirm and then you should see the output appear
like this:

#+RESULTS:
#+begin_example
Hello bjm! Today is Fri 25 Sep 2015 15:03:12 BST
#+end_example

You can do much more with this, like reading input data from a table
in the same file, creating images that appear in the file, extracting
(tangling) all the code snippets into one or more files to be executed
separately, and much more. [[http://orgmode.org/worg/org-contrib/babel/intro.html][Here are some nice examples]].

You can tell org-mode which programming languages to support by adding
something like the following to your [[http://pragmaticemacs.com/emacs/editing-your-emacs-config-file/][emacs config file]]:

#+BEGIN_SRC elisp
;; Some initial languages we want org-babel to support
(org-babel-do-load-languages
 'org-babel-load-languages
 '(
   (sh . t)
   (python . t)
   (R . t)
   (ditaa . t)
   (perl . t)
   (gnuplot t)
   ))
#+END_SRC

Make all prompts y or n

Emacs prompts you at various times to answer yes or no to something. If you add the following to your emacs config file, you will only have to hit y or n saving you countless seconds!

;; change all prompts to y or n
(fset 'yes-or-no-p 'y-or-n-p)

This basically aliases the built in “yes or no” prompt function to the built in “y or n” prompt function so that the latter is always used.

Org-mode basics III: add links and images to your notes

In this series of introductory posts on org-mode we have been focussing on simple text-based notes. We looked at structuring your notes and adding tables to your notes. Next we will look at adding links and images. Links can be to files, URLs or locations in the current org document. If the link is to an image then emacs can display it inline in the org document. This is handy for enhancing your notes and will also be useful when we come to look at exporting to different formats.

As before I suggest adding the notes below to your growing org file. Note that below I have formatted the notes as plain text because org-mode changes the appearance of links, such as hiding the [] around links, which is nice in your org-mode document but makes it harder for me to show you what is going on!

* Links and images
Org mode supports links to files, URLs, and to other points in the org
file. In this example let's use an image from my website. First copy
it to the current directory. You can do this within emacs but for now
just run this command in your terminal.

curl http://www.star.bris.ac.uk/bjm/superman_cluster.gif -o superman_cluster.gif

To add a link to a file use C-u C-c C-l and type the name of a file.
Use tab-completion to select the image we just copied and you will
then be asked for a description - you can press enter to leave this
blank. This will create a link that looks like this

[[file:superman_cluster.gif]]

If you do this in your org file, you wont see the [[ ]] above, instead
you'll see the text as a clickable link.

Since the file we have linked to is an image, we can tell emacs to the
image in the document using C-c C-x C-v and use the same command to
turn the image off again.

You can also click the link with the mouse, or use C-c C-o to follow
it, which might open your web browser, an image viewer or open a file
in emacs depending on the target of the link.

The structure of a link in org mode looks like this

#+BEGIN_EXAMPLE
[[link address][description]]
#+END_EXAMPLE

(I've enclosed the link in an example block which prevents org-mode
from trying to interpret as a real link, for the purpose of showing
its structure - we'll come back to blocks like this later.)

The link address is the URL or file name, and the description is the
text that is displayed, so we can replace our superman link with
something tidier like [[file:superman_cluster.gif][this]].

Links to web pages are easy - just put the http address in as the link
address. Use C-c C-l as a quick way to add such a link (remember we
used C-u C-c C-l is for adding a link to a file).

Links to other parts of the org file are added easily like [[Links and
images][this link]]. Because the address part of the link matches a
headline in this document, then org-mode points the link to that part
of the file. Clicking it will move the cursor there.

Finally, we can add a caption and a name to our image like this

#+CAPTION: Superman and a galaxy cluster
#+NAME: fig.super
[[file:superman_cluster.gif]]

which means we can refer to our image later with a link like this one
[[fig.super]]

That’s all for now. Next time I think we’ll look at some simple text formatting.

Edit files inside zip or tar archives

This is as easy as opening a .zip file in emacs. You will be shown a dired style file browser (in Zip-Archive mode) in which you can open files and edit and save them as normal, without having to extract them from the archive. You can also do a few other things to the files in the archive – use C-h m to see the help for the current major mode.

Similarly, opening a .tar (or even a compressed .tar.gz) archive will open the contents in Tar mode. This is very similar to the above, except that once you edit a file, you have to go back to the Tar mode buffer and save that to update the original archive file (this is automatic in Zip-Archive mode).

Org-mode basics II: use simple tables in your notes

In the first post of this series we looked at using org-mode to structure your notes. Today we’ll look at adding simple tables to your notes. Later we’ll see how these tables can be used for advanced features like spreadsheet style calculations, or using them as the input and/or output of code, and also how they export nicely in html or pdf documents. For now we’ll just use them as simple static tables in our notes.

I suggest adding the text below to the org file from last time to build an org-mode notebook on how to keep org-mode notebooks!

* Tables
Hopefully you can see straight away that the simple structure provided
by org-mode gives a nice way to keep an electronic note book.

Often it is nice to include tables in our notes. Org handles this by
using | to separate columns, and a line of --- (inserted with C-c -)
to add horizontal lines.

Exercise: start typing in this table below; type the first line in
verbatim
 1) when you get to the "s" of comments, press TAB to go to the next
    line
 2) go up to the previous line and use C-c - to add the row of dashes
 3) next enter a few lines of data, using TAB to go through the
    cells - you should notice the columns changing width as needed

| ID | x |  y | comments       |
|----+---+----+----------------|
| A  | 2 |  4 | blah           |
| B  | 3 |  9 | blah           |
| C  | 4 | 16 | blah blah blah |
| D  | 5 | 25 | blah           |

Now, you can move rows and columns around using M-arrow and insert or
delete rows and columns using M-S-arrow. Try this out now.

** Creating and exporting tables
You can create an empty table using C-c | to run the command
org-table-create-or-convert-from-region, which will prompt for table
dimensions if no region is selected.

The same command can easily convert some text to a table; select the
following text and use C-c | to run the command
org-table-create-or-convert-from-region again to convert the text to a
table

 ID  x   y
 A   2   4
 B   3   9
 C   4  16
 D   5  25

You can also save tables to their own files by putting the cursor in
the table and using M-x org-table-export. You'll be asked for a
file name and a format. For the format, type orgtbl-to and press TAB
to see the available options (e.g. orgtbl-to-csv will convert to csv
in the output file).

** Formulae
You can use formulae to do arithmetic on tables, and use them like a
spreadsheet. This is something I keep meaning to use more often, but
don't generally find I need it. One useful command is C-c + which runs
org-table-sum to sum the numbers in the current column.

For more on this, see e.g. this introduction. Notice that we just
added a link in our org-mode file - this is a teaser for what we will
cover next!