# Category Archives: org

## Tagging in Org – plus bonus code for timeclocks and tags!

The section on projects introduced tags as a way to differentiate
tags and how you can use them to filter your task list.

What’s a tag, anyway? In Org, tags are keywords at the end of
headlines. Each tag can contain letters, numbers, and the symbols ‘_’
and ‘@’. Tags begin and end with colons, and a single colon separates
multiple tags. For example, you could have headlines like this:

 * Personal                                     :PERSONAL:
** TODO Call Mom                               :@PHONE:
** TODO Send letters                           :@ERRANDS:
* Work                                         :WORK:
** TODO Call John about report                 :@PHONE:JOHN:
** TODO Prepare for presentation on Monday
** TODO Call Mary about the presentation       :@PHONE:URGENT:MARY:

One way to use tags is to filter your task list by priority. For
example, you may want to focus on your urgent tasks first without
getting distracted by other items on your task list. Another way to
use tags is to keep track of the context of your tasks as suggested in
GTD. By doing similar tasks together, you might be able to work more
efficiently. For example, if you’re on the phone at the office, it may
be a good idea to do all of your work-related phone calls. If you’re
going to go to the post office, you might want to drop by the
supermarket on your way back. You can use tags to categorize your

Tags can take advantage of the outline structure. For example,
although the tasks “Buy milk”, “Call Mom”, and “Send letters” have one
tag each, they also inherit the “PERSONAL” tag from the parent
headline. A tag search for “PERSONAL” would display all three
tasks. To customize this behavior, look at the documentation for the
variables org-use-tag-inheritance and org-tags-match-list-sublevels.

views. You’ll also learn about custom tag searches and other

You can edit your ~/organizer.org file and add tags manually by typing
in :tagname: at the end of the headline. You can also add tags by
typing C-c C-c (org-ctrl-c-ctrl-c) when the point is on a
headline. Use M-TAB (complete-symbol) to complete a tag based on all
the tags used in the current file. If Alt-TAB is not processed by
Emacs, you can use ESC-TAB instead.

Separate multiple tags with a single colon, like this:
(:@PHONE:URGENT:). The beginning and ending colons are optional when
using C-c C-c (org-ctrl-c-ctrl-c), because the function will

If you add certain tags frequently, you can set up single-key
shortcuts. For example, if you frequently tag tasks as “URGENT”, you
may want to define a shortcut (at least until your life gets under
control). You can assign shortcuts globally by adding this code to

   (setq org-tag-alist '(("URGENT" . ?u)
("@PHONE" . ?p)
("@ERRANDS" . ?e)))

You can also set this on a per-file basis by adding the following line
to the beginning of your file:

 #+TAGS: URGENT(u) @PHONE(p) @ERRANDS(e)

You can then use these C-c C-c (org-ctrl-c-ctrl-c) to enter these
single-key shortcuts, ending it with RET. If you are assigning a
single tag, type C-c C-c C-c (org-ctrl-c-ctrl-c, next change exits) to
make it even faster by skipping the RET.

If you use single-key shortcuts, you’ll need another way to enter tags
that start with the shortcut key. You can type them in manually, or
you can use C-c C-c (org-ctrl-c-ctrl-c) and type TAB to enter in any tag.

To remove a tag, you could use C-c C-c (org-ctrl-c-ctrl-c) again, or
delete it manually. To remove all tags, use C-c C-c
(org-ctrl-c-ctrl-c) and press SPC.

#### Viewing tagged items

Whether you want to view tagged headlines by themselves or in the
tagging features for you.

##### Agenda view

To view tagged headlines by themselves, use C-c a m (org-agenda,
org-tags-view) and specify the search tag. For example, you can view
not. For example, if you searched for “WORK”, you would just get the
“* Work” headline. To view tagged tasks, use C-c a M (org-agenda,
org-tags-view with a prefix argument). This shows only the tasks that
have that tag.

To search for a combination of tags, you can combine tags like this:

WORK&@PHONE           only your work phone calls
PERSONAL-@ERRANDS     personal tasks, but without errands
JOHN|MARY             Anything tagged with "JOHN" or "MARY"
For example, if you're going to have a meeting with both of them

If you check certain lists often, you might want to create a custom
agenda command for them. In the section on Projects, you configured
custom agenda commands for active and inactive projects by adding the

(setq org-agenda-custom-commands
'(("p" tags "PROJECT-MAYBE-DONE" nil)
("m" tags "PROJECT&MAYBE" nil)
("a" "My agenda"
((org-agenda-list)
(tags "PROJECT-MAYBE-DONE")))
;; ... put your other custom commands here
))

You can use the same idea to create quick custom views for your other
tagged tasks. For example, to create custom views for your urgent work
setting in your ~/.emacs to be like this:

(setq org-agenda-custom-commands
'(("u" todo "WORK&URGENT" nil)               ;; (1)
("c" todo "WORK&@PHONE" nil)               ;; (2)
("h" todo "PERSONAL-@ERRANDS" nil)         ;; (3)
("p" tags "PROJECT-MAYBE-DONE" nil)        ;; (4)
("m" tags "PROJECT&MAYBE" nil)
("a" "My agenda"
((org-agenda-list)
(tags-todo "URGENT")                     ;; (5)
(tags "PROJECT-MAYBE-DONE")))            ;; (6)
;; ... put your other custom commands here
))
• (1) “u” is for “urgent”, “todo” specifies that TODO headlines are to be shown, “WORK&URGENT” is the query string, and the last item means that there aren’t any options
• (2) “c” is for “call”
• (3) “h” is for “home”
• (4) The second item here is “tags” instead of “todo”, which means that the highest-level matching headlines should be shown whether or not they’re tasks.
• (5) This is how to add a tag search for tasks into a custom agenda command.
• (6) This is how to add a tag search for headlines into a custom agenda command.

Sometimes you’ll want to see more context instead of just a list of
headline by pressing RET (org-agenda-switch-to) on the entry. You can
also quickly browse through the headlines in another window by
pressing f (org-agenda-follow-mode) while in the Org agenda view, then
moving your point to the different lines. These commands work with the
summary in the Org agenda view.

file, you can use Org’s sparse tree search commands.

