org-index.el — A personal index for org and beyond

Table of Contents

Introduction and Overview

org-index helps you to create an index table of favorite locations and references, keeping the most frequently visited lines right at the top.

Or, citing from its documentation:

Mark and find your favorite org-locations and other points of interest
easily; create and update a lookup table of references and links. When
searching, frequently used entries appear at the the top and entering
some keywords narrows down to matching entries only, so that the
right one can be spotted easily.

References are essentially small numbers (e.g. "R237" or "-455-"),
which are created by this package; they are well suited to be used
outside org. Links are normal org-mode links.

org-index helps to find a set of org-nodes and other things easily. You may see it as your private, adaptive index and search engine. It can be used inside and outside of org.

Three scenarios of typical usage

See also A working example for complete examples, that you can readily try out.

Taking notes in a meeting

Lets say, you have a meeting for a project for which you already have a node in org-mode. Now as the meeting starts, you want to go to that node, open it an start taking notes. However, the process of finding that node takes too long and you want to accelerate it.

For this, use org-index and create a line for this meeting within your index table. This line contains a link to the node, where you want to take your meeting-notes and additionally some keywords that you associate with this meeting (e.g. its name).

Next time, when you want to go to that node, simply:

  • Invoke org-index and choose the command "occur" (see The commands of org-index for a list of commands and their description).
  • Type one or more keywords, specific for the project.
  • From the list of results, choose the entry you are looking for.
    • Remark: Your entry will probably appear at the top of the list, because it is sorted by frequency of usage.
  • Type RET to go to this entry and start taking notes.

For frequently used nodes, this can be faster, than finding your node by navigating the outline hierarchy.

Finding the right folder for incoming mail

This assumes that, in your mail program, you have created folders for your favorite projects. An example would be an email folder for a project "R624 Moving to a new internet provider". "R624" in this example is a reference; see References for an explanation.

Now, when a new mail arrives for this project, you can follow these steps to find the correct folder:

  • Invoke org-index and choose the command "occur".
  • Type a keyword, that you associate with this project (e.g. "internet").
  • From the list of results, you can quickly spot the right reference ("R624"), because more frequently used entries appear at the top.
  • With this reference you can find the associated folder within your email-client easily (assuming, that folders in your email program are sorted alphabetically).

This works, because references, like "R624", can easily be used within the names of email-folders.

Marking printed documents with References

By paper mail or in a meeting you receive a printed document. You want to associate it with a certain project and store it away for later. You could proceed like this:

  • Invoke org-index and choose the command "ref", which gives you a new reference (e.g. "R237"). Type some keywords into this new line within your index table; you may also record the physical location, where you keep the document.
  • Now, take a pen and write down this reference "R237" onto the printed document.

Some day later, you might want to read the document again and wonder, where you have stored it:

  • Invoke org-index and choose the command "occur".
  • Enter some keywords for this document; they should overlap with those, that you entered when creating the line within the index table.
  • You see the matching lines from your index table, pick the right one and read the location information, that you recorded initially.

Later again, you might find this document in one of your desk drawers and ask yourself, which project it is associated with. For an answer, you just need the handwritten reference "R237" from the document:

  • Invoke org-index and choose the command "goto".
  • Enter the reference number "237".
  • This brings you to the matching line within your index table, where you can read, what you have entered previously.
  • If your want to visit the org-mode node itself (and not only its line in the index table), invoke org-index again and choose "head".

This shows, how org-index might help to bridge the gap between org-mode and the paper-world.

Some concepts of org-index

References

References (as used within org-index) are small numbers with decorations; examples are "R237", "–455–" or "#323#". You are free, to choose the text before or after the number; org-index inspects the already existing references and creates new references along the same lines. So the next reference after "R237" would be "R238".

References are meant to be easy to type, to write down and remember; you can use them everywhere (not only within org !), where you want to refer to a line within your index table. You may also store additional information Within your index table, e.g. remarks or links to org-mode nodes.

The index table

The index table keeps all your references and links; it counts, how often they have been used. Additionally it also records the date of creation and last access. Moreover it is highly useful to keep some description or a set of keywords within your index table, which can then be searched with the command "occur".

You do not need to create your index table by hand. Just invoke org-index, which will initially assist you in creating the table.

Further down below there is A working example; here is the actual table from this example:

