Using Org-Brain
Table of Contents
1. What’s org-brain?
Org-brain is a package (available on MELPA and elsewhere) by a developer known as “Kungsgeten” on github. It assists in doing concept mapping within Emacs. Concept mapping might be thought of as a generalization of mind mapping, except that relationships between items are not strictly hierarchical. For instance, an item can have several parents, not just one.
I won’t try to explain it further; it’s easy enough to look up, and from here on I’ll assume you have at least passing familiarity.
Kungsgeten wanted to mimic the basic functions of a commercial (expensive) program called “The Brain.” He succeeded to a certain degree, as I’ll discuss.
2. What can it do?
Org-brain allows you to build and display concept maps, with a number of limitations and quirks.
3. Caution
Now, be forewarned: org-brain doesn’t quite work as advertised. The documentation on the github page is sketchy and somewhat non-intuitive. There is a tutorial video on YouTube based on an out-of-date version of org-brain, and the tutorial will at first be quite confusing. I spent a lot of time with trial and error experimentation until I figured out enough to be able to use the tool to produce usable results.
4. Getting it Going
4.1. Basics
Org-brain is built on org-mode, of course, and makes use of a subdirectory (usually just called ’brain’) in your org directory.
I’ll assume you’ve installed org-brain at this point.
Now, how to get started? The command ’org-brain-open’ seems to have disappeared, so you have to start with ’org-brain-visualize’. You’ll be prompted for a name. I suggest you start with ’index’ as your top-level, and hang everything off ’index’ as I’ll describe.
org-brain will then create ’index.org’ in your ’brain’ directory, and show you a visualization buffer. Now you’ll add child entries to your index. Let’s say you want to start to set up projects.
There are two ways to add a child to an entry. One way, with ’c’, creates a file as a child. The filename can’t contain spaces, which is annoying but CamelCase works well enough. So let’s say you create ’Projects’ this way.
The other way is with ’h’ (presumably for ’h’eadline), which creates an org-mode headline in your index (or other parent) file. The headline can contain any text, but nevertheless I think you should create files instead of headlines for most purposes.
So you can move the cursor to ’Projects’ and press enter, and then start entering a series of children for your Project node.
4.2. Resources
Pressing ’l’ will allow you to add a resource, or link, to the active node. The resource has to be in URL format. Org link format will not work. This is quite strange and somewhat annoying. So a file link has to be entered like this:
The link will appear in a “Resources” section at the bottom of the visualization diagram, and clicking on it or pressing Enter on it will open the resource.
5. Overall Comments
org-brain is pretty good, but it has its issues.
- Links are at times illogical
- Naming conventions can be confusing
- It’s a lot more work to create a knowledge representation with this tool than with a graphics-based tool (such as, say, Cmap Tools)
- You can only visualize part of the representation at a time
- Documentation is sketchy and sometimes misleading
- I don’t think it scales well to very large maps and multiple maps
- You’ll have to experiment a lot to get the hang of it
However there are some very good things:
- You stay within Emacs
- It makes use of org-mode
- It is actively developed
- It’s all text mode, making it readable and portable
- No need to ever touch the mouse