A sparse tree shows only the matching headlines in the context of the
that they’re easy to skip. To do a sparse tree search, type C-c \
(org-tags-sparse-tree). You can then expand and collapse subtrees with
the TAB (org-cycle) command. To limit the search to only task
headlines, type C-u C-c \ (org-tags-sparse-tree with a prefix).

#### Other cool things you can do with tags

And if you ever want to know how much time you spent on urgent tasks,
you can call the following function from your organizer.org file with:

M-x wicked/org-calculate-tag-time RET URGENT RET

to see something like this:

Time: 98:44 (98 hours and 44 minutes)

You can call it with a prefix in order to be prompted for a start time
(inclusive) and end time (exclusive).

(defun wicked/org-calculate-tag-time (matcher &optional ts te)
"Return the total minutes clocked in headlines matching MATCHER.
MATCHER is a string or a Lisp form to be evaluated, testing if a
given set of tags qualifies a headline for inclusion. TS and TE
are time start (inclusive) and time end (exclusive). Call with a
prefix to be prompted for TS and TE.

For example, to see how much time you spent on tasks tagged as
URGENT, call M-x wicked/org-calculate-tag-time RET URGENT RET. To
see how much time you spent on tasks tagged as URGENT today, call
C-u M-x wicked/org-calculate-tag-time RET URGENT RET . RET +1 RET."
(interactive (list
;; Convert strings to proper arguments
(if (stringp matcher) (setq matcher (cdr (org-make-tags-matcher matcher))))
(if (stringp ts)
(setq ts (time-to-seconds (apply 'encode-time (org-parse-time-string ts)))))
(if (stringp te)
(setq te (time-to-seconds (apply 'encode-time (org-parse-time-string te)))))
(let* ((re (concat "[\n\r]" outline-regexp " *\$$\\<\\(" (mapconcat 'regexp-quote org-todo-keywords-1 "\\|") (org-re "\\>\$$\\)? *\$$.*?\$$\$$:[[:alnum:]_@:]+:\$$?[ \t]*$"))) (case-fold-search nil) lspos tags tags-list tags-alist (llast 0) rtn level category i txt p marker entry priority (total 0)) (save-excursion (org-clock-sum ts te) (goto-char (point-min)) (while (re-search-forward re nil t) (catch :skip (setq tags (if (match-end 4) (match-string 4))) (goto-char (setq lspos (1+ (match-beginning 0)))) (setq level (org-reduced-level (funcall outline-level)) category (org-get-category)) (setq i llast llast level) ;; remove tag lists from same and sublevels (while (>= i level) (when (setq entry (assoc i tags-alist)) (setq tags-alist (delete entry tags-alist))) (setq i (1- i))) ;; add the nex tags (when tags (setq tags (mapcar 'downcase (org-split-string tags ":")) tags-alist (cons (cons level tags) tags-alist))) ;; compile tags for current headline (setq tags-list (if org-use-tag-inheritance (apply 'append (mapcar 'cdr tags-alist)) tags)) (when (and (eval matcher) (or (not org-agenda-skip-archived-trees) (not (member org-archive-tag tags-list)))) ;; Get the time for the headline at point (goto-char (line-beginning-position)) (setq total (+ total (or (get-text-property (1+ (point)) :org-clock-minutes) 0))) ;; if we are to skip sublevels, jump to end of subtree (org-end-of-subtree t))))) (if (interactive-p) (let* ((h (/ total 60)) (m (- total (* 60 h)))) (message "Time: %d:%02d (%d hours and %d minutes)" h m h m))) total)) Now you can slice and dice your timeclock records any way you want, thanks to tags! Random Emacs symbol: cc-imenu-java-generic-expression – Variable: Imenu generic expression for Java mode. See imenu-generic-expression’. On Technorati: , , ## Writing plans for the chapter on managing notes - [ ] Keeping Notes in Emacs Structured vs Unstructured (outline, free-form) Flat vs Hyperlinked Private vs Public File structure (one file, daily, snippets) In this section, you’ll learn about the different kinds of notes you take, and you will be able to choose one or two Emacs modules to start learning. - [ ] Capture and retrieve – Remember, search Getting the ideas out of your head and into your note-taking system; searching your notes (basic), searching your notes (specific) Wicked cool code: Remembering to different note-taking systems, searching different note-taking systems - [ ] Outline Notes with Org, Blorg In this section, you’ll learn how to keep outlined notes using Org.Â You’ll be able to create headings, sub-headings, and text notes. You’ll also learn how to manage outline items by promoting, demoting, and rearranging them. These basic editing commands are covered in the Emacs Org manual, so I’ll just give a brief summary.. You’ll also get tips on how to capture text quickly (M-x remember, dabbrev), work with large outline files (split windows are useful), and search your notes efficiently (searching headings or text). Lastly, you’ll learn how to publish your Org file as HTML or LaTeX. Wicked cool code would be: searching, how to import to and export from Freemind, a graphical mind-mapping program. - [ ] Daily Notes with Planner In this section, you’ll learn how to write a day-based journal using Planner. In addition to free-form notes on the page, you’ll also be able to keep semi-structured notes typed in manually or captured using Remember. You’ll also learn how to publish the resulting pages as HTML and RSS, and how to customize the output. Wicked cool code would be: searching notes and displaying matching headlines, private notes, publishing note headlines, and publishing a note index. - [ ] Hyperlinked Notes with Muse In this section, you’ll learn how to create a personal wiki using Muse.Â You’ll learn how to create pages, link to pages, and publish your wiki. Wicked cool code: Capturing notes to specific pages using Remember and keyword matches, private pages, publishing pages when you save them. - [ ] Snippets with Howm In this section, you’ll learn how to manage random snippets of information using Howm. - [ ] Blogging from Emacs – WordPress, LJ, Blogger,Muse-Blosxom, EmacsAtomAPI In this section, you’ll learn how to use Emacs as a blogging client for many popular platforms. This is mainly for keeping other blogs in sync, although I’ll also talk about the possibility of using planner-rss + something like Feedwordpress. - [ ] Encrypted Notes (full file, segments) – MOSTLY WRITTEN In this section, you’ll learn how to encrypt your notes. Actually, this will probably be split up into the different tools… ## Capturing Notes with Remember Ideas come from everywhere. While reading this blog, you might come across interesting snippets that you’d like to save. While writing code, you might be hit by an idea for something you want to do with the program. While on a phone call, you might need to write down what you need to prepare for a meeting the next day. How do you take notes now? Do you jot your notes on a scrap of paper or into a leather notebook? Do you copy and paste what you’re looking at into a plain text file or document? Do you scribble things into a personal digital assistant? I’ve tried different note-taking strategies: colorful mindmaps, outlined text files, even voice recordings. I felt frustrated every time I had to write down whose e-mail or which webpage prompted the note (shouldn’t the computer do that automatically?), but I was even more frustrated when I’d come across a note and not remember why I wrote it. Remember changed all that for me. The key ideas behind Remember are that you should be able to write notes with minimal distraction, and that as the context should be automatically picked up so that you don’t have to write it down. If you’re writing a note based on a mail message, Remember will pick up the details of the message and create a hyperlink so that you can view the original message when reviewing your notes. If you’re working on a file, Remember will link to it so that you can jump back to it. If you’re browsing a web page (in Emacs, of course), Remember will remember the title and URL, so that you can go back to the page when you want to clarify something in your notes. After you save the note, you’ll be back in the same environment you were: no need to switch applications and no need to remember different keyboard shortcuts. You might think that Remember’s only worth it if you do _everything_ in Emacs. For me, it worked the other way around. I started by using Remember to take notes in Planner, a personal information manager available for Emacs. As I got accustomed to the way Remember and Planner just automatically hyperlinked to whatever I was looking at, I thought: Why doesn’t my mail client do this? Why doesn’t my web browser do this? Why doesn’t my chat client do this? So I ended up reading through the manuals, figuring out how to do all these things in Emacsâ€”and I loved it, eventually doing most of my work (and play!) within an Emacs frame. Although I use other applications now, like Lotus Notes for work mail and Mozilla Firefox for browsing, I still switch back to Emacs for my notes. In this section, you’ll learn how to set up Remember and take quick notes in Emacs. We’ll start by configuring Remember to save your notes to a file, and how to configure Remember to save to different places depending on the content. You’ll also learn how to quickly search your notes file for entries. You can also integrate Remember into other note-taking systems in Emacs. The sections that cover those systems will also show you how to configure Remember to save your notes there. #### Setting Up Remember Remember is a separate package, which you can download from https://gna.org/projects/remember-el . As of this writing, the latest stable release is Remember 1.9. Download the latest version and unpack it into your ~/elisp directory. You should end up with a new directory, ~/elisp/remember-1.9 . To configure Remember to save to plain text files, add this code to your ~/.emacs and evaluate it: (add-to-list 'load-path "~/elisp/remember-1.9") ;; (1) (require 'remember-autoloads) (setq remember-data-file "~/notes.txt") ;; (2) (global-set-key (kbd "C-c r") 'remember) ;; (3) (defun wicked/remember-review-file () "Open remember-data-file'." (interactive) (find-file-other-window remember-data-file)) (global-set-key (kbd "C-c R") 'wicked/remember-review-file) ;; (4) ;; Not (global-set-key (kbd "C-c r")... as originally written... Thanks for catching that, Seth! • 1: Change this to the directory that contains remember.el • 2: Notes will be saved to this file. You can change this if you want; just keep in mind that this section refers to ~/notes.txt. • 3: C-c r (remember) is a handy shortcut key for remember. You can also bind it to other shortcut keys such as F9 r. • 4: This shortcut makes it easy to check your remembered notes. After you’ve configured Remember, try it out by typing C-c r (remember). Your Emacs frame will be split in two, and one of the windows will be a *Remember* buffer. Type your note. The first line will be the headline, and the rest of the buffer will be the body of the note. If you call C-c r (remember) from a file, the filename will automatically be included at the end of the buffer. Type C-c C-c (remember-buffer) to save the note. Try it now by typing C-c r (remember) to bring up the buffer, typing in a short note, and using C-c c (remember-buffer) to save it. If you open ~/notes.txt to review your note, you’ll find something like this:  ** Sat Jan 12 14:43:02 2008 (Your headline goes here) Your note body goes here /home/sacha/.emacs You can even save yourself some copying and pasting. Mark a region of text and use C-u C-c r (remember). The selected text will be included in the buffer, so all you have to do is comment on it. Make a habit of typing C-c C-r or C-u C-c C-r (remember) when you need to remember something. Type C-c C-c (remember-buffer) to get back to work, knowing that your notes have been safely saved in your ~/notes.txt file. #### Reviewing Your Notes Use C-c R (wicked/remember-review-file) to check your notes, or open ~/notes.txt yourself. To search your notes, use C-c R (wicked/remember-review-file) to open the file, then use C-s (isearch-forward) to search for words interactively, or use M-x occur to find all lines containing a word. You may notice that the default format that Remember uses is an outline format that is compatible with Org and Allout, both of which have powerful outline-editing tools. I prefer Org’s outline-editing commands, and you’ll learn about them in the “Outline Notes with Org” section. Here’s a quick summary. First, you need to switch the buffer to Org mode by typing M-x org-mode. To automatically open your notes file in Org mode, add -*- mode: org -*- to the first line of your ~/notes.txt. Then, when you open your ~/notes.txt file, it will be in Org mode. You can quickly collapse or expand all the outline entries by pressing S-TAB (org-shifttab). To collapse or expand a single entry, move the point to the headline (the line beginning with *, **, or any number of asterisks), then press TAB (org-cycle). To move an entry up or down, move the point to the headline and press S-UP (org-shiftup) or S-DOWN (org-shiftdown). To demote or promote a heading, press M-RIGHT (org-metaright) or M-LEFT (org-metaleft). You can treat ~/notes.txt as your inbox, and keep your organized notes in another file or groups of files. Cut and paste the text between the files to clear your inbox, and use M-x grep to search multiple files. Alternatively, you can keep all of your notes in one large text file, and use C-s (isearch-forward) and M-x occur to search for information. Now you know the basics of remembering information, saving it into a file, and reviewing the file. By default, Remember annotates your notes with a filename, if you were looking at a file when you called C-c r (remember). As you learn more about Emacs, you may want to configure Remember to add more intelligent annotations and other text to the Remember buffer. The more work Remember does for you, the less work you have to do! #### Enabling annotation functions The easiest way to get Remember to automatically understand mail messages, Web pages, info files, BBDB contact records, and other sources of information in Emacs is to use either Org or Planner. To learn how to integrate Remember with either Org or Planner, read the section on “Outline Your Notes with Org” and “Writing Your Journal with Planner”. You can also define your own annotation functions. When you call C-c r (remember) from a buffer, Remember goes through each of the functions in remember-annotation-functions, and it uses the first non-nil value returned. For example, you may work with many temporary buffers that don’t have filenames. To create an annotation function that adds buffer names, add the following code to your ~/.emacs after the basic Remember configuration code: (eval-after-load 'remember '(progn (add-to-list 'remember-annotation-functions 'buffer-name t))) This adds buffer-name to the end of the annotation list, making it a last resort. What if you want line numbers included with the filename or buffer name? You could replace the previous code with this: (defun wicked/remember-line-numbers-and-file-names () "Return FILENAME line NUMBER." (save-restriction (widen) (format " %s line %d" (or (buffer-file-name) (buffer-name)) (line-number-at-pos)))) (eval-after-load 'remember '(progn (add-to-list 'remember-annotation-functions 'wicked/remember-line-numbers-and-file-names))) With that code, C-c r (remember) will automatically pick up the line number from your file or buffer. By default, Remember saves your notes to a plain-text file, so you’ll have to open the files manually. The command M-x ffap or find-find-file-at-point may be convenient. If you want hyperlinks that you can visit easily, consider saving your notes in an Org or Planner file instead. Now you’ve got context. What else can you do with the Remember buffer? #### Adding Other Text to the Remember Buffer Remember has plenty of hooks that let you modify the behavior. For example, you might want to insert a random tagline or fortune-cookie saying whenever you create a note. This is a fun way to encourage yourself to write more, because then there’s a little surprise every time you open a Remember buffer. Here is a totally small-scale way to use random lines from a text file. Let’s say that you have a text file made up of movie quotes, taglines, knock-knock jokes, or short fortune-cookie sayings. When I wrote this code, I used Japanese/English sentence pairs about cats, because I was studying Japanese. You can use whatever tickles your fancy, as long as this text file (~/taglines.txt) has one line per saying. (defun wicked/random-tagline (&optional file) "Return a random tagline." (with-current-buffer (find-file-noselect (or file "~/taglines.txt")) (goto-char (random (point-max))) (let ((string (buffer-substring (line-beginning-position) (line-end-position)))) string))) (eval-after-load 'remember '(progn (defadvice remember (after wicked activate) "Add random tagline." (save-excursion (goto-char (point-max)) (insert "\n\n" (wicked/random-tagline) "\n\n"))))) If you want multi-line sayings, look into the Emacs fortune cookie package, and replace wicked/random-tagline with a function that returns a random string. This code modifies the behavior of C-c r (remember) by inserting a random tagline after the buffer has been prepared. You can use the same idea to insert a timestamp noting the time you started, use a template, or modify the text in other ways. #### Saving to Different Places You can also change how Remember saves its notes. For example, if you want all of the notes that contain the word “:EMACS:” or “:WORK:” to go into separate files, you can add this code to your ~/.emacs: (defvar wicked/remember-keywords '((":EMACS:" . "~/emacs.txt") (":WORK:" . "~/work.txt")) "*List of (REGEXP . FILENAME). If an entry matches REGEXP, it will be storied in FILENAME. The first regular expression that matches is used.") (eval-after-load 'remember '(progn (defadvice remember-region (around wicked activate) "Save notes matching wicked/remember-keywords' elsewhere." (let* ((b (or beg (min (point) (or (mark) (point-min))))) (e (or end (max (point) (or (mark) (point-max))))) (string (buffer-substring-no-properties b e)) (done nil) (keywords wicked/remember-keywords)) (while keywords (when (string-match (caar keywords) string) (let ((remember-data-file (cdar keywords))) ad-do-it) (setq keywords nil done t)) (setq keywords (cdr keywords))) (unless done ad-do-it))))) You can even configure Remember to use different handler functions. This chapter covers several note-taking systems for Emacs, and you may want to use Remember to save to more than one note-taking system. For example, you can set up C-c r p to start a Remember buffer that saves to Planner, and C-c r o to start a Remember buffer that saves to Org. Here’s the code for your ~/.emacs: (defun wicked/remember-to-org () "Remember to Org." (let ((remember-annotation-functions ;; (1) (cons 'org-remember-annotation remember-annotation-functions))) (remember) (set (make-variable-buffer-local 'remember-handler-functions) '(org-remember-handler)))) ;; (2) (defun wicked/remember-to-planner () "Remember to Planner." (let ((remember-annotation-functions ;; (3) (append planner-annotation-functions remember-annotation-functions))) (remember) (set (make-variable-buffer-local 'remember-handler-functions) '(remember-planner-append)))) ;; (4) (global-unset-key (kbd "C-c r")) ;; (5) (global-set-key (kbd "C-c r o") 'wicked/remember-to-org) (global-set-key (kbd "C-c r p") 'wicked/remember-to-planner) • 1: We need to make sure that Org-compatible links are created. • 2: This makes C-c C-c save the note to the Org file. • 3: Planner uses a list of annotation functions, so we add all of them to the beginning of the list. • 4: This makes C-c C-c save the note to the Planner page. • 5: We need to unset keyboard shortcuts before we can set longer keyboard shortcuts that start with the same sequence. To learn more about configuring Remember with the different note-taking systems, read the sections for those systems. On Technorati: , , , Random Emacs symbol: compilation-find-file – Function: Find a buffer for file FILENAME. ## Outlining Your Notes with Org Large documents are almost impossible to write without outlines. There’s just too much to fit in your head. Outlines help you work with a structure, so that you can see the big picture and how sections fit together. Outlines are also surprisingly useful when brainstorming. You can work with varying levels of detail, starting with a high-level overview and successively refining it, or starting with the details and then letting the structure emerge as you organize those details into groups. Emacs has one of the most powerful outline editors I’ve come across. Although word processors like Microsoft Word and OpenOffice.org Writer support outlines too, Emacs has a gazillion keyboard shortcuts, and once you get the hang of them, you’ll want them in other applications as well. In addition, working in Emacs tends to force you to focus on the content instead of spending time fiddling with the formatting. Whether you’re writing personal notes or working on a document that’s due tomorrow, this is a good thing. In this section, you’ll learn how to outline a document using Org. You’ll be able to create headings, sub-headings, and text notes. You’ll also learn how to manage outline items by promoting, demoting, and rearranging them. ### Understanding Org Org is primarily a personal information manager that keeps track of your tasks and schedule, and you’ll learn more about those features in chapters 8 and 9. However, Org also has powerful outline-management tools, which is why I recommend it to people who want to write and organize outlined notes. The structure of an Org file is simple: a plain text file with headlines, text, and some additional information such as tags and timestamps. A headline is any line that stars with a series of asterisks. The more asterisks there are, the deeper the headline is. A second-level headline is the child of the first-level headline before it, and so on. For example: * This is a first-level headline Some text under that headline ** This is a second-level headline Some more text here *** This is a third-level headline *** This is another third-level headline ** This is a second-level headline Because Org uses plain text, it’s easy to back up or process using scripts. Org’s sophistication comes from keyboard shortcuts that allow you to quickly manipulate headlines, hide and show outline subtrees, and search for information. GNU Emacs 22 includes Org. To automatically enable Org mode for all files with the .org extension, add the following to your ~/.emacs: (require 'org) (add-to-list 'auto-mode-alist '("\\.org$" . org-mode))

To change to org-mode manually, use M-x org-mode while viewing a file. To enable Org on a per-file basis, add

-*- mode: org -*- 

to the first line of the files that you would like to associate with Org.

### Working with Outlines

You can keep your notes in more than one Org file, but let’s start by creating ~/notes.org. Open ~/notes.org, which will automatically be associated with Org Mode. Type in the general structure of your document. You can type in something like this:

 * Introduction
* ...

You can also use M-RET (org-meta-return) to create a new headline at the same level as the one above it, or a first-level headline if the document doesn’t have headlines yet.

Create different sections for your work. For example, a thesis might be divided into introduction, review of related literature, description of study, methodology, results and analysis, and conclusions and recommendations. You can type in the starting asterisks yourself, or you can use M-RET (org-meta-return) to create headings one after the other.

Now that you have the basic structure, start refining it. Go to the first section and use a command like C-o (open-line) to create blank space. Add another headline, but this time, make it a second-level headline under the first. You can do that by either typing in two asterisks or by using M-RET (org-meta-return, which calls org-insert-heading) and then M-right (org-metaright, which calls org-do-demote). Then use M-RET (org-meta-return; org-insert-heading) for the other items, or type them in yourself. Repeat this for other sections, and go into as much detail as you want.

What if you want to reorganize your outline? For example, what if you realized you’d accidentally put your conclusions before the introduction? You could either cut and paste it using Emacs shortcuts, or you can use Org’s outline management functions. The following keyboard shortcuts are handy:

 Action Command Shortcut Alternative Move a subtree up org-metaup / org-move-subtree-up M-up C-c C-x u Move a subtree down org-metadown / org-move-subtree-down M-down C-c C-x d Demote a subtree org-shiftmetaright / org-demote-subtree S-M-right C-c C-x r Promote a subtree org-shiftmetaleft / org-promote-subtree S-M-left C-c C-x l Demote a headline org-metaright / org-do-demote M-right C-c C-x Promote a headline org-metaleft / org-do-promote M-left C-c C-x Collapse or expand a subtree org-cycle (while on headline) TAB Collapse or expand everything org-shifttab (org-cycle) S-TAB C-u TAB

Use these commands to help you reorganize your outline as you create a skeleton for your document. These commands make it easy to change your mind about the content or order of sections. You might find it easier to sketch a rough outline first, then gradually fill in more and more detail. On the other hand, you might find it easier to pick one section and keep drilling it down until you have headlines some seven levels deep. When you reach that point, all you need to do is add punctuation and words like "and" or "but" between every other outline item, and you’re done!

Well, no, not likely. You’ll probably get stuck somewhere, so here are some tips for keeping yourself going when you’re working on a large document in Org: brainstorming and getting a sense of your progress.

### Brainstorming

Brainstorming is a great way to break your writer’s block or to generate lots of possibilities. The key idea is to come up with as many ideas as you can, and write them all down before you start evaluating them.

I usually switch to paper for mindmapping and brainstorming because paper helps me think in a more colorful and non-linear way. However, it can be hard to manage large mindmaps on paper, because you can’t reorganize nodes easily. Despite its text-heavy interface, Org is one of the best mindmapping tools I’ve come across. Because it’s built into Emacs, everything can be done through keyboard shortcuts.

When you’re brainstorming, you might like working from two different directions. Sometimes it’s easier to start with an outline and to add more and more detail. Other times, you may want to jot quick ideas and then organize them into groups that make sense. Org provides support for both ways of working.

Brainstorming bottom-up is similar to David Allen’s Getting Things Done method in that separating collection from organization is a good idea. That is, get the ideas out of your head first before you spend time trying to figure out the best way to organize them. To get things out of your head quickly, collect your ideas by using the M-RET (org-meta-return) to create a new heading, typing in your idea, and using M-RET (org-meta-return) to create the next heading. Do this as many times as needed.

One way to encourage yourself to brainstorm lots of ideas is to give yourself a quota. Charles Cave described this technique in an article on org-mode, and it’s a great way to use structure to prompt creativity. Simply start by adding a number of empty headings (say, 20), then work towards filling that quota. For example, you might start with ten blanks for ideas, then gradually fill them in like this:

* Things that make me happy
** Curling up with a good book
** Watching a brilliant sunset
** Giving or getting a big warm hug
** Writing a cool piece of Emacs code
**
**
**
**
**
**

When all of your ideas are in Org, start organizing them. This is where you move ideas around using M-S-up (org-shiftmetaup) and M-S-down (org-shift-metadown), which call org-move-subtree-up and org-move-subtree-down. This is also a good time to use headings to group things together.

### Getting a Sense of Progress

You’ve brainstormed. You’ve started writing your notes. And if you’re working on a large document, you might lose steam at some point along the way. For example, while working on this book, I often find myself intimidated by just how much there is to write about Emacs. It helps to have a sense of progress such as the number of words written or the number of sections completed. To see a word count that updates every second, add this code to your ~/.emacs:

(defvar count-words-buffer
nil
"*Number of words in the buffer.")

(defun wicked/update-wc ()
(interactive)
(setq count-words-buffer (number-to-string (count-words-buffer)))
(force-mode-line-update))

; only setup timer once
(unless count-words-buffer
;; seed count-words-paragraph
;; create timer to keep count-words-paragraph updated
(run-with-idle-timer 1 t 'wicked/update-wc))

;; add count words paragraph the mode line
(unless (memq 'count-words-buffer global-mode-string)

;; count number of words in current paragraph
(defun count-words-buffer ()
"Count the number of words in the current paragraph."
(interactive)
(save-excursion
(goto-char (point-min))
(let ((count 0))
(while (not (eobp))
(forward-word 1)
(setq count (1+ count)))
count)))

The best way I’ve found to track my progress in terms of sections is to use a checklist. For example, the collapsed view for this section looks like this:

** Outline Notes with Org [7/9]    ;; (1)
*** [X] Outlining Your Notes...    ;; (2)
*** [X] Understanding Org...
*** [X] Working with Outlines...
*** [X] Brainstorming...
*** [ ] Getting a Sense of Progress... ;; (3)
*** [ ] Integrating Remember with Org

• (1): [7/9] shows that I’ve completed 7 of 9 parts.
• (2): [X] indicates finished parts.
• (3): [ ] indicates parts I still need to do.

This is based on the checklist feature in Org. However, the standard feature works only with lists like this:

*** Items [1/3]
- [X] Item 1
- [ ] Item 2
- [ ] Item 3

(defun wicked/org-update-checkbox-count (&optional all)
"Update the checkbox statistics in the current section.
This will find all statistic cookies like [57%] and [6/12] and update
them with the current numbers.  With optional prefix argument ALL,
do this for the whole buffer."
(interactive "P")
(save-excursion
(let* ((buffer-invisibility-spec (org-inhibit-invisibility))
(beg (condition-case nil
(error (point-min))))
(end (move-marker
(make-marker)
(progn (or (outline-get-next-sibling) ;; (1)
(goto-char (point-max)))
(point))))
(re "\$$\$[0-9]*%\$\$$\\|\$$\$[0-9]*/[0-9]*\$\$$")
(re-box
"^[ \t]*\$$*+\\|[-+*]\\|[0-9]+[.)]\$$ +\$$\$[- X]\$\$$")
b1 e1 f1 c-on c-off lim (cstat 0))
(when all
(goto-char (point-min))
(or (outline-get-next-sibling) (goto-char (point-max))) ;; (2)
(setq beg (point) end (point-max)))
(goto-char beg)
(while (re-search-forward re end t)
(setq cstat (1+ cstat)
b1 (match-beginning 0)
e1 (match-end 0)
f1 (match-beginning 1)
lim (cond
(or (outline-get-next-sibling) ;; (3)
(goto-char (point-max)))
(point))
((org-at-item-p) (org-end-of-item) (point))
(t nil))
c-on 0 c-off 0)
(goto-char e1)
(when lim
(while (re-search-forward re-box lim t)
(if (member (match-string 2) '("[ ]" "[-]"))
(setq c-off (1+ c-off))
(setq c-on (1+ c-on))))
(goto-char b1)
(insert (if f1
(format "[%d%%]" (/ (* 100 c-on)
(max 1 (+ c-on c-off))))
(format "[%d/%d]" c-on (+ c-on c-off))))
(and (looking-at "\$.*?\$")
(replace-match ""))))
(when (interactive-p)
(message "Checkbox statistics updated %s (%d places)"
(if all "in entire file" "in current outline entry")
cstat)))))
"Fix the built-in checkbox count to understand headlines."
(wicked/org-update-checkbox-count (ad-get-arg 1))))

Now add [ ] or [X] to the lower-level headlines you want to track. Add [/] to the end of the higher-level headline containing those headlines. Type C-c # (org-update-checkbox-count) to update the count for the current headline, or C-u C-c C-# (org-update-checkbox-count) to update all checkbox counts in the whole buffer.

If you want to see the percentage of completed items, use [%] instead of [/]. I find 7/9 to be easier to understand than 71%, but fractions might work better for other cases.

Okay, you’ve written a lot. How do you find information again?

When you’re writing your notes, you might need to refer to something you’ve written. You may find it helpful to split your screen in two with C-x 3 (split-window-horizontally) or C-x 2 (split-window-vertically). To switch to another window, type C-x o (other-window) or click on the window. To return to just one window, use C-x 1 (delete-other-windows) to focus on just the current window, or C-x 0 (delete-window) to get rid of the current window.

Now that you’ve split your screen, how do you quickly search through your notes? C-s (isearch-forward) and C-r (isearch-backward) are two of the most useful Emacs keyboard shortcuts you’ll ever learn. Use them to not only interactively search your Org file, but also to quickly jump to sections. For example, I often search for headlines by typing * and the first word. Org searches collapsed sections, so you don’t need to open everything before searching.

To search using Org’s outline structure, use C-c / r (org-sparse-tree, regexp), which will show only entries matching a regular expression. For more information about regular expressions, read the Emacs info manual entry on Regexps. Here are a few examples:

 To find Search for All entries containing "cat" cat All entries that contain "cat" as a word by itself (example: "cat," but not "catch") \ All entries that contain 2006, 2007, or 2008 200[678]

If you find yourself frequently searching for some sections, you might want to create hyperlinks to them. For example, if you’re using one file for all of your project notes instead of splitting it up into one file per project, then you probably want a list of projects at the beginning of the file so that you can jump to each project quickly.

You can also use hyperlinks to keep track of your current working position. For example, if you’re working on a long document and you want to keep your place, create a link anchor like <<TODO>> at the point where you’re editing, and add a link like [[TODO]] at the beginning of your file.

You can create a hyperlink to a text search by putting the keywords between two pairs of square brackets, like this:

  See [[things that make me happy]] 

You can open the link by moving the point to the link and typing C-c C-o (org-open-at-point). You can also click on the link to open it. Org will then search for text matching the query. If Org doesn’t find an exact match, it tries to match similar text, such as "Things that make me really really happy".

If you find that the link does not go where you want it to go, you can limit the text search. For example, if you want to link to a headline and you know the headline will be unique, you can add an asterisk at the beginning of the link text in order to limit the search to headlines. For example, given the following text:

In this file, I'll write notes on the things that make me happy. (1)
If I ever need a spot of cheering up, I'll know just what to do!

** Things that make me happy (2)
*** ...

Example
Link 1: [[things that make me happy]]

Link 2: [[*things that make me happy]] 

To define a link anchor, put the text in double angled brackets like this:

<<things that make me happy>> 

A link like [[things that make me happy]] would then link to that instead of other occurances of the text.

You can define keywords that will be automatically hyperlinked throughout the file by using radio targets. For example, if you’re writing a jargon-filled document and you frequently need to refer to the definitions, it may help to make a glossary of terms such as "regexp" and "radio target", and then define them in a glossary section at the end of the file, like this:

*** glossary
<<<radio target>>> A word or phrase that is automatically hyperlinked whenever it appears.
<<<regexp>>> A regular expression. See the Emacs info manual. 

Radio targets are automatically enabled when an Org file is opened in Emacs. If you’ve just added a radio target, enable it by moving the point to the anchor and pressing C-c C-c (org-ctrl-c-ctrl-c). This turns all instances of the text into hyperlinks that point to the radio target.

You can keep your notes as a plain text file, or you can publish them as HTML or LaTeX. HTML seems to be the easiest way to let non-Emacs users read your notes, as a large text file without pretty colors can be hard to read.

To export a file to any of the formats that Org understands by default, type C-c C-e (org-export). You can then type ‘h’ (org-export-as-html) to export it as HTML for websites. You can also type ‘l’ (org-export-as-latex) to export it to LaTeX, a scientific typesetting language, which can then be published as PDF or PS. Another way to convert it to PDF is to export it as HTML, open it in OpenOffice.org Writer, and use the Export to PDF feature. You can also open HTML documents in other popular word processors to convert them to other supported formats.

By default, Org exports all the content in the current file. To limit it only to the visible content, use C-c C-e v (org-export-visible) followed by either ‘h’ for HTML or ‘l’ for LaTeX.

If you share your notes, you may want to export an HTML version every time you save an Org file. Here is a quick and dirty way to publish all Org files to HTML every time you save them:

(defun wicked/org-publish-files-maybe ()
"Publish this file."
(org-export-as-html-batch)
nil)
(lambda ()
'wicked/org-publish-files-maybe)))

(Update: Feb 22 2011: Thanks to Neilen for the fix!)

• (1) Every time a buffer is set to Org mode…
• (2) Add a function that publishes the file every time that file is saved.

What if most of your files are private, but you want to publish only a few of them? To control this, let’s add a new special keyword "#+PUBLISH" to the beginning of the files that you want to be automatically published. Replace the previous code in your ~/.emacs with this:

(defun wicked/org-publish-files-maybe ()
"Publish this file if it contains the #+PUBLISH: keyword"
(save-excursion
(save-restriction
(widen)
(goto-char (point-min))
(when (re-search-forward
"^#?[ \t]*\\+\$$PUBLISH\$$"
nil t)
(org-export-as-html-batch)
nil))))

(lambda ()
'wicked/org-publish-files-maybe)))

and add #+PUBLISH on a line by itself to your ~/notes.org file, like this:

 #+PUBLISH
* Things that make me happy

When you save any Org file that contains the keyword, the corresponding HTML page will also be created. You can then use a program like rsync or scp to copy the file to a webserver, or you can copy it to a shared directory.

### Integrating Remember with Org

You can use Remember to collect notes that you will later integrate into your outline. Add the following code to your ~/.emacs to set it up:

(global-set-key (kbd "C-c r") 'remember)    ;; (1)
(setq org-remember-templates
'((?n "* %U %?\n\n  %i\n  %a" "~/notes.org")))  ;; (3)
(setq remember-annotation-functions '(org-remember-annotation)) ;; (4)
(setq remember-handler-functions '(org-remember-handler)) ;; (5)
• 1: Handy keyboard shortcut for (r)emember
• 2: Creates a template for (n)otes
• 3: Create a note template which saves the note to ~/notes.org, or whichever Org file you want to use
• 4: Creates org-compatible context links
• 5: Saves remembered notes to an Org file

With this code, you can type C-c r n (remember, Notes template) to pop up a buffer (usually containing a link to whatever you were looking at), write your note, and type C-c C-c (remember-buffer) to save the note and close the buffer.

You can use this to store snippets in your notes file, or to quickly capture an idea that comes up when you’re doing something else.

Now you know how to sketch an outline, reorganize it, fill it in, brainstorm, stay motivated, and publish your notes. I look forward to reading what you have to share!

## Emacs: Smarter interactive prompts with Org remember templates

Paul Lussier wanted to know how to interactively prompt for a value and use that value multiple times in org-remember-templates. His example is:

(setq org-link-abbrev-alist
'(("RT" . "https://rt/Ticket/Display.html?id=")))

(setq org-remember-templates
'(("Tasks" ?t "* TODO %?\n  %i\n  %a"            "~/organizer.org")
("Appts" ?a "* Appointment: %?\n%^T\n%i\n  %a" "~/organizer.org")
("RT"    ?R "* [[RT:%^{Number}][%^{Number}/%^{Description}]]" "~/org/rt.org")))


The version of Org on my system prompts for Number twice. We want to store the value in an associative list somewhere so that if Org encounters another prompt with the same text, it’ll use the stored value. Here’s a diff that’ll do the trick.

diff -u /home/sachac/elisp/org/org.el /tmp/buffer-content-4571Oz1
--- /home/sachac/elisp/org/org.el	2008-07-20 11:28:54.000000000 -0400
+++ /tmp/buffer-content-4571Oz1	2008-07-20 11:42:06.000000000 -0400
@@ -12822,38 +12822,52 @@
;; Interactive template entries
(goto-char (point-min))
-	(while (re-search-forward "%^\$${\\([^}]*\$$}\\)?\$$[guUtT]\$$?" nil t)
-	  (setq char (if (match-end 3) (match-string 3))
-		prompt (if (match-end 2) (match-string 2)))
-	  (goto-char (match-beginning 0))
-	  (replace-match "")
-	  (cond
-	   ((member char '("G" "g"))
-	    (let* ((org-last-tags-completion-table
-		    (org-global-tags-completion-table
-		     (if (equal char "G") (org-agenda-files) (and file (list file)))))
-			 (if prompt (concat prompt ": ") "Tags: ")
-			 'org-tags-completion-function nil nil nil
-			 'org-tags-history)))
-	      (setq ins (mapconcat 'identity
-				  (org-split-string ins (org-re "[^[:alnum:]]+"))
-				  ":"))
-	      (when (string-match "\\S-" ins)
+	(let (interactive-entries lookup)
+	  (while (re-search-forward "%^\$${\\([^}]*\$$}\\)?\$$[guUtT]\$$?" nil t)
+	    (setq char (if (match-end 3) (match-string 3))
+		  prompt (if (match-end 2) (match-string 2))
+		  lookup (assoc prompt interactive-entries))
+	    (goto-char (match-beginning 0))
+	    (replace-match "")
+	    (cond
+	     ((member char '("G" "g"))
+	      (let* ((org-last-tags-completion-table
+		      (org-global-tags-completion-table
+		       (if (equal char "G") (org-agenda-files) (and file (list file)))))
+		     (ins (if lookup
+			      (cdr lookup)
+			     (if prompt (concat prompt ": ") "Tags: ")
+			     'org-tags-completion-function nil nil nil
+			     'org-tags-history))))
+		(if (null lookup)
+		    (setq interactive-entries (cons (cons prompt ins) interactive-entries)))
+		(setq ins (mapconcat 'identity
+				     (org-split-string ins (org-re "[^[:alnum:]]+"))
+				     ":"))
+		(when (string-match "\\S-" ins)
(or (equal (char-before) ?:) (insert ":"))
(insert ins)
(or (equal (char-after) ?:) (insert ":")))))
-	   (char
-	    (setq org-time-was-given (equal (upcase char) char))
-	    (setq time (org-read-date (equal (upcase char) "U") t nil
-				      prompt))
-	    (org-insert-time-stamp time org-time-was-given
-				   (member char '("u" "U"))
-				   nil nil (list org-end-time-was-given)))
-	   (t
-		     (if prompt (concat prompt ": ") "Enter string"))))))
+	     (char
+	      (setq org-time-was-given (equal (upcase char) char))
+	      (setq time (if lookup (cdr lookup) (org-read-date (equal (upcase char) "U") t nil
+								prompt)))
+	      (if (null lookup)
+		  (setq interactive-entries (cons (cons prompt time) interactive-entries))
+		(org-insert-time-stamp time org-time-was-given
+				       (member char '("u" "U"))
+				       nil nil (list org-end-time-was-given))))
+	     (t
+	      (let ((text
+		     (if lookup
+			 (cdr lookup)
+			(if prompt (concat prompt ": ") "Enter string")))))
+		(insert (or text ""))
+		(if (null lookup)
+		    (setq interactive-entries (cons (cons prompt text) interactive-entries))))))))
(goto-char (point-min))
(if (re-search-forward "%\\?" nil t)
(replace-match "")


Have fun!

## Emacs, Org, and BBDB: Hyperlinking names to blogs

Back when I used Planner for Emacs, I coded some shortcuts to make it easier to write about the people I met and the conversations I had. I used the hippie-expand module to complete names from my Big Brother Database addressbook, and I wrote a function that converted those names into links to people’s blogs or websites whenever I published my blog posts as HTML.

I switched to WordPress for my blog because I got tired of trying to figure out a way to enable comments without getting mired in spam-fighting. That meant I could explore other Emacs personal information managers like Org, which I turned into my main task manager. I often used the WordPress interface to write blog posts. I sometimes used Windows Live Writer to write posts about books (there’s a good book review plugin that makes this easy). I also sometimes used Emacs and Org to draft blog posts using Org’s friendlier markup, exporting snippets to HTML that I then pasted into my blog posts.

Reading the posts on Planet Emacsen reminded me that my customized configuration was pretty darn sweet. That and the conversation notes I’ve been blogging lately encouraged me to dust off my configuration files and get them to work under Org. So here’s the code:

 (defun sacha/org-bbdb-get (path)
"Return BBDB record for PATH."
(car (bbdb-search (bbdb-records) path path path)))

(defun sacha/org-bbdb-export (path desc format)
"Create the export version of a BBDB link specified by PATH or DESC.
If exporting to HTML, it will be linked to the person's blog,
www, or web address. If exporting to LaTeX FORMAT the link will be
italicised. In all other cases, it is left unchanged."
(cond
((eq format 'html)
(let* ((record
(sacha/org-bbdb-get path))
url)
(setq url (and record
(or (bbdb-record-getprop record 'blog)
(bbdb-record-getprop record 'www)
(bbdb-record-getprop record 'web))))
(if url
(format "<a href=\"%s\">%s</a>"
url (or desc path))
(format "<em>%s</em>"
(or desc path)))))
((eq format 'latex) (format "\\textit{%s}" (or desc path)))
(t (or desc path))))

"Override org-bbdb-export."
(setq ad-return-value (sacha/org-bbdb-export path desc format)))

;;;_+ Hippie expansion for BBDB; map M-/ to hippie-expand for most fun
(defun sacha/try-expand-bbdb-annotation (old)
"Expand from BBDB. If OLD is non-nil, cycle through other possibilities."
(unless old
;; First time, so search through BBDB records for the name
(he-init-string (he-dabbrev-beg) (point))
(when (> (length he-search-string) 0)
(setq he-expand-list nil)
(mapcar
(lambda (item)
(let ((name (bbdb-record-name item)))
(when name
(setq he-expand-list
name)
he-expand-list)))))
(bbdb-search (bbdb-records)
he-search-string
he-search-string
he-search-string
nil nil))))
(while (and he-expand-list
(or (not (car he-expand-list))
(he-string-member (car he-expand-list) he-tried-table t)))
(setq he-expand-list (cdr he-expand-list)))
(if (null he-expand-list)
(progn
(if old (he-reset-string))
nil)
(progn
(he-substitute-string (car he-expand-list) t)
(setq he-expand-list (cdr he-expand-list))
t)))
`

If you’ve got Org and BBDB, drop this into your ~/.emacs and fiddle with it. =)