emacsrookie.com

Do what you have to do

tonini.samuel@gmail.com (Samuel Tonini) — Wed, 26 Oct 2011 00:00:00 CEST

In the article Capture the monkey I wrote about the Capture feature from Org Mode, which gives you the ability to create task items on the fly. Now I will show you how I use this feature to create so-called TODO items.

You will see that the introduction I give you is enough to start and use the TODO feature to be productive in your task management daily grind. If you're looking for more detailed information about the TODO items, please consider to read the Org Mode manual.

Here's how to use it

Ok, let's create our first TODO item.

To structure an Org Mode document you use headlines, and these start with one or more stars:

* Top level
** Second level
*** Third level

Now you see how to create headlines, to make a headline into a TODO item, just add the word TODO after the stars and you get your first TODO item:

** TODO Create your first todo item

By default, a TODO item has two states, TODO and DONE and to rotate through the different states use (org-shiftright) or (org-shiftleft) functions. At this time it just switches between TODO and DONE, but later when you have more keywords, it will also iterate through these.

Example of a TODO item and a finished one marked as DONE:

** TODO Not done yet!
** DONE I'm done!
   CLOSED: [<Timestamp>]

You see that in the DONE marked task item is a CLOSED keyword with a timestamp beside it. By default, if you finish a task item Org Mode will add a timestamp and a CLOSED keyword, to inform you about the finished time of the task. This is very helpful to get more information in the agenda view.

By default the variable org-log-done is set to 'time, which means that after you finish a task a timestamp will be added, as already mentioned above. But you could also add a note. Just assign 'note to the org-log-done variable and Org Mode will prompt you for an additional note along with the timestamp.

One of my favorite features I couldn't work without are the clock commands. Imagine you're starting with a new task, you have to fix a bug in your code and have to manage the time you need to fix it. Org Mode comes along with punch-clock powers, which makes this kind of job very easy.

The function (org-clock-in) starts the clock on the current item you're in and the vice-versa function (org-clock-out) stops the clock.

Check out what this looks like:

** TODO what's the amount of time needed
   CLOCK: [2011-10-26 Wed 14:31]--[2011-10-26 Wed 15:10] =>  0:39

In the example above I started the clock and stopped the clock 39 minutes later. This feature is really great, because in the agenda view of Org Mode this clock information will give you an overview over how long we needed to fix our bugs.

For now you know enough to manage your task items. Go ahead and try this out.

Next I will show you how easy it is to create your own TODO like keywords, for example something like FEATURE, BUG or SUPPORT.

Your own keywords

In my daily grind I use a few more keywords than just a simple TODO for my tasks. Org Mode gives you the possibility to add our own keywords really easily. The variable org-todo-keywords gets all the task types we want to have:

(setq org-todo-keywords
       '((sequence "TODO" "|" "DONE")
       (sequence "FEATURE" "|" "COMPLETED")
       (sequence "BUG" "|" "FIXED")
       (sequence "|" "CANCELED")))

Great, now you're ready to use this just like TODO before.

What I really like is the possibility to create fast access TODO states by just adding single keys in parentheses after a keyword.

Fast access state keys:

(setq org-todo-keywords
       '((sequence "TODO(t)" "|" "DONE(d)")
       (sequence "FEATURE(f)" "|" "COMPLETED(c)")
       (sequence "BUG(b)" "|" "FIXED(x)")
       (sequence "|" "CANCELED(a)")))

If you now use the (org-todo) function, Org Mode prompts you for the kind of task key which you want to use, so you don't have to cycle through the task types with the (org-shiftleft) or (org-shiftright) functions anymore.

Functions and default keybindings

Function	Keybinding	Description
org-shiftright	S-RIGHT	Cycling through the item state forwardly.
org-shiftleft	S-LEFT	Cycling through the item state backwards.
org-clock-in	C-c C-x C-i	Start the clock in the current task item.
org-clock-out	C-c C-x C-o	Stop the clock in the current task item.
org-todo	C-c C-t	Change the TODO state of an item. If other keywords are set it prompts for one of these..

Summary

You see Org Mode's TODO feature is very powerful and still easy to use. You get in touch with it in no time and you can use it for your daily programming routine.

There is certainly a lot of more stuff about the TODO Org Mode feature and it would be wise of you to check it out. Org Mode TODO manual

Capture the monkey

tonini.samuel@gmail.com (Samuel Tonini) — Mon, 17 Oct 2011 00:00:00 CEST