|     | Type    | description    | Keywords       |         |      |                 |                       |
| Ref |         | ;c             |                | count;s | link | created         | last-accessed         |
|     |         |                |                |         | <4>  |                 |                       |
|-----+---------+----------------+----------------+---------+------+-----------------+-----------------------|
| R2  | project | bar            | support, legal |       8 |      | [2012-12-07 Fr] | [2013-03-16 Sa 10:24] |
| R3  | paper   | printed report |                |       3 |      | [2012-12-04 Di] | [2013-03-15 Fr 22:07] |
| R5  | project | baz            | financial      |       5 |      | [2012-12-05 Mi] | [2012-12-08 Sa 23:03] |
| R6  | project | qux            | sport          |       3 |      | [2012-12-08 Sa] | [2012-12-08 Sa 23:01] |
| R1  | project | foo            | support        |       3 |      | [2012-12-03 Mo] | [2013-03-15 Fr 19:26] |
| R4  | folder  | directory      |                |       2 |      | [2012-12-08 Sa] | [2012-12-08 Sa 23:04] |

Links

org-index also supports links, which are just normal org-mode links as described in the documentation of org-mode. They essentially consist of the id (stored in the property-drawer) of an org-mode node.

Finding an org-mode node by its link is typically much faster, than finding it by its reference. So it is useful to keep both in your index table.

Installation and setup

Please note, that the working example below brings its own, non-permanent setup instructions: Setting up things for this example

If, however, you want to install org-index permanently, just read on.

Obtaining

org-index.el comes as a contributed package of org and can be found within the directory contrib of your org-mode distribution.

Modifying your .emacs

Citing from org-index own documentation:

Setup:

  - Add these lines to your .emacs:

    ;; use the real path from your org-installation
    (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t) 
    (require 'org-index)

  - Restart your emacs to make these lines effective

  - Invoke `org-index', which will assist in creating your index
    table. The variable org-index-id will be persisted within your
    customization file (typically .emacs).

Thats it. You may now invoke org-index. Read below, to learn what will happen.

Let the builtin assistent create your index table

When you invoke org-index for the first time, it will notice, that the index table needs to be created first. For that goal the builtin assistant will ask you some questions (like the file where you want to store your index table and the name of its node).

Afterwards you will be dropped within the newly created node, where you may read the notes explaining its structure.

A Suggestion on keyboard shortcuts

If you use org-index a lot, you will probably want to assign it a custom keyboard shortcut. Emacs reserves "C-c" followed by a single letter for user defined custom shortcuts. If you choose the letter "i" to resemble "index", you may use "C-c i" to invoke org-index; add this to your .emacs:

(global-set-key (kbd "C-c i") 'org-index)

If you want to choose specific commands of org-index, with a single key sequence, you may add a new prefix map and assign individual letters along these lines:

(define-prefix-command 'org-index-map)
(global-set-key (kbd "C-c i") 'org-index-map)
(define-key org-index-map (kbd "o") (lambda () (interactive) (org-index 'occur)))
(define-key org-index-map (kbd "r") (lambda () (interactive) (org-index 'ref)))
(define-key org-index-map (kbd "l") (lambda () (interactive) (org-index 'leave)))
(define-key org-index-map (kbd "h") (lambda () (interactive) (org-index 'head)))
(define-key org-index-map (kbd "i") (lambda () (interactive) (org-index)))

This way, you have quick access to the occur-command by typing "C-c i o" and can still invoke org-index through "C-c i i" access some less frequently used commands.

A working example

This node contains a simple setup, which can be used to explore org-index. Further below there is also A sample for an index table.

These examples revolve around the few most common usecases and only employ a very limited set of commands (mainly "occur" and "ref"). Below at The commands of org-index you will find much more commands (e.g. "sort" or "highlight") that can become quite helpful, once you have mastered the basic functionality.

Setting up things for this example

To really try out the things described here, you need to go through some minimal preparations: Open two files in your browser, copy-and-paste them into emacs and execute two lines of elisp-code.

But of course, you can still go ahead, skip these setup instructions and just read things without actually trying them.

These instructions are non-permanent; after your next emacs restart you wont be able to use org-index any more. To install it permanently follow these instructions: Installation and setup.

Get org-index.org

Read this text within org-mode in emacs, especially to have all the org-mode nodes, that are used in this example. Reading this text in a browser is still instructive but does not give you the full hands-on experience. So, if you are reading the browser-version of org-index.org, open:

http://orgmode.org/worg/org-contrib/org-index.org

in your browser. Mark the whole page and copy-and-paste it into your emacs: Create a new buffer "org-index.org", do "M-x org-mode" and paste. Continue reading within this new emacs-buffer.

Eval org-index.el

Open org-index.el from the contrib/lisp-directory of your org-installation.

To make emacs read and evaluate the the elisp-code you need to say "M-x eval-buffer" within the new buffer.

Configuration

Finally, you have to execute two lines of elisp: place your cursor at the end of each line and type "C-x C-e" (which runs "eval-last-sexp").

(setq org-index-id "848c6d2a-6e8b-4c93-8481-19e6db7e6ca8")
(global-set-key (kbd "C-c i") 'org-index)

This will instruct org-index to use the index table further below in this document. This table (and so this document as a whole) will change as you follow along these examples.

First example: Finding a node by its name

Say, your are in a meeting about project "bar" and want to take notes. For this you need to visit the node for project "bar".

Type "C-c i" to invoke org-index and then type "bar" and RET. This will create a new buffer named org-index-occur with one line:

| R2 | project | bar | support, legal | 8 |   | [2012-12-07 Fr] | [2012-12-08 Sa 23:37] |

Now, to visit the node with the reference R2, move the cursor onto this line and type RET. This will also increment the count of this line within the index table from 8 to 9, giving it a higher rank in future searches (you can check this by visiting the index table below.

This search resembles emacs classical occur-feature (and whence its name); however, it is incremental: If you are not satisfied with the results of your initial search, you may correct your search term anytime by deleting characters or typing new ones. The content of the occur-buffer will change accordingly after each character.

Remark: even though the initial prompt of org-index offers only a fixed set of choices, you may just as well type something else (e.g. "bar") to implicitly accept the first choice (here: "occur") and directly supply input ("bar") for the default command ("occur").

Secound example: Finding a node by keyword

Later you want to take some notes for project "bar" but do not recall its name. However, you know that the project is related with "support".

So you type "C-c i" to invoke org-index. Then type "support" and RET.

After this you will see these two lines (R2 and R1) from your index table, which contain the keyword "support":

| R2 | project | bar | support, legal | 9 |   | [2012-12-07 Fr] | [2012-12-08 Sa 23:37] |
| R1 | project | foo | support        | 3 |   | [2012-12-03 Mo] |                       |

The first line "R2" is the one with the highest access count (9), because the table is kept sorted by this column. This line already represents your project "bar". Now just hit RET, to visit this node.

Third example: Find the right folder for an incoming mail

This example assumes, that within your email-client you have organised messages in folders, the names of which start with a reference, e.g. "R2 bar".

Compared to the straightforward approach of naming the folder just "bar", the overhead related with including the reference within the name allows you to use org-index as your search-engine for email-folders.

This is especially helpful, if you have dozens or even hundreds of folders, which can be too many to spot the right one easily.

Moreover, if you later need to rename your project from "bar" to "qux", the reference can be left unchanged and your mail folder appears at its usual place.

Now lets assume, that you get an email related to project "bar" and want to move it into the right folder.

So you type "C-c i" to invoke org-index and then "bar" and RET.

Just as in the first example, this is what you get:

| R2 | project | bar | support, legal | 9 |   | [2012-12-07 Fr] | [2012-12-08 Sa 23:37] |

(Please note, that the count has changed from 8 to 9, if you have followed along the examples before.)

From the line displayed you can easily spot the reference "R2" and find the right folder within your email-client.

Fourth example: Create a new reference for a new piece of paper

In a meeting, you get handed a printout; a discussion starts and you want to keep track of it. And within your org-mode notes you want to refer to the printout, that is the focus of the discussion.

For this you can create a new reference: Type "C-c i" to invoke org-index and then type "ref" and RET.

This will create a new row within your index table with a new reference already filled in (if you try it out yourself, it will probably be "R7"). Now, you can fill out the other columns, especially description and keywords.

Then you should write the new reference "R7" onto the printout, so that later (see the next example) you will be able to look it up.

Once you are done, leave the index table by typing "C-c i" and "leave" RET.

Remark: The closely related example below assumes reference "R3"; it is just as good as "R7".

Fifth example: Looking up a reference you find on a piece of paper

Lets assume, that in one of your drawers you find a lengthy printout. On its cover page you spot the handwritten reference "R3".

First you would like to know the date, when you received this document. For this, simply type "C-c i", then "3" and RET.

As a result you will see something similar to the lines below:

continue here

9 matches total for "\_<R-3\_>":
9 matches in buffer: org-index.org
    160:   | R-3  | paper   | printed report |                |       3 |      | [2012-12-04 Di] | [2013-03-15 Fr 22:07] |
    440:   Remark: The closely related example below assumes reference "R-3"; it is
    446:   its cover page you spot the handwritten reference "R-3".
    471:   Which is a multi-occur for reference "R-3". 
    473:   Please note, that in the cited example output above, the reference "R-3"
    478:   reference "R-3"; that way it should be easy, to find your org-mode notes
    489:    - [ ] Read paper R-3
    518:   | R-3  | paper   | printed report |                |4|      | [2012-12-04 Di] | [2014-01-03 Fr 14:39]                      |
    528:   | R-3  | paper   | printed report |                |       3 |      | [2012-12-04 Di] | [2013-03-15 Fr 22:07] |

Which is a multi-occur summary for reference "R3".

Please note, that in the cited example output above, the reference "R3" has been replaced with "R-3". This avoids, that this citation itself appears in your output again, if you try the example yourself.

The output above tells you, where in all your org-mode files, you have used reference "R3"; that way it should be easy, to find your org-mode notes about this paper. The list also includes the matching line from your index table, which tells you, when this reference has once been created.

Example nodes

The subnodes below are made up only to be used within the examples above. Their contents is therefore fictous.

TODO R1 Project foo

  • [ ] Read paper R3

TODO R2 Project bar

  • [ ] Talk to Jim

DONE R5 Project baz

  • [X] Clean up directory R4

TODO R6 Project qux

  • [ ] Clean running shoes

A sample for an index table

|     | Type    | description    | Keywords       |         |      |                 |                       |
| Ref |         | ;c             |                | count;s | link | created         | last-accessed         |
|     |         |                |                |         | <4>  |                 |                       |
|-----+---------+----------------+----------------+---------+------+-----------------+-----------------------|
| R2  | project | bar            | support, legal |       8 |      | [2012-12-07 Fr] | [2013-03-16 Sa 10:24] |
| R3  | paper   | printed report |                |       3 |      | [2012-12-04 Di] | [2013-03-15 Fr 22:07] |
| R5  | project | baz            | financial      |       5 |      | [2012-12-05 Mi] | [2012-12-08 Sa 23:03] |
| R6  | project | qux            | sport          |       3 |      | [2012-12-08 Sa] | [2012-12-08 Sa 23:01] |
| R1  | project | foo            | support        |       3 |      | [2012-12-03 Mo] | [2013-03-15 Fr 19:26] |
| R4  | folder  | directory      |                |       2 |      | [2012-12-08 Sa] | [2012-12-08 Sa 23:04] |

The commands of org-index -ch-

When you invoke org-index, it will prompt to choose one from a set of commands:

occur: Incremental search, that shows matching lines from the
  index table, updated after every keystroke. You may enter a
  list of words seperated by space or comma (","), to select
  lines that contain all of the given words.

  If you supply a number (e.g. "237"): Apply emacs standard
  multi-occur operation on all org-mode buffers to search for
  this specific reference.

  You may also read the note at the end of this help on saving
  the keystroke RET with this frequent default command.

head: If invoked outside the index table, ask for a reference
  number and search for an entry, which either has this
  reference contained in its heading or within its property
  org-index-ref. If invoked from within the index table dont
  ask; rather use the reference or link from the current line.

ref: Create a new reference, copy any previously selected text.
  If already within index table, fill in ref-column.

link: Create a new line in index table with a link to the
  current node.  Do not populate the ref column; this can later
  be populated by calling the "fill" command from within the
  index table.

leave: Leave the index table. If the last command has been
  "ref", the new reference is copied and ready to yank.  This
  "org-mark-ring-goto" and can be called several times in
  succession. If you invoke org-index with a prefix argument,
  this command "leave" is executed without further questions.

put: Put the reference, that was created last, as the value of
  property org-index-ref into the current node. That way it can
  be found by a later call to "head". 

enter: Just enter the node with the index table.

goto: Enter index table and go to a specific reference.

help: Show this text.

+: Show all commands including the less frequently used ones
  given below. If "+" is followd by enough letters of such a
  command (e.g. "+fi"), then this command (e.g. "fill") is
  invoked directly.

reorder: Temporarily reorder the index table, e.g. by count,
  reference or last access.

fill: If either ref or link is missing in current line of index
  table, fill in the missing value.

sort: Sort a set of lines (either from the active region or the
  whole buffer) by references found in each line.

update: For the given reference, update the line in the
  index table, i.e. increment its count.

highlight: Highlight references in active region or buffer.

unhighlight: Remove those highlights.

missing : Search for missing reference numbers (which do not
  appear in the reference table). If requested, add additional
  lines for them, so that the command "ref" is able to reuse
  them.

statistics : Show some statistics (e.g. minimum and maximum
  reference) about index table.

Please note, that you are not required to explicitly choose one of these commands when prompted by org-index. Simply typing something else (e.g. "237") accepts the default-command and supplies your input as an argument.

Further Reading, Version, Contact

org-index.el itself contains embedded documentation, which can be easily accessed through the command "help". Most, but not all of it has already been cited within this document.

As of [2014-01-03 Fr] this document describes version 2.4.0 of org-index.

Remaining questions or feedback should be directed to:

org-index@2484.de

Documentation from the http://orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.