The first Emacsrookie article was about Remember, an Emacs built in package to create new tasks on the fly. There I promised to write a new article about how to do the same in a more recent way, with Capture.

I will show now how to use Capture, the way how Org Mode handles capturing new tasks on the fly. Capture is highly inspired by the Remember package and I recommend to switch to it if you still use Remember.

But why it's so great? It's really easy to use, it's built in Org Mode and it brings powerful abilities to create and customize new task templates.

Let's check it out!

Here's how to use it

Org Mode ships in with Emacs. But if you like to get a more recent version of Org Mode, please check the install section in the Org Mode manual.

To create your first task, you have to define a default file in which the task should be added.

Just leave the path to the file in the following variable:

(setq org-default-notes-file (concat org-directory "/tasks.org"))

Done, now you're ready to go!

Org Mode gives you the function org-capture to open the *Org select* buffer. At first, you just have three points to choose from, create a new task item, open customize (for create new Capture templates) or quit the buffer.

You should create a new task item at the outset, to get a feeling how it works. You shouldn't have any problems to create a task, it's very self-explinatory.

Maybe at this point you ask yourself what's about this Capture template stuff you read about in the *Org select* buffer.

Let's see what this template stuff is all about.

Templates

Capture gives you the ability to create your own templates for new task items. You just have to define a list for each of your templates and assign them to the org-capture-templates variable.

(setq org-capture-templates
      '(("t" "Todo" entry (file+headline "~/org/tasks.org" "Tasks")
             "* TODO %?\n  %t")))

Ok, let's see what kind of a template we have defined. When you create a template, you need to set the following items in the list:

Item value	Description
keys	A string which is used as a key for the template selection.
description	The description of the template.
type	The type of a new item.
target	The specification where the new item should be placed.
template	The template for creating the capture item.
properties	Additional properties.

Check the manuel for detailed information.

Capture has some nice template expansion and you should read through the list.

In the above template definition I just used %? and %t. I mostly use them because I'm not a fancy boy. %? means that after completing the template, the cursor will be positioned there. And the %t is a simple date only timestamp which I use because I want that my new TODO item will be shown up in the agenda view of Org Mode.

Let's define a new keybinding to your new Capture template, so you don’t have to go through the selecting process when you want to create a new task item:

(define-key global-map "C-c t"
  (lambda () (interactive) (org-capture nil "t")))

So now you could create a new task item with C-c t without going trough the template selection.

Some customization

I use Org Mode for a lot of things, also these article are written in Org mode. I manage also all my project with it, and because I have to switch between them through the day, I have written some code to create new items for a specific project on the fly.

First a variable which holds the path to the projects org files:

(defvar custom--org-project-file-path
  "~/org/projects/")

Second I defined a method who returns all the files which are in the org projects path:

(defun custom-org-project-files
  (directory-files custom--org-project-file-path nil "\\.org$"))

Then I created a method which prompts for one of my project org files and I used the completing-read function to get a nice file completing on my org project files:

(defun custom-org-project-chooser ()
  (let ((completing-read-func (if (null ido-mode)
                                  'completing-read
                                'ido-completing-read)))
    (setq project-file
          (funcall completing-read-func
                   "Project: "
                   (custom-org-project-files)
                   nil
                   t))))

You can see in the code example above that I decided to use the function ido-completing-read instead of completing-read if ido-mode available. (Check out ido-mode for further informations.)

After that I put my custom-org-project-chooser function in a helper function where I define in which file the new task item should be placed and where in the file the task should be positioned.

I used in the re-search-forward function with a speficied regulary expression to find the position in the file where I want to put the task.

In my case I always put it after the project title header (like: * My Project).

(defun custom-org-project-file ()
  (find-file (concat custom--org-project-file-path (custom-org-projects-chooser)))
  (goto-char (point-min))
  (re-search-forward "^\*\s*.+\n" nil t)
  (newline 1))

At last I created a Capture template from the type function which calls my custom-org-project-file function when a new project item will be created:

(setq org-capture-templates
      '(("p" "Project Todo Files" entry (function custom-org-project-file)
         "** TODO %?\n  %T")))

Thats it! Bind this Capture template call to a key you like and you're ready to go and create your own project tasks on the fly.

You find the whole source in my emacs configs repository.

Summary

If you like to manage your task through the day I really recommend Capture and all his capabilites. Check the Capture manual out and get yourself a better overview.

Enter The Dired Dungeon

tonini.samuel@gmail.com (Samuel Tonini) — Mon, 10 Oct 2011 00:00:00 CEST

When I talk with people about Emacs, they often complain about the missing project navigator.

Dired has a lot to offer that doesn't fit in just one article, so I decided to split it into several parts. I start by showing the navigation abilities of Dired.

Throughout the article I won't refer to keybindings but instead to the function names. At the end there will be a list of the functions including the corresponding default keybindings.

Here's how to use it

Dired is built into Emacs, so you don't have to install anything.

Enter Dired by calling the function dired. The minibuffer opens and prompts you to choose a directory to open.

Example of an open Dired buffer:

  /Users/samuel/Projects/basement:
  total used in directory 48 available 151364824
  drwxr-xr-x  10 samuel  staff   340 24 Aug 16:16 .
  drwxr-xr-x  37 samuel  staff  1258  5 Okt 13:54 ..
  drwxr-xr-x  12 samuel  staff   408  5 Okt 22:29 .git
  -rw-r--r--   1 samuel  staff    33 24 Aug 15:55 .gitignore
  -rw-r--r--   1 samuel  staff    92 24 Aug 15:55 Gemfile
  -rw-r--r--   1 samuel  staff   194 24 Aug 16:16 Gemfile.lock
  -rw-r--r--   1 samuel  staff    71 24 Aug 15:57 README.markdown
  -rw-r--r--   1 samuel  staff    28 24 Aug 15:55 Rakefile
  -rw-r--r--   1 samuel  staff   757 24 Aug 16:04 basement.gemspec
  drwxr-xr-x   4 samuel  staff   136 24 Aug 15:55 lib

Dired creates a read-only buffer and lists all the files from your chosen directory.

In the Dired buffer you're able to move around with the usual movement functions. Only the next-line and previous-line functions are redefined. Generally when you use these functions, the cursor will be positioned at the beginning of the line, but in the Dired buffer it goes to the beginning of the file name.

Next what you want to know is the dired-goto-file function, which prompts for a file name in the minibuffer. It moves the cursor in the Dired buffer to the file you've chosen. Most of the time, you want to visit the file of the currently selected line. In this case you use dired-find-file which opens the file straight away without prompting for a file name input.

Maybe you're asking yourself now, but what about sub directories? You have seen how easy it is to navigate in a single directory and visit specific files, maybe you found out that when you use dired-goto-file on a sub directory it will list the files from this directory. But you want a solution with a better overview, something that gives you the parent and the sub directory at one glance. So lets check out what Dired has in store for that scenario.

As you know, Dired just displays one directory at the time. But with the dired-maybe-insert-subdir function, Dired takes the directory on the current line and lists the content of the directory below the parent directory in the current Dired buffer.

Let's see how this looks like:

  /Users/samuel/Projects/basement:
  total used in directory 48 available 151364824
  drwxr-xr-x  10 samuel  staff   340 24 Aug 16:16 .
  drwxr-xr-x  37 samuel  staff  1258  5 Okt 13:54 ..
  drwxr-xr-x  12 samuel  staff   408  5 Okt 22:29 .git
  -rw-r--r--   1 samuel  staff    33 24 Aug 15:55 .gitignore
  -rw-r--r--   1 samuel  staff    92 24 Aug 15:55 Gemfile
  -rw-r--r--   1 samuel  staff   194 24 Aug 16:16 Gemfile.lock
  -rw-r--r--   1 samuel  staff    71 24 Aug 15:57 README.markdown
  -rw-r--r--   1 samuel  staff    28 24 Aug 15:55 Rakefile
  -rw-r--r--   1 samuel  staff   757 24 Aug 16:04 basement.gemspec
  drwxr-xr-x   4 samuel  staff   136 24 Aug 15:55 lib

  /Users/samuel/Projects/basement/lib:
  total used in directory 8 available 151364824
  drwxr-xr-x   4 samuel  staff  136 24 Aug 15:55 .
  drwxr-xr-x  10 samuel  staff  340 24 Aug 16:16 ..
  drwxr-xr-x   3 samuel  staff  102 24 Aug 15:55 basement
  -rw-r--r--   1 samuel  staff   75 24 Aug 15:55 basement.rb

You see, the parent directory is on top and the sub directory you jumped to is listed below. It's an easy and great overview. At this point Dired gives you a few functions to move between the directories. dired-prev-subdir to move up in the directory tree and the vice-versa function dired-next-subdir. Also useful is the function dired-up-directory which runs Dired in the parent directory. It searches in the current buffer for the parent directory or in another buffer, or creates a new one if needed.

Some customization

The variable dired-listing-switches contains the options which are used when ls is called. That means you could define how the command ls should be called when you open a new directory in Dired.

Example:

(setq dired-listing-switches "-lRS")

The - in the dired-listing-switches variable is a must or Dired wont work. I also recommend to add the l option to the variable, as by default just the single file and directory names would be listed. Just fire up the ls man page if you want to see all available options for ls.

Functions and default keybindings

Function	Keybinding	Description
dired	C-x d	Enter Dired.
dired-next-line	C-n / SPC / n	Move to the next line.
dired-previous-line	C-p / p / DEL	Move to the previous line. (DEL also unflags.)
dired-goto-file	j	Prompts for a filename and moves cursor to choosen file in the Dired buffer.
dired-find-file	f / e / RET	Open the file on the current line.
dired-next-subdir	C-M-n	Jumps to the next sub directory.
dired-prev-subdir	C-M-p	Jumps to the previous sub directory.
dired-prev-subdir	^	Run Dired on parent directory of current directory.
dired-maybe-insert-subdir	i	Opens the content of the directory on the current line in the Dired buffer.

Summary

Dired has everything you need to navigate through your daily projects and a lot more. I just scratched the surface and recommend the official Emacs Dired manual for further information.

Handle Ruby Versions

tonini.samuel@gmail.com (Samuel Tonini) — Sat, 01 Oct 2011 00:00:00 CEST

RVM it's an extremly usefull tool if you have to work with Ruby, different Ruby projects and specific Ruby Gemsets for your projects. RVM offers the solution for these needs by creating environments bound to a specific Ruby version and a set of Ruby Gems. This possibility avoids Gem version conflicts between your projects and also makes it easy to create test environments.

Now what we want is to bring this into our beloved Emacs. And here comes rvm.el along, an Emacs package by Yves Senn. The rvm.el package integrates Emacs with RVM and gives us a few nifty functions.

One of the great advantages which rvm.el brings is that packages like inf-ruby and mode-compile automatically benefit from it and use the precise Ruby version.

Here's how to use it

First you have to install rvm.el; you get the source on Github.

Then you need to put the rvm.el somewhere in your load-path and add the following to your ~/.emacs file.

;; Load rvm.el
(require 'rvm)
;; use rvm’s default ruby for the current Emacs session
(rvm-use-default)

Done, now you're ready to use rvm.el.

The first function you want to know is rvm-activate-corresponding-ruby, this interactive function activates the corresponding Ruby version for the file in the current buffer. What the function does is, to search for an .rvmrc file and activate the selected Ruby version. If there is no .rvmrc file, the default ruby will be used instead.

Maybe you want to switch manually to a specific Ruby version, then you could use the rvm-use function, which is also as an interactive function available.

If you're working with Ruby on a daily basis and have to rummage through different Gem source code from time to time, then you will definitely need the interactive rvm-open-gem function. This function gives you a list of all the Gems which are installed for the currently activated Ruby version and shows them in the minibuffer. Now you just have to decide which one to open.

In addition to that, if you have Perspective installed, rvm-open-gem will open the chosen Gem directory in a new perspective, labeled with the Gem's name. Now it's easy to switch back and forth between your project and the Gem source.

More functions

rvm-autodetect-ruby will add a ruby-mode-hook which will call rvm-activate-corresponding-ruby to detect the Ruby version.

rvm-autodetect-ruby-stop is the vice-versa function, it will remove the ruby-mode-hook which calls the rvm-activate-corresponding-ruby function.

rvm-use-default uses the rvm default configured Ruby as the current Ruby version.

Some customization

You can use rvm.el in your own Emacs scripts easily. Here an example how rspec-mode uses it:

(defcustom rspec-use-rvm nil
  "t when RVM in is in use. (Requires rvm.el)"
  :type 'boolean
  :group 'rspec-mode)

And in the rspec-compile function it uses the rvm-activate-corresponding-ruby before it runs the specs.

The following example code is simplified.

(defun rspec-compile ()
  ;; some code.....
  (if rspec-use-rvm
      (rvm-activate-corresponding-ruby))
  ;; more code ..
  )

Summary

Rvm.el is a great package and if you're a Ruby programmer it will make your daily adventures with Ruby a lot more exciting.

The source code is available on the rvm.el repository on Github.

Workspaces

tonini.samuel@gmail.com (Samuel Tonini) — Sun, 25 Sep 2011 00:00:00 CEST

Perspective is an emacs package by Nathan Weizenbaum, which offers the possibility of working with different workspaces. If you are used to a windows manager (like Fluxbox, Gnome, KDE etc. for instance), you know the advantages of switching between several desktops or setting up different desktops for your purposes.

In my daily grind I switch often between projects, fixing a bug there or reading some source codes here. This possibility of working this way is extremely helpful. It's hard imagining not to be able to use it.

Perspective gives you tagged workspaces and because each perspective (workspace) is composed of a window configuration and a set of buffers, switching to a perspective will only make the buffers available which belong to it.

Here's how to use it

First you have to install perspective, you get the source on Github.

Then you need to put the perspective.el file somewhere in your load-path and add the following to your ~/.emacs file.

;; Load Perspective
(require 'perspective)
;; Toggle the perspective mode
(persp-mode)

From now on you are ready to go. Perspective is easy to use and you will be familiar with its functionality in no time.

What you will use mostly are persp-switch. With this function you switch to the perspective you want, if the specified perspective doesn't exist, it will create a new one and switch to it.

Sometimes you need to rename a perspective and for this action use the function persp-rename.

Another useful function is persp-add-buffer, just add a buffer to your chosen perspective. The vice-versa function of it is persp-remove-buffer.

More functions

pesp-kill just kill a not anymore used perspective.

persp-import import a perspective from another frame.

Some customization

Yves Senn, a friend of mine did a great job customizing perspective. He defined a macro which takes two arguments : the name for the perspective and the body which contains the code that will be evaluated after creating the perspective. So what you can do now is to define your custom function using the macro.

(defmacro custom-persp (name &rest body)
       `(let ((initialize (not (gethash ,name perspectives-hash)))
              (current-perspective persp-curr))
          (persp-switch ,name)
          (when initialize ,@body)
          (setq persp-last current-perspective)))

For instance, create a @org named perspective and open the first agenda file.

(defun custom-persp/org ()
  (interactive)
  (custom-persp "@org"
  (find-file (first org-agenda-files))))

At last, just create a key binding for the function.

(global-set-key (kbd "C-p o") 'custom-persp/org)

You find the whole source in the emacs-configs repository from Yves Senn.

Summary

Perspective is definitly a well written package

I recommend reading through the Perspective source and make yourself more familiar with whats going on beyond all these functions.

Do you remember?

tonini.samuel@gmail.com (Samuel Tonini) — Tue, 13 Sep 2011 00:00:00 CEST

Remember is a mode for Emacs, to simpy remember data. I'm a big fan of org-mode, but to create notes on the fly without having to switch to my org file, I prefer Remember. Since Emacs version 23.1 Remember is built in and it's doing a good job without any special configurations needed.

Here's how to use it

To jump in the note Remember buffer, simpy call the remember function. You will see an empty buffer if you are using it for the first time and there is no ~/.notes file. Below your current cursor position you will see the file path from which you called the remember function.

# The cursor will be positioned above the file path
/path/to/your/file.rb

Add your notes and after you're finished, just call the remember-finalize function, or use the default key-binding C-c C-c. By default the note will be stored in <your_home_directory>/.notes.

** Mon Sep 12 16:02:03 2011 (Refactor)

Refactor

I should refactor some code smell in this file...

/path/to/your/file.rb

Done. That's it! That's the easy way to use it without any magic and store your notes on the fly.

More functions

There are a few other functions which are also very useful.

remember-destroy just destroy the current Remember buffer you're in.

remember-region without opening the selected region in the Remember buffer - it saves the text directly into your notes file.

remember-clipboard writes your current clipboard contents to your notes file.

I would recommend that you just inspect the source of Remember on your own to get an overview of the full functionality.

Some customization

To change the file name in which you want to store your notes from .todos to .notes just overwrite the remember-data-file variable.

(defcustom remember-data-file (convert-standard-filename "~/.todos")
  "The file in which to store unprocessed data."
  :type 'file
  :group 'remember)

Or the leading text, which is used to begin each created note.

(defcustom remember-leader-text "** "
  "The text used to begin each remember item."
  :type 'string
  :group 'remember)

Further information

A lot of people use Remember with org-mode (org-remember documentation). But since version 6.36, org-mode has its own Remember-like feature implemented (see Capture), If you're using org-mode already, I would recommend to use that instead of Remember.

In a further article I will show you how to use Capture, instead of Remember and how org-mode serves you some cool features with Capture.