86919f969f003730483b1c6c9c26fe16952b7a3f
[worg.git] / org-hacks.org
1 #+TITLE:      Org ad hoc code, quick hacks and workarounds
2 #+AUTHOR:     Worg people
3 #+EMAIL:      mdl AT imapmail DOT org
4 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
5 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
6 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
7 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
8 #+LANGUAGE:   en
9 #+PRIORITIES: A C B
10 #+CATEGORY:   worg
11
12 # This file is the default header for new Org files in Worg.  Feel free
13 # to tailor it to your needs.
14
15 [[file:index.org][{Back to Worg's index}]]
16
17 This page is for ad hoc bits of code. Feel free to add quick hacks and
18 workaround. Go crazy.
19
20 * Hacking Org: Working within Org-mode.
21 ** Org Agenda
22
23 *** Picking up a random task in the global TODO list
24
25 Tony day [[http://mid.gmane.org/m2zk19l1me.fsf%2540gmail.com][shared]] [[https://gist.github.com/4343164][this gist]] to pick up a
26 random task.
27
28 ** Building and Managing Org
29 *** Generating autoloads and Compiling Org without make
30     :PROPERTIES:
31     :CUSTOM_ID: compiling-org-without-make
32     :END:
33
34 #+index: Compilation!without make
35
36   Compilation is optional, but you _must_ update the autoloads file
37   each time you update org, even when you run org uncompiled!
38
39   Starting with Org 7.9 you'll find functions for creating the
40   autoload files and do byte-compilation in =mk/org-fixup.el=.  When
41   you execute the commands below, your current directory must be where
42   org has been unpacked into, in other words the file =README= should
43   be found in your current directory and the directories =lisp= and
44   =etc= should be subdirectories of it.  The command =emacs= should be
45   found in your =PATH= and start the Emacs version you are using.  To
46   make just the autoloads file do:
47   : emacs -batch -Q -L lisp -l ../mk/org-fixup -f org-make-autoloads
48   To make the autoloads file and byte-compile org:
49   : emacs -batch -Q -L lisp -l ../mk/org-fixup -f org-make-autoloads-compile
50   To make the autoloads file and byte-compile all of org again:
51   : emacs -batch -Q -L lisp -l ../mk/org-fixup -f org-make-autoloads-compile-force
52   If you are not using Git, you'll have to make fake version strings
53   first if =org-version.el= is not already available (if it is, you
54   could also edit the version strings there).
55   : emacs -batch -Q -L lisp -l ../mk/org-fixup \
56   : --eval '(let ((org-fake-release "7.9.1")(org-fake-git-version "7.9.1-fake"))\
57   : (org-make-autoloads))'
58   The above assumes a
59   POSIX shell for its quoting.  Windows =CMD.exe= has quite different
60   quoting rules and this won't work, so your other option is to start
61   Emacs like this
62   : emacs -Q -L lisp -l ../mk/org-fixup
63   then paste the following into the =*scratch*= buffer
64 #+BEGIN_SRC emacs-lisp
65   (let ((org-fake-release     "7.9.1")
66         (org-fake-git-version "7.9.1-fake"))
67     (org-make-autoloads))
68 #+END_SRC
69   position the cursor after the closing paren and press =C-j= or =C-x
70   C-e= to evaluate the form.  Of course you can replace
71   =org-make-autoloads= with =org-make-autoloads-compile= or even
72   =org-make-autoloads-compile-force= if you wish with both variants.
73
74   For *older org versions only* (that do not yet have
75   =mk/org-fixup.el=), you can use the definitions below.  To use
76   this function, adjust the variables =my/org-lisp-directory= and
77   =my/org-compile-sources= to suit your needs.  If you have
78   byte-compiled org, but want to run org uncompiled again, just remove
79   all =*.elc= files in the =lisp/= directory, set
80   =my/org-compile-sources= to =nil=.
81
82 #+BEGIN_SRC emacs-lisp
83   (defvar my/org-lisp-directory "~/.emacs.d/org/lisp/"
84     "Directory where your org-mode files live.")
85   
86   (defvar my/org-compile-sources t
87     "If `nil', never compile org-sources. `my/compile-org' will only create
88   the autoloads file `org-loaddefs.el' then. If `t', compile the sources, too.")
89   
90   ;; Customize: (must end with a slash!)
91   (setq my/org-lisp-directory "~/.emacs.d/org/lisp/")
92   
93   ;; Customize:
94   (setq  my/org-compile-sources t)
95   
96   (defun my/compile-org(&optional directory)
97     "Generate autoloads file org-loaddefs.el.  Optionally compile
98      all *.el files that come with org-mode."
99     (interactive)
100     (defun my/compile-org()
101       "Generate autoloads file org-loaddefs.el.  Optionally compile
102        all *.el files that come with org-mode."
103       (interactive)
104       (let ((dirlisp (file-name-directory my/org-lisp-directory)))
105         (add-to-list 'load-path dirlisp)
106         (require 'autoload)
107         (let ((generated-autoload-file (concat dirlisp "org-loaddefs.el")))
108           ;; create the org-loaddefs file
109           (update-directory-autoloads dirlisp)
110           (when my/org-compile-sources
111             ;; optionally byte-compile
112             (byte-recompile-directory dirlisp 0 'force)))))
113   #+END_SRC
114 *** Reload Org
115
116 #+index: Initialization!Reload
117
118 As of Org version 6.23b (released Sunday Feb 22, 2009) there is a new
119 function to reload org files.
120
121 Normally you want to use the compiled files since they are faster.
122 If you update your org files you can easily reload them with
123
124 : M-x org-reload
125
126 If you run into a bug and want to generate a useful backtrace you can
127 reload the source files instead of the compiled files with
128
129 : C-u M-x org-reload
130
131 and turn on the "Enter Debugger On Error" option.  Redo the action
132 that generates the error and cut and paste the resulting backtrace.
133 To switch back to the compiled version just reload again with
134
135 : M-x org-reload
136
137 *** Check for possibly problematic old link escapes
138 :PROPERTIES:
139 :CUSTOM_ID: check-old-link-escapes
140 :END:
141 #+index: Link!Escape
142 Starting with version 7.5 Org uses [[http://en.wikipedia.org/wiki/Percent-encoding][percent escaping]] more consistently
143 and with a modified algorithm to determine which characters to escape
144 and how.
145
146 As a side effect this modified behaviour might break existing links if
147 they contain a sequence of characters that look like a percent escape
148 (e.g. =[0-9A-Fa-f]{2}=) but are in fact not a percent escape.
149
150 The function below can be used to perform a preliminary check for such
151 links in an Org mode file.  It will run through all links in the file
152 and issue a warning if it finds a percent escape sequence which is not
153 in old Org's list of known percent escapes.
154
155 #+begin_src emacs-lisp
156   (defun dmaus/org-check-percent-escapes ()
157     "*Check buffer for possibly problematic old link escapes."
158     (interactive)
159     (when (eq major-mode 'org-mode)
160       (let ((old-escapes '("%20" "%5B" "%5D" "%E0" "%E2" "%E7" "%E8" "%E9"
161                            "%EA" "%EE" "%F4" "%F9" "%FB" "%3B" "%3D" "%2B")))
162         (unless (boundp 'warning-suppress-types)
163           (setq warning-suppress-types nil))
164         (widen)
165         (show-all)
166         (goto-char (point-min))
167         (while (re-search-forward org-any-link-re nil t)
168           (let ((end (match-end 0)))
169             (goto-char (match-beginning 0))
170             (while (re-search-forward "%[0-9a-zA-Z]\\{2\\}" end t)
171               (let ((escape (match-string-no-properties 0)))
172                 (unless (member (upcase escape) old-escapes)
173                   (warn "Found unknown percent escape sequence %s at buffer %s, position %d"
174                         escape
175                         (buffer-name)
176                         (- (point) 3)))))
177             (goto-char end))))))
178 #+end_src
179
180 ** Structure Movement and Editing 
181 *** Show next/prev heading tidily
182
183 #+index: Navigation!Heading
184 - Dan Davison
185   These close the current heading and open the next/previous heading.
186
187 #+begin_src emacs-lisp
188 (defun ded/org-show-next-heading-tidily ()
189   "Show next entry, keeping other entries closed."
190   (if (save-excursion (end-of-line) (outline-invisible-p))
191       (progn (org-show-entry) (show-children))
192     (outline-next-heading)
193     (unless (and (bolp) (org-on-heading-p))
194       (org-up-heading-safe)
195       (hide-subtree)
196       (error "Boundary reached"))
197     (org-overview)
198     (org-reveal t)
199     (org-show-entry)
200     (show-children)))
201
202 (defun ded/org-show-previous-heading-tidily ()
203   "Show previous entry, keeping other entries closed."
204   (let ((pos (point)))
205     (outline-previous-heading)
206     (unless (and (< (point) pos) (bolp) (org-on-heading-p))
207       (goto-char pos)
208       (hide-subtree)
209       (error "Boundary reached"))
210     (org-overview)
211     (org-reveal t)
212     (org-show-entry)
213     (show-children)))
214
215 (setq org-use-speed-commands t)
216 (add-to-list 'org-speed-commands-user
217              '("n" ded/org-show-next-heading-tidily))
218 (add-to-list 'org-speed-commands-user
219              '("p" ded/org-show-previous-heading-tidily))
220 #+end_src
221
222 *** Promote all items in subtree
223 #+index: Structure Editing!Promote
224 - Matt Lundin
225
226 This function will promote all items in a subtree. Since I use
227 subtrees primarily to organize projects, the function is somewhat
228 unimaginatively called my-org-un-project:
229
230 #+begin_src emacs-lisp
231 (defun my-org-un-project ()
232   (interactive)
233   (org-map-entries 'org-do-promote "LEVEL>1" 'tree)
234   (org-cycle t))
235 #+end_src
236
237 *** Turn a heading into an Org link
238     :PROPERTIES:
239     :CUSTOM_ID: heading-to-link
240     :END:
241 #+index: Structure Editing!Heading
242 #+index: Link!Turn a heading into a
243 From David Maus:
244
245 #+begin_src emacs-lisp
246   (defun dmj:turn-headline-into-org-mode-link ()
247     "Replace word at point by an Org mode link."
248     (interactive)
249     (when (org-at-heading-p)
250       (let ((hl-text (nth 4 (org-heading-components))))
251         (unless (or (null hl-text)
252                     (org-string-match-p "^[ \t]*:[^:]+:$" hl-text))
253           (beginning-of-line)
254           (search-forward hl-text (point-at-eol))
255           (replace-string
256            hl-text
257            (format "[[file:%s.org][%s]]"
258                    (org-link-escape hl-text)
259                    (org-link-escape hl-text '((?\] . "%5D") (?\[ . "%5B"))))
260            nil (- (point) (length hl-text)) (point))))))
261 #+end_src
262
263 *** Using M-up and M-down to transpose paragraphs
264 #+index: Structure Editing!paragraphs
265
266 From Paul Sexton: By default, if used within ordinary paragraphs in
267 org mode, =M-up= and =M-down= transpose *lines* (not sentences).  The
268 following code makes these keys transpose paragraphs, keeping the
269 point at the start of the moved paragraph. Behavior in tables and
270 headings is unaffected. It would be easy to modify this to transpose
271 sentences.
272
273 #+begin_src emacs-lisp
274 (defun org-transpose-paragraphs (arg)
275  (interactive)
276  (when (and (not (or (org-at-table-p) (org-on-heading-p) (org-at-item-p)))
277             (thing-at-point 'sentence))
278    (transpose-paragraphs arg)
279    (backward-paragraph)
280    (re-search-forward "[[:graph:]]")
281    (goto-char (match-beginning 0))
282    t))
283
284 (add-to-list 'org-metaup-hook 
285  (lambda () (interactive) (org-transpose-paragraphs -1)))
286 (add-to-list 'org-metadown-hook 
287  (lambda () (interactive) (org-transpose-paragraphs 1)))
288 #+end_src
289 *** Changelog support for org headers
290 #+index: Structure Editing!Heading
291 -- James TD Smith
292
293 Put the following in your =.emacs=, and =C-x 4 a= and other functions which
294 use =add-log-current-defun= like =magit-add-log= will pick up the nearest org
295 headline as the "current function" if you add a changelog entry from an org
296 buffer.
297
298 #+BEGIN_SRC emacs-lisp
299   (defun org-log-current-defun ()
300     (save-excursion
301       (org-back-to-heading)
302       (if (looking-at org-complex-heading-regexp)
303           (match-string 4))))
304
305   (add-hook 'org-mode-hook
306             (lambda ()
307               (make-variable-buffer-local 'add-log-current-defun-function)
308               (setq add-log-current-defun-function 'org-log-current-defun)))
309 #+END_SRC
310
311 *** Different org-cycle-level behavior
312 #+index: Cycling!behavior
313 -- Ryan Thompson
314
315 In recent org versions, when your point (cursor) is at the end of an
316 empty header line (like after you first created the header), the TAB
317 key (=org-cycle=) has a special behavior: it cycles the headline through
318 all possible levels. However, I did not like the way it determined
319 "all possible levels," so I rewrote the whole function, along with a
320 couple of supporting functions.
321
322 The original function's definition of "all possible levels" was "every
323 level from 1 to one more than the initial level of the current
324 headline before you started cycling." My new definition is "every
325 level from 1 to one more than the previous headline's level." So, if
326 you have a headline at level 4 and you use ALT+RET to make a new
327 headline below it, it will cycle between levels 1 and 5, inclusive.
328
329 The main advantage of my custom =org-cycle-level= function is that it
330 is stateless: the next level in the cycle is determined entirely by
331 the contents of the buffer, and not what command you executed last.
332 This makes it more predictable, I hope.
333
334 #+BEGIN_SRC emacs-lisp
335 (require 'cl)
336
337 (defun org-point-at-end-of-empty-headline ()
338   "If point is at the end of an empty headline, return t, else nil."
339   (and (looking-at "[ \t]*$")
340        (save-excursion
341          (beginning-of-line 1)
342          (looking-at (concat "^\\(\\*+\\)[ \t]+\\(" org-todo-regexp "\\)?[ \t]*")))))
343
344 (defun org-level-increment ()
345   "Return the number of stars that will be added or removed at a
346 time to headlines when structure editing, based on the value of
347 `org-odd-levels-only'."
348   (if org-odd-levels-only 2 1))
349
350 (defvar org-previous-line-level-cached nil)
351
352 (defun org-recalculate-previous-line-level ()
353   "Same as `org-get-previous-line-level', but does not use cached
354 value. It does *set* the cached value, though."
355   (set 'org-previous-line-level-cached
356        (let ((current-level (org-current-level))
357              (prev-level (when (> (line-number-at-pos) 1)
358                            (save-excursion
359                              (previous-line)
360                              (org-current-level)))))
361          (cond ((null current-level) nil) ; Before first headline
362                ((null prev-level) 0)      ; At first headline
363                (prev-level)))))
364
365 (defun org-get-previous-line-level ()
366   "Return the outline depth of the last headline before the
367 current line. Returns 0 for the first headline in the buffer, and
368 nil if before the first headline."
369   ;; This calculation is quite expensive, with all the regex searching
370   ;; and stuff. Since org-cycle-level won't change lines, we can reuse
371   ;; the last value of this command.
372   (or (and (eq last-command 'org-cycle-level)
373            org-previous-line-level-cached)
374       (org-recalculate-previous-line-level)))
375
376 (defun org-cycle-level ()
377   (interactive)
378   (let ((org-adapt-indentation nil))
379     (when (org-point-at-end-of-empty-headline)
380       (setq this-command 'org-cycle-level) ;Only needed for caching
381       (let ((cur-level (org-current-level))
382             (prev-level (org-get-previous-line-level)))
383         (cond
384          ;; If first headline in file, promote to top-level.
385          ((= prev-level 0)
386           (loop repeat (/ (- cur-level 1) (org-level-increment))
387                 do (org-do-promote)))
388          ;; If same level as prev, demote one.
389          ((= prev-level cur-level)
390           (org-do-demote))
391          ;; If parent is top-level, promote to top level if not already.
392          ((= prev-level 1)
393           (loop repeat (/ (- cur-level 1) (org-level-increment))
394                 do (org-do-promote)))
395          ;; If top-level, return to prev-level.
396          ((= cur-level 1)
397           (loop repeat (/ (- prev-level 1) (org-level-increment))
398                 do (org-do-demote)))
399          ;; If less than prev-level, promote one.
400          ((< cur-level prev-level)
401           (org-do-promote))
402          ;; If deeper than prev-level, promote until higher than
403          ;; prev-level.
404          ((> cur-level prev-level)
405           (loop repeat (+ 1 (/ (- cur-level prev-level) (org-level-increment)))
406                 do (org-do-promote))))
407         t))))
408 #+END_SRC
409
410 *** Count words in an Org buffer
411 #FIXME: Does not fit too well under Structure. Any idea where to put it?
412 Paul Sexton [[http://article.gmane.org/gmane.emacs.orgmode/38014][posted]] this function to count words in an Org buffer:
413
414 #+begin_src emacs-lisp
415 (defun org-word-count (beg end
416                            &optional count-latex-macro-args?
417                            count-footnotes?)
418   "Report the number of words in the Org mode buffer or selected region.
419 Ignores:
420 - comments
421 - tables
422 - source code blocks (#+BEGIN_SRC ... #+END_SRC, and inline blocks)
423 - hyperlinks (but does count words in hyperlink descriptions)
424 - tags, priorities, and TODO keywords in headers
425 - sections tagged as 'not for export'.
426
427 The text of footnote definitions is ignored, unless the optional argument
428 COUNT-FOOTNOTES? is non-nil.
429
430 If the optional argument COUNT-LATEX-MACRO-ARGS? is non-nil, the word count
431 includes LaTeX macro arguments (the material between {curly braces}).
432 Otherwise, and by default, every LaTeX macro counts as 1 word regardless
433 of its arguments."
434   (interactive "r")
435   (unless mark-active
436     (setf beg (point-min)
437           end (point-max)))
438   (let ((wc 0)
439         (latex-macro-regexp "\\\\[A-Za-z]+\\(\\[[^]]*\\]\\|\\){\\([^}]*\\)}"))
440     (save-excursion
441       (goto-char beg)
442       (while (< (point) end)
443         (cond
444          ;; Ignore comments.
445          ((or (org-in-commented-line) (org-at-table-p))
446           nil)
447          ;; Ignore hyperlinks. But if link has a description, count
448          ;; the words within the description.
449          ((looking-at org-bracket-link-analytic-regexp)
450           (when (match-string-no-properties 5)
451             (let ((desc (match-string-no-properties 5)))
452               (save-match-data
453                 (incf wc (length (remove "" (org-split-string
454                                              desc "\\W")))))))
455           (goto-char (match-end 0)))
456          ((looking-at org-any-link-re)
457           (goto-char (match-end 0)))
458          ;; Ignore source code blocks.
459          ((org-in-regexps-block-p "^#\\+BEGIN_SRC\\W" "^#\\+END_SRC\\W")
460           nil)
461          ;; Ignore inline source blocks, counting them as 1 word.
462          ((save-excursion
463             (backward-char)
464             (looking-at org-babel-inline-src-block-regexp))
465           (goto-char (match-end 0))
466           (setf wc (+ 2 wc)))
467          ;; Count latex macros as 1 word, ignoring their arguments.
468          ((save-excursion
469             (backward-char)
470             (looking-at latex-macro-regexp))
471           (goto-char (if count-latex-macro-args?
472                          (match-beginning 2)
473                        (match-end 0)))
474           (setf wc (+ 2 wc)))
475          ;; Ignore footnotes.
476          ((and (not count-footnotes?)
477                (or (org-footnote-at-definition-p)
478                    (org-footnote-at-reference-p)))
479           nil)
480          (t
481           (let ((contexts (org-context)))
482             (cond
483              ;; Ignore tags and TODO keywords, etc.
484              ((or (assoc :todo-keyword contexts)
485                   (assoc :priority contexts)
486                   (assoc :keyword contexts)
487                   (assoc :checkbox contexts))
488               nil)
489              ;; Ignore sections marked with tags that are
490              ;; excluded from export.
491              ((assoc :tags contexts)
492               (if (intersection (org-get-tags-at) org-export-exclude-tags
493                                 :test 'equal)
494                   (org-forward-same-level 1)
495                 nil))
496              (t
497               (incf wc))))))
498         (re-search-forward "\\w+\\W*")))
499     (message (format "%d words in %s." wc
500                      (if mark-active "region" "buffer")))))
501 #+end_src
502
503 *** Check for misplaced SCHEDULED and DEADLINE cookies
504
505 The =SCHEDULED= and =DEADLINE= cookies should be used on the line *right
506 below* the headline -- like this:
507
508 #+begin_src org
509   ,* A headline
510   ,  SCHEDULED: <2012-04-09 lun.>
511 #+end_src
512
513 This is what =org-scheduled= and =org-deadline= (and other similar
514 commands) do.  And the manual explicitely tell people to stick to this
515 format (see the section "8.3.1 Inserting deadlines or schedules").
516
517 If you think you might have subtrees with misplaced =SCHEDULED= and
518 =DEADLINE= cookies, this command lets you check the current buffer:
519
520 #+begin_src emacs-lisp
521 (defun org-check-misformatted-subtree ()
522   "Check misformatted entries in the current buffer."
523   (interactive)
524   (show-all)
525   (org-map-entries
526    (lambda ()
527      (when (and (move-beginning-of-line 2)
528                 (not (looking-at org-heading-regexp)))
529        (if (or (and (org-get-scheduled-time (point))
530                     (not (looking-at (concat "^.*" org-scheduled-regexp))))
531                (and (org-get-deadline-time (point))
532                     (not (looking-at (concat "^.*" org-deadline-regexp)))))
533            (when (y-or-n-p "Fix this subtree? ")
534              (message "Call the function again when you're done fixing this subtree.")
535              (recursive-edit))
536          (message "All subtrees checked."))))))
537 #+end_src
538
539 *** Sorting list by checkbox type
540
541 #+index: checkbox!sorting
542
543 You can use a custom function to sort list by checkbox type.
544 Here is a function suggested by Carsten:
545
546 #+BEGIN_SRC emacs-lisp
547 (defun org-sort-list-by-checkbox-type ()
548   "Sort list items according to Checkbox state."
549   (interactive)
550   (org-sort-list
551    nil ?f
552    (lambda ()
553      (if (looking-at org-list-full-item-re)
554          (cdr (assoc (match-string 3)
555                      '(("[X]" . 1) ("[-]" . 2) ("[ ]" . 3) (nil . 4))))
556        4))))
557 #+END_SRC
558
559 Use the function above directly on the list.  If you want to use an
560 equivalent function after =C-c ^ f=, use this one instead:
561
562 #+BEGIN_SRC emacs-lisp
563   (defun org-sort-list-by-checkbox-type-1 ()
564     (lambda ()
565       (if (looking-at org-list-full-item-re)
566           (cdr (assoc (match-string 3)
567                       '(("[X]" . 1) ("[-]" . 2) ("[ ]" . 3) (nil . 4))))
568         4)))
569 #+END_SRC
570
571 ** Org Table
572 *** Align all tables in a file
573
574 Andrew Young provided this function in [[http://thread.gmane.org/gmane.emacs.orgmode/58974/focus%3D58976][this thread]]:
575
576 #+begin_src emacs-lisp
577   (defun my-align-all-tables ()
578     (interactive)
579     (org-table-map-tables 'org-table-align 'quietly))
580 #+end_src
581
582 *** Transpose table
583 #+index: Table!Calculation
584     :PROPERTIES:
585     :CUSTOM_ID: transpose-table
586     :END:
587
588 Since Org 7.8, you can use =org-table-transpose-table-at-point= (which
589 see.)  There are also other solutions:
590
591 - with org-babel and Emacs Lisp: provided by Thomas S. Dye in the mailing
592   list, see [[http://thread.gmane.org/gmane.emacs.orgmode/23809/focus=23815][gmane]] or [[http://lists.gnu.org/archive/html/emacs-orgmode/2010-04/msg00239.html][gnu]]
593
594 - with org-babel and R: provided by Dan Davison in the mailing list (old
595   =#+TBLR:= syntax), see [[http://thread.gmane.org/gmane.emacs.orgmode/10159/focus=10159][gmane]] or [[http://lists.gnu.org/archive/html/emacs-orgmode/2008-12/msg00454.html][gnu]]
596
597 - with field coordinates in formulas (=@#= and =$#=): see [[file:org-hacks.org::#field-coordinates-in-formulas-transpose-table][Worg]].
598
599 *** Manipulate hours/minutes/seconds in table formulas
600 #+index: Table!hours-minutes-seconds
601 Both Bastien and Martin Halder have posted code ([[http://article.gmane.org/gmane.emacs.orgmode/39519][Bastien's code]] and
602 [[http://article.gmane.org/gmane.emacs.orgmode/39519][Martin's code]]) for interpreting =dd:dd= or =dd:dd:dd= strings (where
603 "=d=" is any digit) as time values in Org-mode table formula.  These
604 functions have now been wrapped up into a =with-time= macro which can
605 be used in table formula to translate table cell values to and from
606 numerical values for algebraic manipulation.
607
608 Here is the code implementing this macro.
609 #+begin_src emacs-lisp :results silent
610   (defun org-time-string-to-seconds (s)
611     "Convert a string HH:MM:SS to a number of seconds."
612     (cond
613      ((and (stringp s)
614            (string-match "\\([0-9]+\\):\\([0-9]+\\):\\([0-9]+\\)" s))
615       (let ((hour (string-to-number (match-string 1 s)))
616             (min (string-to-number (match-string 2 s)))
617             (sec (string-to-number (match-string 3 s))))
618         (+ (* hour 3600) (* min 60) sec)))
619      ((and (stringp s)
620            (string-match "\\([0-9]+\\):\\([0-9]+\\)" s))
621       (let ((min (string-to-number (match-string 1 s)))
622             (sec (string-to-number (match-string 2 s))))
623         (+ (* min 60) sec)))
624      ((stringp s) (string-to-number s))
625      (t s)))
626
627   (defun org-time-seconds-to-string (secs)
628     "Convert a number of seconds to a time string."
629     (cond ((>= secs 3600) (format-seconds "%h:%.2m:%.2s" secs))
630           ((>= secs 60) (format-seconds "%m:%.2s" secs))
631           (t (format-seconds "%s" secs))))
632
633   (defmacro with-time (time-output-p &rest exprs)
634     "Evaluate an org-table formula, converting all fields that look
635   like time data to integer seconds.  If TIME-OUTPUT-P then return
636   the result as a time value."
637     (list
638      (if time-output-p 'org-time-seconds-to-string 'identity)
639      (cons 'progn
640            (mapcar
641             (lambda (expr)
642               `,(cons (car expr)
643                       (mapcar
644                        (lambda (el)
645                          (if (listp el)
646                              (list 'with-time nil el)
647                            (org-time-string-to-seconds el)))
648                        (cdr expr))))
649             `,@exprs))))
650 #+end_src
651
652 Which allows the following forms of table manipulation such as adding
653 and subtracting time values.
654 : | Date             | Start | Lunch |  Back |   End |  Sum |
655 : |------------------+-------+-------+-------+-------+------|
656 : | [2011-03-01 Tue] |  8:00 | 12:00 | 12:30 | 18:15 | 9:45 |
657 : #+TBLFM: $6='(with-time t (+ (- $5 $4) (- $3 $2)))
658
659 and dividing time values by integers
660 : |  time | miles | minutes/mile |
661 : |-------+-------+--------------|
662 : | 34:43 |   2.9 |        11:58 |
663 : | 32:15 |  2.77 |        11:38 |
664 : | 33:56 |   3.0 |        11:18 |
665 : | 52:22 |  4.62 |        11:20 |
666 : #+TBLFM: $3='(with-time t (/ $1 $2))
667
668 *Update*: As of Org version 7.6, you can use the =T= flag (both in Calc and
669 Elisp formulas) to compute time durations.  For example:
670
671 : | Task 1 | Task 2 |   Total |
672 : |--------+--------+---------|
673 : |  35:00 |  35:00 | 1:10:00 |
674 : #+TBLFM: @2$3=$1+$2;T
675
676 *** Dates computation
677 #+index: Table!dates
678 Xin Shi [[http://article.gmane.org/gmane.emacs.orgmode/15692][asked]] for a way to calculate the duration of 
679 dates stored in an org table.
680
681 Nick Dokos [[http://article.gmane.org/gmane.emacs.orgmode/15694][suggested]]:
682
683 Try the following:
684
685 | Start Date |   End Date | Duration |
686 |------------+------------+----------|
687 | 2004.08.07 | 2005.07.08 |      335 |
688 :#+TBLFM: $3=(date(<$2>)-date(<$1>))
689
690 See [[http://thread.gmane.org/gmane.emacs.orgmode/7741][this thread]] as well as [[http://article.gmane.org/gmane.emacs.orgmode/7753][this post]] (which is really a followup on the
691 above).  The problem that this last article pointed out was solved in [[http://article.gmane.org/gmane.emacs.orgmode/8001][this
692 post]] and Chris Randle's original musings are [[http://article.gmane.org/gmane.emacs.orgmode/6536/][here]].
693
694 *** Hex computation
695 #+index: Table!Calculation
696 As with Times computation, the following code allows Computation with
697 Hex values in Org-mode tables using the =with-hex= macro.
698
699 Here is the code implementing this macro.
700 #+begin_src emacs-lisp
701   (defun org-hex-strip-lead (str)
702     (if (and (> (length str) 2) (string= (substring str 0 2) "0x"))
703         (substring str 2) str))
704
705   (defun org-hex-to-hex (int)
706     (format "0x%x" int))
707
708   (defun org-hex-to-dec (str)
709     (cond
710      ((and (stringp str)
711            (string-match "\\([0-9a-f]+\\)" (setf str (org-hex-strip-lead str))))
712       (let ((out 0))
713         (mapc
714          (lambda (ch)
715            (setf out (+ (* out 16)
716                         (if (and (>= ch 48) (<= ch 57)) (- ch 48) (- ch 87)))))
717          (coerce (match-string 1 str) 'list))
718         out))
719      ((stringp str) (string-to-number str))
720      (t str)))
721
722   (defmacro with-hex (hex-output-p &rest exprs)
723     "Evaluate an org-table formula, converting all fields that look
724       like hexadecimal to decimal integers.  If HEX-OUTPUT-P then
725       return the result as a hex value."
726     (list
727      (if hex-output-p 'org-hex-to-hex 'identity)
728      (cons 'progn
729            (mapcar
730             (lambda (expr)
731               `,(cons (car expr)
732                       (mapcar (lambda (el)
733                                 (if (listp el)
734                                     (list 'with-hex nil el)
735                                   (org-hex-to-dec el)))
736                               (cdr expr))))
737             `,@exprs))))
738 #+end_src
739
740 Which allows the following forms of table manipulation such as adding
741 and subtracting hex values.
742 | 0x10 | 0x0 | 0x10 |  16 |
743 | 0x20 | 0x1 | 0x21 |  33 |
744 | 0x30 | 0x2 | 0x32 |  50 |
745 | 0xf0 | 0xf | 0xff | 255 |
746 #+TBLFM: $3='(with-hex 'hex (+ $2 $1))::$4='(with-hex nil (identity $3))
747
748 *** Field coordinates in formulas (=@#= and =$#=)
749     :PROPERTIES:
750     :CUSTOM_ID: field-coordinates-in-formulas
751     :END:
752 #+index: Table!Field Coordinates
753 -- Michael Brand
754
755 Following are some use cases that can be implemented with the “field
756 coordinates in formulas” described in the corresponding chapter in the
757 [[http://orgmode.org/manual/References.html#References][Org manual]].
758
759 **** Copy a column from a remote table into a column
760      :PROPERTIES:
761      :CUSTOM_ID: field-coordinates-in-formulas-copy-col-to-col
762      :END:
763
764 current column =$3= = remote column =$2=:
765 : #+TBLFM: $3 = remote(FOO, @@#$2)
766
767 **** Copy a row from a remote table transposed into a column
768      :PROPERTIES:
769      :CUSTOM_ID: field-coordinates-in-formulas-copy-row-to-col
770      :END:
771
772 current column =$1= = transposed remote row =@1=:
773 : #+TBLFM: $1 = remote(FOO, @$#$@#)
774
775 **** Transpose table
776      :PROPERTIES:
777      :CUSTOM_ID: field-coordinates-in-formulas-transpose-table
778      :END:
779
780 -- Michael Brand
781
782 This is more like a demonstration of using “field coordinates in formulas”
783 and is bound to be slow for large tables. See the discussion in the mailing
784 list on
785 [[http://thread.gmane.org/gmane.emacs.orgmode/22610/focus=23662][gmane]] or
786 [[http://lists.gnu.org/archive/html/emacs-orgmode/2010-04/msg00086.html][gnu]].
787 For more efficient solutions see
788 [[file:org-hacks.org::#transpose-table][Worg]].
789
790 To transpose this 4x7 table
791
792 : #+TBLNAME: FOO
793 : | year | 2004 | 2005 | 2006 | 2007 | 2008 | 2009 |
794 : |------+------+------+------+------+------+------|
795 : | min  |  401 |  501 |  601 |  701 |  801 |  901 |
796 : | avg  |  402 |  502 |  602 |  702 |  802 |  902 |
797 : | max  |  403 |  503 |  603 |  703 |  803 |  903 |
798
799 start with a 7x4 table without any horizontal line (to have filled
800 also the column header) and yet empty:
801
802 : |   |   |   |   |
803 : |   |   |   |   |
804 : |   |   |   |   |
805 : |   |   |   |   |
806 : |   |   |   |   |
807 : |   |   |   |   |
808 : |   |   |   |   |
809
810 Then add the =TBLFM= line below.  After recalculation this will end up with
811 the transposed copy:
812
813 : | year | min | avg | max |
814 : | 2004 | 401 | 402 | 403 |
815 : | 2005 | 501 | 502 | 503 |
816 : | 2006 | 601 | 602 | 603 |
817 : | 2007 | 701 | 702 | 703 |
818 : | 2008 | 801 | 802 | 803 |
819 : | 2009 | 901 | 902 | 903 |
820 : #+TBLFM: @<$<..@>$> = remote(FOO, @$#$@#)
821
822 The formula simply exchanges row and column numbers by taking
823 - the absolute remote row number =@$#= from the current column number =$#=
824 - the absolute remote column number =$@#= from the current row number =@#=
825
826 Formulas to be taken over from the remote table will have to be transformed
827 manually.
828
829 **** Dynamic variation of ranges
830
831 -- Michael Brand
832
833 In this example all columns next to =quote= are calculated from the column
834 =quote= and show the average change of the time series =quote[year]=
835 during the period of the preceding =1=, =2=, =3= or =4= years:
836
837 : | year | quote |   1 a |   2 a |   3 a |   4 a |
838 : |------+-------+-------+-------+-------+-------|
839 : | 2005 |    10 |       |       |       |       |
840 : | 2006 |    12 | 0.200 |       |       |       |
841 : | 2007 |    14 | 0.167 | 0.183 |       |       |
842 : | 2008 |    16 | 0.143 | 0.155 | 0.170 |       |
843 : | 2009 |    18 | 0.125 | 0.134 | 0.145 | 0.158 |
844 : #+TBLFM: @I$3..@>$>=if(@# >= $#, ($2 / subscr(@-I$2..@+I$2, @# + 1 - $#)) ^ (1 / ($# - 2)) - 1, string("")) +.0; f-3
845
846 The important part of the formula without the field blanking is:
847
848 : ($2 / subscr(@-I$2..@+I$2, @# + 1 - $#)) ^ (1 / ($# - 2)) - 1
849
850 which is the Emacs Calc implementation of the equation
851
852 /AvgChange(i, a) = (quote[i] / quote[i - a]) ^ (1 / a) - 1/
853
854 where /i/ is the current time and /a/ is the length of the preceding period.
855
856 *** Change the column sequence in one row only
857 #+index: Table!Editing
858     :PROPERTIES:
859     :CUSTOM_ID: column-sequence-in-row
860     :END:
861
862 -- Michael Brand
863
864 The functions below can be used to change the column sequence in one row
865 only, without affecting the other rows above and below like with M-<left> or
866 M-<right> (org-table-move-column). Please see the docstring of the functions
867 for more explanations. Below is one example per function, with this original
868 table as the starting point for each example:
869 : | a | b | c  | d  |
870 : | e | 9 | 10 | 11 |
871 : | f | g | h  | i  |
872
873 **** Move in row left
874
875 1) place point at "10" in original table
876 2) result of M-x my-org-table-move-column-in-row-left:
877    : | a | b  | c | d  |
878    : | e | 10 | 9 | 11 |
879    : | f | g  | h | i  |
880
881 **** Move in row right
882
883 1) place point at "9" in original table
884 2) result of M-x my-org-table-move-column-in-row-right:
885    : | a | b  | c | d  |
886    : | e | 10 | 9 | 11 |
887    : | f | g  | h | i  |
888
889 **** Rotate in row left
890
891 1) place point at "9" in original table
892 2) result of M-x my-org-table-rotate-column-in-row-left:
893    : | a | b  | c  | d |
894    : | e | 10 | 11 | 9 |
895    : | f | g  | h  | i |
896
897 **** Rotate in row right
898
899 1) place point at "9" in original table
900 2) result of M-x my-org-table-rotate-column-in-row-right:
901    : | a | b  | c | d  |
902    : | e | 11 | 9 | 10 |
903    : | f | g  | h | i  |
904
905 **** The functions
906
907 #+BEGIN_SRC emacs-lisp
908 (defun my-org-table-move-column-in-row-right ()
909   "Move column to the right, limited to the current row."
910   (interactive)
911   (my-org-table-move-column-in-row nil))
912 (defun my-org-table-move-column-in-row-left ()
913   "Move column to the left, limited to the current row."
914   (interactive)
915   (my-org-table-move-column-in-row 'left))
916
917 (defun my-org-table-move-column-in-row (&optional left)
918   "Move the current column to the right, limited to the current row.
919 With arg LEFT, move to the left.  For repeated invocation the point follows
920 the value and changes to the target colum.  Does not fix formulas."
921   ;; derived from `org-table-move-column'
922   (interactive "P")
923   (if (not (org-at-table-p))
924       (error "Not at a table"))
925   (org-table-find-dataline)
926   (org-table-check-inside-data-field)
927   (let* ((col (org-table-current-column))
928          (col1 (if left (1- col) col))
929          ;; Current cursor position
930          (colpos (if left (1- col) (1+ col))))
931     (if (and left (= col 1))
932         (error "Cannot move column further left"))
933     (if (and (not left) (looking-at "[^|\n]*|[^|\n]*$"))
934         (error "Cannot move column further right"))
935     (org-table-goto-column col1 t)
936     (and (looking-at "|\\([^|\n]+\\)|\\([^|\n]+\\)|")
937          (replace-match "|\\2|\\1|"))
938     (org-table-goto-column colpos)
939     (org-table-align)))
940
941 (defun my-org-table-rotate-column-in-row-right ()
942   "Rotate column to the right, limited to the current row."
943   (interactive)
944   (my-org-table-rotate-column-in-row nil))
945 (defun my-org-table-rotate-column-in-row-left ()
946   "Rotate column to the left, limited to the current row."
947   (interactive)
948   (my-org-table-rotate-column-in-row 'left))
949
950 (defun my-org-table-rotate-column-in-row (&optional left)
951   "Rotate the current column to the right, limited to the current row.
952 With arg LEFT, rotate to the left.  The boundaries of the rotation range are
953 the current and the most right column for both directions.  For repeated
954 invocation the point stays on the current column.  Does not fix formulas."
955   ;; derived from `org-table-move-column'
956   (interactive "P")
957   (if (not (org-at-table-p))
958       (error "Not at a table"))
959   (org-table-find-dataline)
960   (org-table-check-inside-data-field)
961   (let ((col (org-table-current-column)))
962     (org-table-goto-column col t)
963     (and (looking-at (if left
964                          "|\\([^|\n]+\\)|\\([^\n]+\\)|$"
965                        "|\\([^\n]+\\)|\\([^|\n]+\\)|$"))
966          (replace-match "|\\2|\\1|"))
967     (org-table-goto-column col)
968     (org-table-align)))
969 #+END_SRC
970
971 **** Key bindings
972
973 As hack I have this in an Org buffer to change temporarily to the desired
974 behavior with C-c C-c on one of the three snippets:
975 : - move in row:
976 :   #+begin_src emacs-lisp :results silent
977 :     (org-defkey org-mode-map [(meta left)]
978 :                 'my-org-table-move-column-in-row-left)
979 :     (org-defkey org-mode-map [(meta right)]
980 :                 'my-org-table-move-column-in-row-right)
981 :     (org-defkey org-mode-map [(left)]  'org-table-previous-field)
982 :     (org-defkey org-mode-map [(right)] 'org-table-next-field)
983 :   #+end_src
984 :
985 : - rotate in row:
986 :   #+begin_src emacs-lisp :results silent
987 :     (org-defkey org-mode-map [(meta left)]
988 :                 'my-org-table-rotate-column-in-row-left)
989 :     (org-defkey org-mode-map [(meta right)]
990 :                 'my-org-table-rotate-column-in-row-right)
991 :     (org-defkey org-mode-map [(left)]  'org-table-previous-field)
992 :     (org-defkey org-mode-map [(right)] 'org-table-next-field)
993 :   #+end_src
994 :
995 : - back to original:
996 :   #+begin_src emacs-lisp :results silent
997 :     (org-defkey org-mode-map [(meta left)]  'org-metaleft)
998 :     (org-defkey org-mode-map [(meta right)] 'org-metaright)
999 :     (org-defkey org-mode-map [(left)]  'backward-char)
1000 :     (org-defkey org-mode-map [(right)] 'forward-char)
1001 :   #+end_src
1002
1003 **** reasons why this is not put into the Org core
1004
1005 I consider this as only a hack for several reasons:
1006 - Generalization:  The existing org-table-move-column function could be
1007   enhanced with additional optional parameters to incorporate these
1008   functionalities and could be used as the only function for better
1009   maintainability.  Now it's only a copy/paste hack of several similar
1010   functions with simple modifications.
1011 - Bindings:  Should be convenient for repetition like M-<right>.  What
1012   should be bound where, what has to be left unbound?
1013 - Does not fix formulas.  Could be resolved for field formulas but
1014   most probably not for column or range formulas and this can lead
1015   to confusion.  AFAIK all "official" table manipulations fix formulas.
1016 - Completeness:  Not all variations and combinations are covered yet
1017   - left-right, up-down
1018   - move, rotate with range to end, rotate with range to begin
1019   - whole column/row, only in-row/in-column
1020
1021 ** Capture and Remember
1022 *** Customize the size of the frame for remember
1023 #+index: Remember!frame
1024 #+index: Customization!remember
1025 (Note: this hack is likely out of date due to the development of
1026 [[org-capture]].)
1027
1028 #FIXME: gmane link?
1029 On emacs-orgmode, Ryan C. Thompson suggested this:
1030
1031 #+begin_quote
1032 I am using org-remember set to open a new frame when used,
1033 and the default frame size is much too large. To fix this, I have
1034 designed some advice and a custom variable to implement custom
1035 parameters for the remember frame:
1036 #+end_quote
1037
1038 #+begin_src emacs-lisp
1039 (defcustom remember-frame-alist nil
1040   "Additional frame parameters for dedicated remember frame."
1041   :type 'alist
1042   :group 'remember)
1043
1044 (defadvice remember (around remember-frame-parameters activate)
1045   "Set some frame parameters for the remember frame."
1046   (let ((default-frame-alist (append remember-frame-alist
1047                                      default-frame-alist)))
1048     ad-do-it))
1049 #+end_src
1050
1051 Setting remember-frame-alist to =((width . 80) (height . 15)))= give a
1052 reasonable size for the frame.
1053 ** Handling Links
1054 *** [[#heading-to-link][Turn a heading into an org link]] 
1055 *** Quickaccess to the link part of hyperlinks
1056 #+index: Link!Referent
1057 Christian Moe [[http://permalink.gmane.org/gmane.emacs.orgmode/43122][asked]], if there is a simpler way to copy the link part
1058 of an org hyperling other than to use `C-c C-l C-a C-k C-g', 
1059 which is indeed kind of cumbersome.
1060
1061 The thread offered [[http://permalink.gmane.org/gmane.emacs.orgmode/43606][two ways]]:
1062
1063 Using a [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Keyboard-Macros.html][keyboard macro]]:
1064 #+begin_src emacs-lisp
1065 (fset 'getlink
1066       (lambda (&optional arg) 
1067         "Keyboard macro." 
1068         (interactive "p") 
1069         (kmacro-exec-ring-item (quote ("\C-c\C-l\C-a\C-k\C-g" 0 "%d")) arg)))
1070 #+end_src
1071
1072 or a function: 
1073 #+begin_src emacs-lisp
1074 (defun my-org-extract-link ()
1075   "Extract the link location at point and put it on the killring."
1076   (interactive)
1077   (when (org-in-regexp org-bracket-link-regexp 1)
1078     (kill-new (org-link-unescape (org-match-string-no-properties 1)))))
1079 #+end_src
1080
1081 They put the link destination on the killring and can be easily bound to a key.
1082
1083 *** Insert link with HTML title as default description
1084 When using `org-insert-link' (`C-c C-l') it might be useful to extract contents
1085 from HTML <title> tag and use it as a default link description. Here is a way to
1086 accomplish this:
1087
1088 #+begin_src emacs-lisp
1089 (require 'mm-url) ; to include mm-url-decode-entities-string
1090
1091 (defun my-org-insert-link ()
1092   "Insert org link where default description is set to html title."
1093   (interactive)
1094   (let* ((url (read-string "URL: "))
1095          (title (get-html-title-from-url url)))
1096     (org-insert-link nil url title)))
1097
1098 (defun get-html-title-from-url (url)
1099   "Return content in <title> tag."
1100   (let (x1 x2 (download-buffer (url-retrieve-synchronously url)))
1101     (save-excursion
1102       (set-buffer download-buffer)
1103       (beginning-of-buffer)
1104       (setq x1 (search-forward "<title>"))
1105       (search-forward "</title>")
1106       (setq x2 (search-backward "<"))
1107       (mm-url-decode-entities-string (buffer-substring-no-properties x1 x2)))))
1108 #+end_src
1109
1110 Then just use `M-x my-org-insert-link' instead of `org-insert-link'.
1111
1112 ** Archiving Content in Org-Mode
1113 *** Preserve top level headings when archiving to a file
1114 #+index: Archiving!Preserve top level headings
1115 - Matt Lundin
1116
1117 To preserve (somewhat) the integrity of your archive structure while
1118 archiving lower level items to a file, you can use the following
1119 defadvice:
1120
1121 #+begin_src emacs-lisp
1122 (defadvice org-archive-subtree (around my-org-archive-subtree activate)
1123   (let ((org-archive-location
1124          (if (save-excursion (org-back-to-heading)
1125                              (> (org-outline-level) 1))
1126              (concat (car (split-string org-archive-location "::"))
1127                      "::* "
1128                      (car (org-get-outline-path)))
1129            org-archive-location)))
1130     ad-do-it))
1131 #+end_src
1132
1133 Thus, if you have an outline structure such as...
1134
1135 #+begin_src org
1136 ,* Heading
1137 ,** Subheading
1138 ,*** Subsubheading
1139 #+end_src
1140
1141 ...archiving "Subsubheading" to a new file will set the location in
1142 the new file to the top level heading:
1143
1144 #+begin_src org
1145 ,* Heading
1146 ,** Subsubheading
1147 #+end_src
1148
1149 While this hack obviously destroys the outline hierarchy somewhat, it
1150 at least preserves the logic of level one groupings.
1151
1152 A slightly more complex version of this hack will not only keep the
1153 archive organized by top-level headings, but will also preserve the
1154 tags found on those headings:
1155
1156 #+begin_src emacs-lisp
1157   (defun my-org-inherited-no-file-tags ()
1158     (let ((tags (org-entry-get nil "ALLTAGS" 'selective))
1159           (ltags (org-entry-get nil "TAGS")))
1160       (mapc (lambda (tag)
1161               (setq tags
1162                     (replace-regexp-in-string (concat tag ":") "" tags)))
1163             (append org-file-tags (when ltags (split-string ltags ":" t))))
1164       (if (string= ":" tags) nil tags)))
1165
1166   (defadvice org-archive-subtree (around my-org-archive-subtree-low-level activate)
1167     (let ((tags (my-org-inherited-no-file-tags))
1168           (org-archive-location
1169            (if (save-excursion (org-back-to-heading)
1170                                (> (org-outline-level) 1))
1171                (concat (car (split-string org-archive-location "::"))
1172                        "::* "
1173                        (car (org-get-outline-path)))
1174              org-archive-location)))
1175       ad-do-it
1176       (with-current-buffer (find-file-noselect (org-extract-archive-file))
1177         (save-excursion
1178           (while (org-up-heading-safe))
1179           (org-set-tags-to tags)))))
1180 #+end_src
1181
1182 *** Archive in a date tree
1183 #+index: Archiving!date tree
1184 Posted to Org-mode mailing list by Osamu Okano [2010-04-21 Wed].
1185
1186 (Make sure org-datetree.el is loaded for this to work.)
1187
1188 #+begin_src emacs-lisp
1189 ;; (setq org-archive-location "%s_archive::date-tree")
1190 (defadvice org-archive-subtree
1191   (around org-archive-subtree-to-data-tree activate)
1192   "org-archive-subtree to date-tree"
1193   (if
1194       (string= "date-tree"
1195                (org-extract-archive-heading
1196                 (org-get-local-archive-location)))
1197       (let* ((dct (decode-time (org-current-time)))
1198              (y (nth 5 dct))
1199              (m (nth 4 dct))
1200              (d (nth 3 dct))
1201              (this-buffer (current-buffer))
1202              (location (org-get-local-archive-location))
1203              (afile (org-extract-archive-file location))
1204              (org-archive-location
1205               (format "%s::*** %04d-%02d-%02d %s" afile y m d
1206                       (format-time-string "%A" (encode-time 0 0 0 d m y)))))
1207         (message "afile=%s" afile)
1208         (unless afile
1209           (error "Invalid `org-archive-location'"))
1210         (save-excursion
1211           (switch-to-buffer (find-file-noselect afile))
1212           (org-datetree-find-year-create y)
1213           (org-datetree-find-month-create y m)
1214           (org-datetree-find-day-create y m d)
1215           (widen)
1216           (switch-to-buffer this-buffer))
1217         ad-do-it)
1218     ad-do-it))
1219 #+end_src
1220
1221 *** Add inherited tags to archived entries
1222 #+index: Archiving!Add inherited tags
1223 To make =org-archive-subtree= keep inherited tags, Osamu OKANO suggests to
1224 advise the function like this:
1225
1226 #+begin_example
1227 (defadvice org-archive-subtree
1228   (before add-inherited-tags-before-org-archive-subtree activate)
1229     "add inherited tags before org-archive-subtree"
1230     (org-set-tags-to (org-get-tags-at)))
1231 #+end_example
1232
1233 ** Using and Managing Org-Metadata
1234 *** Remove redundant tags of headlines
1235 #+index: Tag!Remove redundant
1236 -- David Maus
1237
1238 A small function that processes all headlines in current buffer and
1239 removes tags that are local to a headline and inherited by a parent
1240 headline or the #+FILETAGS: statement.
1241
1242 #+BEGIN_SRC emacs-lisp
1243   (defun dmj/org-remove-redundant-tags ()
1244     "Remove redundant tags of headlines in current buffer.
1245
1246   A tag is considered redundant if it is local to a headline and
1247   inherited by a parent headline."
1248     (interactive)
1249     (when (eq major-mode 'org-mode)
1250       (save-excursion
1251         (org-map-entries
1252          '(lambda ()
1253             (let ((alltags (split-string (or (org-entry-get (point) "ALLTAGS") "") ":"))
1254                   local inherited tag)
1255               (dolist (tag alltags)
1256                 (if (get-text-property 0 'inherited tag)
1257                     (push tag inherited) (push tag local)))
1258               (dolist (tag local)
1259                 (if (member tag inherited) (org-toggle-tag tag 'off)))))
1260          t nil))))
1261 #+END_SRC
1262
1263 *** Remove empty property drawers
1264 #+index: Drawer!Empty
1265 David Maus proposed this:
1266
1267 #+begin_src emacs-lisp
1268 (defun dmj:org:remove-empty-propert-drawers ()
1269   "*Remove all empty property drawers in current file."
1270   (interactive)
1271   (unless (eq major-mode 'org-mode)
1272     (error "You need to turn on Org mode for this function."))
1273   (save-excursion
1274     (goto-char (point-min))
1275     (while (re-search-forward ":PROPERTIES:" nil t)
1276       (save-excursion
1277         (org-remove-empty-drawer-at "PROPERTIES" (match-beginning 0))))))
1278 #+end_src
1279
1280 *** Group task list by a property
1281 #+index: Agenda!Group task list
1282 This advice allows you to group a task list in Org-Mode.  To use it,
1283 set the variable =org-agenda-group-by-property= to the name of a
1284 property in the option list for a TODO or TAGS search.  The resulting
1285 agenda view will group tasks by that property prior to searching.
1286
1287 #+begin_src emacs-lisp
1288 (defvar org-agenda-group-by-property nil
1289   "Set this in org-mode agenda views to group tasks by property")
1290
1291 (defun org-group-bucket-items (prop items)
1292   (let ((buckets ()))
1293     (dolist (item items)
1294       (let* ((marker (get-text-property 0 'org-marker item))
1295              (pvalue (org-entry-get marker prop t))
1296              (cell (assoc pvalue buckets)))
1297         (if cell
1298             (setcdr cell (cons item (cdr cell)))
1299           (setq buckets (cons (cons pvalue (list item))
1300                               buckets)))))
1301     (setq buckets (mapcar (lambda (bucket)
1302                             (cons (car bucket)
1303                                   (reverse (cdr bucket))))
1304                           buckets))
1305     (sort buckets (lambda (i1 i2)
1306                     (string< (car i1) (car i2))))))
1307
1308 (defadvice org-finalize-agenda-entries (around org-group-agenda-finalize
1309                                                (list &optional nosort))
1310   "Prepare bucketed agenda entry lists"
1311   (if org-agenda-group-by-property
1312       ;; bucketed, handle appropriately
1313       (let ((text ""))
1314         (dolist (bucket (org-group-bucket-items
1315                          org-agenda-group-by-property
1316                          list))
1317           (let ((header (concat "Property "
1318                                 org-agenda-group-by-property
1319                                 " is "
1320                                 (or (car bucket) "<nil>") ":\n")))
1321             (add-text-properties 0 (1- (length header))
1322                                  (list 'face 'org-agenda-structure)
1323                                  header)
1324             (setq text
1325                   (concat text header
1326                           ;; recursively process
1327                           (let ((org-agenda-group-by-property nil))
1328                             (org-finalize-agenda-entries
1329                              (cdr bucket) nosort))
1330                           "\n\n"))))
1331         (setq ad-return-value text))
1332     ad-do-it))
1333 (ad-activate 'org-finalize-agenda-entries)
1334 #+end_src
1335 *** A way to tag a task so that when clocking-out user is prompted to take a note.
1336 #+index: Tag!Clock
1337 #+index: Clock!Tag
1338     Thanks to Richard Riley (see [[http://permalink.gmane.org/gmane.emacs.orgmode/40896][this post on the mailing list]]).
1339
1340 A small hook run when clocking out of a task that prompts for a note
1341 when the tag "=clockout_note=" is found in a headline. It uses the tag
1342 ("=clockout_note=") so inheritance can also be used...
1343
1344 #+begin_src emacs-lisp
1345   (defun rgr/check-for-clock-out-note()
1346         (interactive)
1347         (save-excursion
1348           (org-back-to-heading)
1349           (let ((tags (org-get-tags)))
1350             (and tags (message "tags: %s " tags)
1351                  (when (member "clocknote" tags)
1352                    (org-add-note))))))
1353
1354   (add-hook 'org-clock-out-hook 'rgr/check-for-clock-out-note)
1355 #+end_src
1356 *** Dynamically adjust tag position
1357 #+index: Tag!position
1358 Here is a bit of code that allows you to have the tags always
1359 right-adjusted in the buffer.
1360
1361 This is useful when you have bigger window than default window-size
1362 and you dislike the aesthetics of having the tag in the middle of the
1363 line.
1364
1365 This hack solves the problem of adjusting it whenever you change the
1366 window size.
1367 Before saving it will revert the file to having the tag position be
1368 left-adjusted so that if you track your files with version control,
1369 you won't run into artificial diffs just because the window-size
1370 changed.
1371
1372 *IMPORTANT*: This is probably slow on very big files.
1373
1374 #+begin_src emacs-lisp
1375 (setq ba/org-adjust-tags-column t)
1376
1377 (defun ba/org-adjust-tags-column-reset-tags ()
1378   "In org-mode buffers it will reset tag position according to
1379 `org-tags-column'."
1380   (when (and
1381          (not (string= (buffer-name) "*Remember*"))
1382          (eql major-mode 'org-mode))
1383     (let ((b-m-p (buffer-modified-p)))
1384       (condition-case nil
1385           (save-excursion
1386             (goto-char (point-min))
1387             (command-execute 'outline-next-visible-heading)
1388             ;; disable (message) that org-set-tags generates
1389             (flet ((message (&rest ignored) nil))
1390               (org-set-tags 1 t))
1391             (set-buffer-modified-p b-m-p))
1392         (error nil)))))
1393
1394 (defun ba/org-adjust-tags-column-now ()
1395   "Right-adjust `org-tags-column' value, then reset tag position."
1396   (set (make-local-variable 'org-tags-column)
1397        (- (- (window-width) (length org-ellipsis))))
1398   (ba/org-adjust-tags-column-reset-tags))
1399
1400 (defun ba/org-adjust-tags-column-maybe ()
1401   "If `ba/org-adjust-tags-column' is set to non-nil, adjust tags."
1402   (when ba/org-adjust-tags-column
1403     (ba/org-adjust-tags-column-now)))
1404
1405 (defun ba/org-adjust-tags-column-before-save ()
1406   "Tags need to be left-adjusted when saving."
1407   (when ba/org-adjust-tags-column
1408      (setq org-tags-column 1)
1409      (ba/org-adjust-tags-column-reset-tags)))
1410
1411 (defun ba/org-adjust-tags-column-after-save ()
1412   "Revert left-adjusted tag position done by before-save hook."
1413   (ba/org-adjust-tags-column-maybe)
1414   (set-buffer-modified-p nil))
1415
1416 ; automatically align tags on right-hand side
1417 (add-hook 'window-configuration-change-hook
1418           'ba/org-adjust-tags-column-maybe)
1419 (add-hook 'before-save-hook 'ba/org-adjust-tags-column-before-save)
1420 (add-hook 'after-save-hook 'ba/org-adjust-tags-column-after-save)
1421 (add-hook 'org-agenda-mode-hook '(lambda ()
1422                                   (setq org-agenda-tags-column (- (window-width)))))
1423
1424 ; between invoking org-refile and displaying the prompt (which
1425 ; triggers window-configuration-change-hook) tags might adjust,
1426 ; which invalidates the org-refile cache
1427 (defadvice org-refile (around org-refile-disable-adjust-tags)
1428   "Disable dynamically adjusting tags"
1429   (let ((ba/org-adjust-tags-column nil))
1430     ad-do-it))
1431 (ad-activate 'org-refile)
1432 #+end_src
1433 *** Use an "attach" link type to open files without worrying about their location
1434 #+index: Link!Attach
1435 -- Darlan Cavalcante Moreira
1436
1437 In the setup part in my org-files I put:
1438
1439 #+begin_src org
1440   ,#+LINK: attach elisp:(org-open-file (org-attach-expand "%s"))
1441 #+end_src org
1442
1443 Now I can use the "attach" link type, but org will ask me if I want to
1444 allow executing the elisp code.  To avoid this you can even set
1445 org-confirm-elisp-link-function to nil (I don't like this because it allows
1446 any elisp code in links) or you can set org-confirm-elisp-link-not-regexp
1447 appropriately.
1448
1449 In my case I use
1450
1451 : (setq org-confirm-elisp-link-not-regexp "org-open-file")
1452
1453 This works very well.
1454
1455 ** Org Agenda and Task Management
1456 *** Make it easier to set org-agenda-files from multiple directories
1457 #+index: Agenda!Files
1458 - Matt Lundin
1459
1460 #+begin_src emacs-lisp
1461 (defun my-org-list-files (dirs ext)
1462   "Function to create list of org files in multiple subdirectories.
1463 This can be called to generate a list of files for
1464 org-agenda-files or org-refile-targets.
1465
1466 DIRS is a list of directories.
1467
1468 EXT is a list of the extensions of files to be included."
1469   (let ((dirs (if (listp dirs)
1470                   dirs
1471                 (list dirs)))
1472         (ext (if (listp ext)
1473                  ext
1474                (list ext)))
1475         files)
1476     (mapc
1477      (lambda (x)
1478        (mapc
1479         (lambda (y)
1480           (setq files
1481                 (append files
1482                         (file-expand-wildcards
1483                          (concat (file-name-as-directory x) "*" y)))))
1484         ext))
1485      dirs)
1486     (mapc
1487      (lambda (x)
1488        (when (or (string-match "/.#" x)
1489                  (string-match "#$" x))
1490          (setq files (delete x files))))
1491      files)
1492     files))
1493
1494 (defvar my-org-agenda-directories '("~/org/")
1495   "List of directories containing org files.")
1496 (defvar my-org-agenda-extensions '(".org")
1497   "List of extensions of agenda files")
1498
1499 (setq my-org-agenda-directories '("~/org/" "~/work/"))
1500 (setq my-org-agenda-extensions '(".org" ".ref"))
1501
1502 (defun my-org-set-agenda-files ()
1503   (interactive)
1504   (setq org-agenda-files (my-org-list-files
1505                           my-org-agenda-directories
1506                           my-org-agenda-extensions)))
1507
1508 (my-org-set-agenda-files)
1509 #+end_src
1510
1511 The code above will set your "default" agenda files to all files
1512 ending in ".org" and ".ref" in the directories "~/org/" and "~/work/".
1513 You can change these values by setting the variables
1514 my-org-agenda-extensions and my-org-agenda-directories. The function
1515 my-org-agenda-files-by-filetag uses these two variables to determine
1516 which files to search for filetags (i.e., the larger set from which
1517 the subset will be drawn).
1518
1519 You can also easily use my-org-list-files to "mix and match"
1520 directories and extensions to generate different lists of agenda
1521 files.
1522
1523 *** Restrict org-agenda-files by filetag
1524 #+index: Agenda!Files
1525   :PROPERTIES:
1526   :CUSTOM_ID: set-agenda-files-by-filetag
1527   :END:
1528 - Matt Lundin
1529
1530 It is often helpful to limit yourself to a subset of your agenda
1531 files. For instance, at work, you might want to see only files related
1532 to work (e.g., bugs, clientA, projectxyz, etc.). The FAQ has helpful
1533 information on filtering tasks using [[file:org-faq.org::#limit-agenda-with-tag-filtering][filetags]] and [[file:org-faq.org::#limit-agenda-with-category-match][custom agenda
1534 commands]]. These solutions, however, require reapplying a filter each
1535 time you call the agenda or writing several new custom agenda commands
1536 for each context. Another solution is to use directories for different
1537 types of tasks and to change your agenda files with a function that
1538 sets org-agenda-files to the appropriate directory. But this relies on
1539 hard and static boundaries between files.
1540
1541 The following functions allow for a more dynamic approach to selecting
1542 a subset of files based on filetags:
1543
1544 #+begin_src emacs-lisp
1545 (defun my-org-agenda-restrict-files-by-filetag (&optional tag)
1546   "Restrict org agenda files only to those containing filetag."
1547   (interactive)
1548   (let* ((tagslist (my-org-get-all-filetags))
1549          (ftag (or tag
1550                    (completing-read "Tag: "
1551                                     (mapcar 'car tagslist)))))
1552     (org-agenda-remove-restriction-lock 'noupdate)
1553     (put 'org-agenda-files 'org-restrict (cdr (assoc ftag tagslist)))
1554     (setq org-agenda-overriding-restriction 'files)))
1555
1556 (defun my-org-get-all-filetags ()
1557   "Get list of filetags from all default org-files."
1558   (let ((files org-agenda-files)
1559         tagslist x)
1560     (save-window-excursion
1561       (while (setq x (pop files))
1562         (set-buffer (find-file-noselect x))
1563         (mapc
1564          (lambda (y)
1565            (let ((tagfiles (assoc y tagslist)))
1566              (if tagfiles
1567                  (setcdr tagfiles (cons x (cdr tagfiles)))
1568                (add-to-list 'tagslist (list y x)))))
1569          (my-org-get-filetags)))
1570       tagslist)))
1571
1572 (defun my-org-get-filetags ()
1573   "Get list of filetags for current buffer"
1574   (let ((ftags org-file-tags)
1575         x)
1576     (mapcar
1577      (lambda (x)
1578        (org-substring-no-properties x))
1579      ftags)))
1580 #+end_src
1581
1582 Calling my-org-agenda-restrict-files-by-filetag results in a prompt
1583 with all filetags in your "normal" agenda files. When you select a
1584 tag, org-agenda-files will be restricted to only those files
1585 containing the filetag. To release the restriction, type C-c C-x >
1586 (org-agenda-remove-restriction-lock).
1587
1588 *** Highlight the agenda line under cursor
1589 #+index: Agenda!Highlight
1590 This is useful to make sure what task you are operating on.
1591
1592 #+BEGIN_SRC emacs-lisp
1593 (add-hook 'org-agenda-mode-hook '(lambda () (hl-line-mode 1)))
1594 #+END_SRC
1595
1596 Under XEmacs:
1597
1598 #+BEGIN_SRC emacs-lisp
1599 ;; hl-line seems to be only for emacs
1600 (require 'highline)
1601 (add-hook 'org-agenda-mode-hook '(lambda () (highline-mode 1)))
1602
1603 ;; highline-mode does not work straightaway in tty mode.
1604 ;; I use a black background
1605 (custom-set-faces
1606   '(highline-face ((((type tty) (class color))
1607                     (:background "white" :foreground "black")))))
1608 #+END_SRC
1609
1610 *** Split frame horizontally for agenda
1611 #+index: Agenda!frame
1612 If you would like to split the frame into two side-by-side windows when
1613 displaying the agenda, try this hack from Jan Rehders, which uses the
1614 `toggle-window-split' from
1615
1616 http://www.emacswiki.org/cgi-bin/wiki/ToggleWindowSplit
1617
1618 #+BEGIN_SRC emacs-lisp
1619 ;; Patch org-mode to use vertical splitting
1620 (defadvice org-prepare-agenda (after org-fix-split)
1621   (toggle-window-split))
1622 (ad-activate 'org-prepare-agenda)
1623 #+END_SRC
1624
1625 *** Automatically add an appointment when clocking in a task
1626 #+index: Clock!Automatically add an appointment when clocking in a task
1627 #+index: Appointment!Automatically add an appointment when clocking in a task
1628 #+BEGIN_SRC emacs-lisp
1629 ;; Make sure you have a sensible value for `appt-message-warning-time'
1630 (defvar bzg-org-clock-in-appt-delay 100
1631   "Number of minutes for setting an appointment by clocking-in")
1632 #+END_SRC
1633
1634 This function let's you add an appointment for the current entry.
1635 This can be useful when you need a reminder.
1636
1637 #+BEGIN_SRC emacs-lisp
1638 (defun bzg-org-clock-in-add-appt (&optional n)
1639   "Add an appointment for the Org entry at point in N minutes."
1640   (interactive)
1641   (save-excursion
1642     (org-back-to-heading t)
1643     (looking-at org-complex-heading-regexp)
1644     (let* ((msg (match-string-no-properties 4))
1645            (ct-time (decode-time))
1646            (appt-min (+ (cadr ct-time)
1647                         (or n bzg-org-clock-in-appt-delay)))
1648            (appt-time ; define the time for the appointment
1649             (progn (setf (cadr ct-time) appt-min) ct-time)))
1650       (appt-add (format-time-string
1651                  "%H:%M" (apply 'encode-time appt-time)) msg)
1652       (if (interactive-p) (message "New appointment for %s" msg)))))
1653 #+END_SRC
1654
1655 You can advise =org-clock-in= so that =C-c C-x C-i= will automatically
1656 add an appointment:
1657
1658 #+BEGIN_SRC emacs-lisp
1659 (defadvice org-clock-in (after org-clock-in-add-appt activate)
1660   "Add an appointment when clocking a task in."
1661   (bzg-org-clock-in-add-appt))
1662 #+END_SRC
1663
1664 You may also want to delete the associated appointment when clocking
1665 out.  This function does this:
1666
1667 #+BEGIN_SRC emacs-lisp
1668 (defun bzg-org-clock-out-delete-appt nil
1669   "When clocking out, delete any associated appointment."
1670   (interactive)
1671   (save-excursion
1672     (org-back-to-heading t)
1673     (looking-at org-complex-heading-regexp)
1674     (let* ((msg (match-string-no-properties 4)))
1675       (setq appt-time-msg-list
1676             (delete nil
1677                     (mapcar
1678                      (lambda (appt)
1679                        (if (not (string-match (regexp-quote msg)
1680                                               (cadr appt))) appt))
1681                      appt-time-msg-list)))
1682       (appt-check))))
1683 #+END_SRC
1684
1685 And here is the advice for =org-clock-out= (=C-c C-x C-o=)
1686
1687 #+BEGIN_SRC emacs-lisp
1688 (defadvice org-clock-out (before org-clock-out-delete-appt activate)
1689   "Delete an appointment when clocking a task out."
1690   (bzg-org-clock-out-delete-appt))
1691 #+END_SRC
1692
1693 *IMPORTANT*: You can add appointment by clocking in in both an
1694 =org-mode= and an =org-agenda-mode= buffer.  But clocking out from
1695 agenda buffer with the advice above will bring an error.
1696
1697 *** Using external programs for appointments reminders
1698 #+index: Appointment!reminders
1699 Read this rich [[http://comments.gmane.org/gmane.emacs.orgmode/46641][thread]] from the org-mode list.
1700
1701 *** Remove from agenda time grid lines that are in an appointment
1702 #+index: Agenda!time grid
1703 #+index: Appointment!Remove from agenda time grid lines
1704 The agenda shows lines for the time grid.  Some people think that
1705 these lines are a distraction when there are appointments at those
1706 times.  You can get rid of the lines which coincide exactly with the
1707 beginning of an appointment.  Michael Ekstrand has written a piece of
1708 advice that also removes lines that are somewhere inside an
1709 appointment:
1710
1711 #+begin_src emacs-lisp
1712 (defun org-time-to-minutes (time)
1713   "Convert an HHMM time to minutes"
1714   (+ (* (/ time 100) 60) (% time 100)))
1715
1716 (defun org-time-from-minutes (minutes)
1717   "Convert a number of minutes to an HHMM time"
1718   (+ (* (/ minutes 60) 100) (% minutes 60)))
1719
1720 (defadvice org-agenda-add-time-grid-maybe (around mde-org-agenda-grid-tweakify
1721                                                   (list ndays todayp))
1722   (if (member 'remove-match (car org-agenda-time-grid))
1723       (flet ((extract-window
1724               (line)
1725               (let ((start (get-text-property 1 'time-of-day line))
1726                     (dur (get-text-property 1 'duration line)))
1727                 (cond
1728                  ((and start dur)
1729                   (cons start
1730                         (org-time-from-minutes
1731                          (+ dur (org-time-to-minutes start)))))
1732                  (start start)
1733                  (t nil)))))
1734         (let* ((windows (delq nil (mapcar 'extract-window list)))
1735                (org-agenda-time-grid
1736                 (list (car org-agenda-time-grid)
1737                       (cadr org-agenda-time-grid)
1738                       (remove-if
1739                        (lambda (time)
1740                          (find-if (lambda (w)
1741                                     (if (numberp w)
1742                                         (equal w time)
1743                                       (and (>= time (car w))
1744                                            (< time (cdr w)))))
1745                                   windows))
1746                        (caddr org-agenda-time-grid)))))
1747           ad-do-it))
1748     ad-do-it))
1749 (ad-activate 'org-agenda-add-time-grid-maybe)
1750 #+end_src
1751 *** Disable version control for Org mode agenda files
1752 #+index: Agenda!Files
1753 -- David Maus
1754
1755 Even if you use Git to track your agenda files you might not need
1756 vc-mode to be enabled for these files.
1757
1758 #+begin_src emacs-lisp
1759 (add-hook 'find-file-hook 'dmj/disable-vc-for-agenda-files-hook)
1760 (defun dmj/disable-vc-for-agenda-files-hook ()
1761   "Disable vc-mode for Org agenda files."
1762   (if (and (fboundp 'org-agenda-file-p)
1763            (org-agenda-file-p (buffer-file-name)))
1764       (remove-hook 'find-file-hook 'vc-find-file-hook)
1765     (add-hook 'find-file-hook 'vc-find-file-hook)))
1766 #+end_src
1767
1768 *** Easy customization of TODO colors
1769 #+index: Customization!Todo keywords
1770 #+index: Todo keywords!Customization
1771
1772 -- Ryan C. Thompson
1773
1774 Here is some code I came up with some code to make it easier to
1775 customize the colors of various TODO keywords. As long as you just
1776 want a different color and nothing else, you can customize the
1777 variable org-todo-keyword-faces and use just a string color (i.e. a
1778 string of the color name) as the face, and then org-get-todo-face
1779 will convert the color to a face, inheriting everything else from
1780 the standard org-todo face.
1781
1782 To demonstrate, I currently have org-todo-keyword-faces set to
1783
1784 #+BEGIN_SRC emacs-lisp
1785 (("IN PROGRESS" . "dark orange")
1786  ("WAITING" . "red4")
1787  ("CANCELED" . "saddle brown"))
1788 #+END_SRC
1789
1790   Here's the code, in a form you can put in your =.emacs=
1791
1792 #+BEGIN_SRC emacs-lisp
1793 (eval-after-load 'org-faces
1794  '(progn
1795     (defcustom org-todo-keyword-faces nil
1796       "Faces for specific TODO keywords.
1797 This is a list of cons cells, with TODO keywords in the car and
1798 faces in the cdr.  The face can be a symbol, a color, or a
1799 property list of attributes, like (:foreground \"blue\" :weight
1800 bold :underline t)."
1801       :group 'org-faces
1802       :group 'org-todo
1803       :type '(repeat
1804               (cons
1805                (string :tag "Keyword")
1806                (choice color (sexp :tag "Face")))))))
1807
1808 (eval-after-load 'org
1809  '(progn
1810     (defun org-get-todo-face-from-color (color)
1811       "Returns a specification for a face that inherits from org-todo
1812  face and has the given color as foreground. Returns nil if
1813  color is nil."
1814       (when color
1815         `(:inherit org-warning :foreground ,color)))
1816
1817     (defun org-get-todo-face (kwd)
1818       "Get the right face for a TODO keyword KWD.
1819 If KWD is a number, get the corresponding match group."
1820       (if (numberp kwd) (setq kwd (match-string kwd)))
1821       (or (let ((face (cdr (assoc kwd org-todo-keyword-faces))))
1822             (if (stringp face)
1823                 (org-get-todo-face-from-color face)
1824               face))
1825           (and (member kwd org-done-keywords) 'org-done)
1826           'org-todo))))
1827 #+END_SRC
1828
1829 *** Add an effort estimate on the fly when clocking in
1830 #+index: Effort estimate!Add when clocking in
1831 #+index: Clock!Effort estimate
1832 You can use =org-clock-in-prepare-hook= to add an effort estimate.
1833 This way you can easily have a "tea-timer" for your tasks when they
1834 don't already have an effort estimate.
1835
1836 #+begin_src emacs-lisp
1837 (add-hook 'org-clock-in-prepare-hook
1838           'my-org-mode-ask-effort)
1839
1840 (defun my-org-mode-ask-effort ()
1841   "Ask for an effort estimate when clocking in."
1842   (unless (org-entry-get (point) "Effort")
1843     (let ((effort
1844            (completing-read
1845             "Effort: "
1846             (org-entry-get-multivalued-property (point) "Effort"))))
1847       (unless (equal effort "")
1848         (org-set-property "Effort" effort)))))
1849 #+end_src
1850
1851 Or you can use a default effort for such a timer:
1852
1853 #+begin_src emacs-lisp
1854 (add-hook 'org-clock-in-prepare-hook
1855           'my-org-mode-add-default-effort)
1856
1857 (defvar org-clock-default-effort "1:00")
1858
1859 (defun my-org-mode-add-default-effort ()
1860   "Add a default effort estimation."
1861   (unless (org-entry-get (point) "Effort")
1862     (org-set-property "Effort" org-clock-default-effort)))
1863 #+end_src
1864
1865 *** Use idle timer for automatic agenda views
1866 #+index: Agenda view!Refresh
1867 From John Wiegley's mailing list post (March 18, 2010):
1868
1869 #+begin_quote
1870 I have the following snippet in my .emacs file, which I find very
1871 useful. Basically what it does is that if I don't touch my Emacs for 5
1872 minutes, it displays the current agenda. This keeps my tasks "always
1873 in mind" whenever I come back to Emacs after doing something else,
1874 whereas before I had a tendency to forget that it was there.
1875 #+end_quote
1876
1877   - [[http://mid.gmane.org/55590EA7-C744-44E5-909F-755F0BBE452D@gmail.com][John Wiegley: Displaying your Org agenda after idle time]]
1878
1879 #+begin_src emacs-lisp
1880 (defun jump-to-org-agenda ()
1881   (interactive)
1882   (let ((buf (get-buffer "*Org Agenda*"))
1883         wind)
1884     (if buf
1885         (if (setq wind (get-buffer-window buf))
1886             (select-window wind)
1887           (if (called-interactively-p)
1888               (progn
1889                 (select-window (display-buffer buf t t))
1890                 (org-fit-window-to-buffer)
1891                 ;; (org-agenda-redo)
1892                 )
1893             (with-selected-window (display-buffer buf)
1894               (org-fit-window-to-buffer)
1895               ;; (org-agenda-redo)
1896               )))
1897       (call-interactively 'org-agenda-list)))
1898   ;;(let ((buf (get-buffer "*Calendar*")))
1899   ;;  (unless (get-buffer-window buf)
1900   ;;    (org-agenda-goto-calendar)))
1901   )
1902
1903 (run-with-idle-timer 300 t 'jump-to-org-agenda)
1904 #+end_src
1905
1906 #+results:
1907 : [nil 0 300 0 t jump-to-org-agenda nil idle]
1908
1909 *** Refresh the agenda view regularly
1910 #+index: Agenda view!Refresh
1911 Hack sent by Kiwon Um:
1912
1913 #+begin_src emacs-lisp
1914 (defun kiwon/org-agenda-redo-in-other-window ()
1915   "Call org-agenda-redo function even in the non-agenda buffer."
1916   (interactive)
1917   (let ((agenda-window (get-buffer-window org-agenda-buffer-name t)))
1918     (when agenda-window
1919       (with-selected-window agenda-window (org-agenda-redo)))))
1920 (run-at-time nil 300 'kiwon/org-agenda-redo-in-other-window)
1921 #+end_src
1922
1923 *** Reschedule agenda items to today with a single command
1924 #+index: Agenda!Reschedule
1925 This was suggested by Carsten in reply to David Abrahams:
1926
1927 #+begin_example emacs-lisp
1928 (defun org-agenda-reschedule-to-today ()
1929   (interactive)
1930   (flet ((org-read-date (&rest rest) (current-time)))
1931     (call-interactively 'org-agenda-schedule)))
1932 #+end_example
1933
1934 *** Mark subtree DONE along with all subheadings
1935 #+index: Subtree!subheadings
1936 Bernt Hansen [[http://permalink.gmane.org/gmane.emacs.orgmode/44693][suggested]] this command:
1937
1938 #+begin_src emacs-lisp
1939 (defun bh/mark-subtree-done ()
1940   (interactive)
1941   (org-mark-subtree)
1942   (let ((limit (point)))
1943     (save-excursion
1944       (exchange-point-and-mark)
1945       (while (> (point) limit)
1946         (org-todo "DONE")
1947         (outline-previous-visible-heading 1))
1948       (org-todo "DONE"))))
1949 #+end_src
1950
1951 Then M-x bh/mark-subtree-done.
1952
1953 *** Mark heading done when all checkboxes are checked.
1954     :PROPERTIES:
1955     :CUSTOM_ID: mark-done-when-all-checkboxes-checked
1956     :END:
1957
1958 #+index: Checkbox
1959
1960 An item consists of a list with checkboxes.  When all of the
1961 checkboxes are checked, the item should be considered complete and its
1962 TODO state should be automatically changed to DONE. The code below
1963 does that. This version is slightly enhanced over the one in the
1964 mailing list (see
1965 http://thread.gmane.org/gmane.emacs.orgmode/42715/focus=42721) to
1966 reset the state back to TODO if a checkbox is unchecked.
1967
1968 Note that the code requires that a checkbox statistics cookie (the [/]
1969 or [%] thingie in the headline - see the [[http://orgmode.org/manual/Checkboxes.html#Checkboxes][Checkboxes]] section in the
1970 manual) be present in order for it to work. Note also that it is too
1971 dumb to figure out whether the item has a TODO state in the first
1972 place: if there is a statistics cookie, a TODO/DONE state will be
1973 added willy-nilly any time that the statistics cookie is changed.
1974
1975 #+begin_src emacs-lisp
1976   ;; see http://thread.gmane.org/gmane.emacs.orgmode/42715
1977   (eval-after-load 'org-list
1978     '(add-hook 'org-checkbox-statistics-hook (function ndk/checkbox-list-complete)))
1979   
1980   (defun ndk/checkbox-list-complete ()
1981     (save-excursion
1982       (org-back-to-heading t)
1983       (let ((beg (point)) end)
1984         (end-of-line)
1985         (setq end (point))
1986         (goto-char beg)
1987         (if (re-search-forward "\\[\\([0-9]*%\\)\\]\\|\\[\\([0-9]*\\)/\\([0-9]*\\)\\]" end t)
1988               (if (match-end 1)
1989                   (if (equal (match-string 1) "100%")
1990                       ;; all done - do the state change
1991                       (org-todo 'done)
1992                     (org-todo 'todo))
1993                 (if (and (> (match-end 2) (match-beginning 2))
1994                          (equal (match-string 2) (match-string 3)))
1995                     (org-todo 'done)
1996                   (org-todo 'todo)))))))
1997 #+end_src
1998
1999 *** Links to custom agenda views
2000     :PROPERTIES:
2001     :CUSTOM_ID: links-to-agenda-views
2002     :END:
2003 #+index: Agenda view!Links to
2004 This hack was [[http://lists.gnu.org/archive/html/emacs-orgmode/2012-08/msg00986.html][posted to the mailing list]] by Nathan Neff.
2005
2006 If you have custom agenda commands defined to some key, say w, then
2007 the following will serve as a link to the custom agenda buffer.
2008 : [[elisp:(org-agenda nil "w")][Show Waiting Tasks]]
2009
2010 Clicking on it will prompt if you want to execute the elisp code.  If
2011 you would rather not have the prompt or would want to respond with a
2012 single letter, ~y~ or ~n~, take a look at the docstrings of the
2013 variables =org-confirm-elisp-link-function= and
2014 =org-confirm-elisp-link-not-regexp=.  Please take special note of the
2015 security risk associated with completely disabling the prompting
2016 before you proceed.
2017
2018 ** Exporting org files
2019 *** Export Org to Org and handle includes.
2020 #+index: Export!handle includes
2021 Nick Dokos came up with this useful function:
2022
2023 #+begin_src emacs-lisp
2024 (defun org-to-org-handle-includes ()
2025   "Copy the contents of the current buffer to OUTFILE,
2026 recursively processing #+INCLUDEs."
2027   (let* ((s (buffer-string))
2028          (fname (buffer-file-name))
2029          (ofname (format "%s.I.org" (file-name-sans-extension fname))))
2030     (setq result
2031           (with-temp-buffer
2032             (insert s)
2033             (org-export-handle-include-files-recurse)
2034             (buffer-string)))
2035     (find-file ofname)
2036     (delete-region (point-min) (point-max))
2037     (insert result)
2038     (save-buffer)))
2039 #+end_src
2040
2041 *** Specifying LaTeX commands to floating environments
2042     :PROPERTIES:
2043     :CUSTOM_ID: latex-command-for-floats
2044     :END:
2045
2046 #+index: Export!LaTeX
2047 The keyword ~placement~ can be used to specify placement options to
2048 floating environments (like =\begin{figure}= and =\begin{table}=}) in
2049 LaTeX export. Org passes along everything passed in options as long as
2050 there are no spaces. One can take advantage of this to pass other
2051 LaTeX commands and have their scope limited to the floating
2052 environment.
2053
2054 For example one can set the fontsize of a table different from the
2055 default normal size by putting something like =\footnotesize= right
2056 after the placement options. During LaTeX export using the
2057 ~#+ATTR_LaTeX:~ line below:
2058
2059 #+begin_src org
2060   ,#+ATTR_LaTeX: placement=[<options>]\footnotesize
2061 #+end_src
2062
2063 exports the associated floating environment as shown in the following
2064 block.
2065
2066 #+begin_src latex
2067 \begin{table}[<options>]\footnotesize
2068 ...
2069 \end{table}
2070 #+end_src
2071
2072 It should be noted that this hack does not work for beamer export of
2073 tables since the =table= environment is not used. As an ugly
2074 workaround, one can use the following:
2075
2076 #+begin_src org
2077   ,#+LATEX: {\footnotesize
2078   ,#+ATTR_LaTeX: align=rr
2079   ,| some | table |
2080   ,|------+-------|
2081   ,| ..   | ..    |
2082   ,#+LATEX: }
2083 #+end_src
2084
2085 *** Styling code sections with CSS
2086
2087 #+index: HTML!Styling code sections with CSS
2088
2089 Code sections (marked with =#+begin_src= and =#+end_src=) are exported
2090 to HTML using =<pre>= tags, and assigned CSS classes by their content
2091 type.  For example, Perl content will have an opening tag like
2092 =<pre class="src src-perl">=.  You can use those classes to add styling
2093 to the output, such as here where a small language tag is added at the
2094 top of each kind of code box:
2095
2096 #+begin_src lisp
2097 (setq org-export-html-style
2098  "<style type=\"text/css\">
2099     <!--/*--><![CDATA[/*><!--*/
2100       .src             { background-color: #F5FFF5; position: relative; overflow: visible; }
2101       .src:before      { position: absolute; top: -15px; background: #ffffff; padding: 1px; border: 1px solid #000000; font-size: small; }
2102       .src-sh:before   { content: 'sh'; }
2103       .src-bash:before { content: 'sh'; }
2104       .src-R:before    { content: 'R'; }
2105       .src-perl:before { content: 'Perl'; }
2106       .src-sql:before  { content: 'SQL'; }
2107       .example         { background-color: #FFF5F5; }
2108     /*]]>*/-->
2109  </style>")
2110 #+end_src
2111
2112 Additionally, we use color to distinguish code output (the =.example=
2113 class) from input (all the =.src-*= classes).
2114
2115 * Hacking Org: Working with Org-mode and other Emacs Packages.
2116 ** org-remember-anything
2117
2118 #+index: Remember!Anything
2119
2120 [[http://www.emacswiki.org/cgi-bin/wiki/Anything][Anything]] users may find the snippet below interesting:
2121
2122 #+BEGIN_SRC emacs-lisp
2123 (defvar org-remember-anything
2124   '((name . "Org Remember")
2125     (candidates . (lambda () (mapcar 'car org-remember-templates)))
2126     (action . (lambda (name)
2127                 (let* ((orig-template org-remember-templates)
2128                        (org-remember-templates
2129                         (list (assoc name orig-template))))
2130                   (call-interactively 'org-remember))))))
2131 #+END_SRC
2132
2133 You can add it to your 'anything-sources' variable and open remember directly
2134 from anything. I imagine this would be more interesting for people with many
2135 remember templates, so that you are out of keys to assign those to.
2136
2137 ** Org-mode and saveplace.el
2138
2139 Fix a problem with =saveplace.el= putting you back in a folded position:
2140
2141 #+begin_src emacs-lisp
2142 (add-hook 'org-mode-hook
2143           (lambda ()
2144             (when (outline-invisible-p)
2145               (save-excursion
2146                 (outline-previous-visible-heading 1)
2147                 (org-show-subtree)))))
2148 #+end_src
2149
2150 ** Using ido-mode for org-refile (and archiving via refile)
2151
2152 First set up ido-mode, for example using:
2153
2154 #+begin_src emacs-lisp
2155 ; use ido mode for completion
2156 (setq ido-everywhere t)
2157 (setq ido-enable-flex-matching t)
2158 (setq ido-max-directory-size 100000)
2159 (ido-mode (quote both))
2160 #+end_src
2161
2162 Now to enable it in org-mode, use the following:
2163 #+begin_src emacs-lisp
2164 (setq org-completion-use-ido t)
2165 (setq org-refile-use-outline-path nil)
2166 (setq org-refile-allow-creating-parent-nodes 'confirm)
2167 #+end_src
2168 The last line enables the creation of nodes on the fly.
2169
2170 If you refile into files that are not in your agenda file list, you can add them as target like this (replace file1\_done, etc with your files):
2171 #+begin_src emacs-lisp
2172 (setq org-refile-targets '((org-agenda-files :maxlevel . 5) (("~/org/file1_done" "~/org/file2_done") :maxlevel . 5) ))
2173 #+end_src
2174
2175 For refiling it is often not useful to include targets that have a DONE state. It's easy to remove them by using the verify-refile-target hook.
2176 #+begin_src emacs-lisp
2177 ; Exclude DONE state tasks from refile targets; taken from http://doc.norang.ca/org-mode.html
2178 ; added check to only include headlines, e.g. line must have at least one child
2179 (defun my/verify-refile-target ()
2180   "Exclude todo keywords with a DONE state from refile targets"
2181   (or (not (member (nth 2 (org-heading-components)) org-done-keywords)))
2182       (save-excursion (org-goto-first-child))
2183   )
2184 (setq org-refile-target-verify-function 'my/verify-refile-target)
2185 #+end_src
2186 Now when looking for a refile target, you can use the full power of ido to find them. Ctrl-R can be used to switch between different options that ido offers.
2187
2188 ** Using ido-completing-read to find attachments
2189
2190 #+index: Attachment!ido completion
2191
2192 -- Matt Lundin.
2193
2194 Org-attach is great for quickly linking files to a project. But if you
2195 use org-attach extensively you might find yourself wanting to browse
2196 all the files you've attached to org headlines. This is not easy to do
2197 manually, since the directories containing the files are not human
2198 readable (i.e., they are based on automatically generated ids). Here's
2199 some code to browse those files using ido (obviously, you need to be
2200 using ido):
2201
2202 #+begin_src emacs-lisp
2203 (load-library "find-lisp")
2204
2205 ;; Adapted from http://www.emacswiki.org/emacs/RecentFiles
2206
2207 (defun my-ido-find-org-attach ()
2208   "Find files in org-attachment directory"
2209   (interactive)
2210   (let* ((enable-recursive-minibuffers t)
2211          (files (find-lisp-find-files org-attach-directory "."))
2212          (file-assoc-list
2213           (mapcar (lambda (x)
2214                     (cons (file-name-nondirectory x)
2215                           x))
2216                   files))
2217          (filename-list
2218           (remove-duplicates (mapcar #'car file-assoc-list)
2219                              :test #'string=))
2220          (filename (ido-completing-read "Org attachments: " filename-list nil t))
2221          (longname (cdr (assoc filename file-assoc-list))))
2222     (ido-set-current-directory
2223      (if (file-directory-p longname)
2224          longname
2225        (file-name-directory longname)))
2226     (setq ido-exit 'refresh
2227           ido-text-init ido-text
2228           ido-rotate-temp t)
2229     (exit-minibuffer)))
2230
2231 (add-hook 'ido-setup-hook 'ido-my-keys)
2232
2233 (defun ido-my-keys ()
2234   "Add my keybindings for ido."
2235   (define-key ido-completion-map (kbd "C-;") 'my-ido-find-org-attach))
2236 #+end_src
2237
2238 To browse your org attachments using ido fuzzy matching and/or the
2239 completion buffer, invoke ido-find-file as usual (=C-x C-f=) and then
2240 press =C-;=.
2241
2242 ** Link to Gnus messages by Message-Id
2243 #+index: Link!Gnus message by Message-Id
2244 In a [[http://thread.gmane.org/gmane.emacs.orgmode/8860][recent thread]] on the Org-Mode mailing list, there was some
2245 discussion about linking to Gnus messages without encoding the folder
2246 name in the link.  The following code hooks in to the store-link
2247 function in Gnus to capture links by Message-Id when in nnml folders,
2248 and then provides a link type "mid" which can open this link.  The
2249 =mde-org-gnus-open-message-link= function uses the
2250 =mde-mid-resolve-methods= variable to determine what Gnus backends to
2251 scan.  It will go through them, in order, asking each to locate the
2252 message and opening it from the first one that reports success.
2253
2254 It has only been tested with a single nnml backend, so there may be
2255 bugs lurking here and there.
2256
2257 The logic for finding the message was adapted from [[http://www.emacswiki.org/cgi-bin/wiki/FindMailByMessageId][an Emacs Wiki
2258 article]].
2259
2260 #+begin_src emacs-lisp
2261 ;; Support for saving Gnus messages by Message-ID
2262 (defun mde-org-gnus-save-by-mid ()
2263   (when (memq major-mode '(gnus-summary-mode gnus-article-mode))
2264     (when (eq major-mode 'gnus-article-mode)
2265       (gnus-article-show-summary))
2266     (let* ((group gnus-newsgroup-name)
2267            (method (gnus-find-method-for-group group)))
2268       (when (eq 'nnml (car method))
2269         (let* ((article (gnus-summary-article-number))
2270                (header (gnus-summary-article-header article))
2271                (from (mail-header-from header))
2272                (message-id
2273                 (save-match-data
2274                   (let ((mid (mail-header-id header)))
2275                     (if (string-match "<\\(.*\\)>" mid)
2276                         (match-string 1 mid)
2277                       (error "Malformed message ID header %s" mid)))))
2278                (date (mail-header-date header))
2279                (subject (gnus-summary-subject-string)))
2280           (org-store-link-props :type "mid" :from from :subject subject
2281                                 :message-id message-id :group group
2282                                 :link (org-make-link "mid:" message-id))
2283           (apply 'org-store-link-props
2284                  :description (org-email-link-description)
2285                  org-store-link-plist)
2286           t)))))
2287
2288 (defvar mde-mid-resolve-methods '()
2289   "List of methods to try when resolving message ID's.  For Gnus,
2290 it is a cons of 'gnus and the select (type and name).")
2291 (setq mde-mid-resolve-methods
2292       '((gnus nnml "")))
2293
2294 (defvar mde-org-gnus-open-level 1
2295   "Level at which Gnus is started when opening a link")
2296 (defun mde-org-gnus-open-message-link (msgid)
2297   "Open a message link with Gnus"
2298   (require 'gnus)
2299   (require 'org-table)
2300   (catch 'method-found
2301     (message "[MID linker] Resolving %s" msgid)
2302     (dolist (method mde-mid-resolve-methods)
2303       (cond
2304        ((and (eq (car method) 'gnus)
2305              (eq (cadr method) 'nnml))
2306         (funcall (cdr (assq 'gnus org-link-frame-setup))
2307                  mde-org-gnus-open-level)
2308         (when gnus-other-frame-object
2309           (select-frame gnus-other-frame-object))
2310         (let* ((msg-info (nnml-find-group-number
2311                           (concat "<" msgid ">")
2312                           (cdr method)))
2313                (group (and msg-info (car msg-info)))
2314                (message (and msg-info (cdr msg-info)))
2315                (qname (and group
2316                            (if (gnus-methods-equal-p
2317                                 (cdr method)
2318                                 gnus-select-method)
2319                                group
2320                              (gnus-group-full-name group (cdr method))))))
2321           (when msg-info
2322             (gnus-summary-read-group qname nil t)
2323             (gnus-summary-goto-article message nil t))
2324           (throw 'method-found t)))
2325        (t (error "Unknown link type"))))))
2326
2327 (eval-after-load 'org-gnus
2328   '(progn
2329      (add-to-list 'org-store-link-functions 'mde-org-gnus-save-by-mid)
2330      (org-add-link-type "mid" 'mde-org-gnus-open-message-link)))
2331 #+end_src
2332
2333 ** Store link to a message when sending in Gnus
2334 #+index: Link!Store link to a message when sending in Gnus
2335 Ulf Stegemann came up with this solution (see his [[http://www.mail-archive.com/emacs-orgmode@gnu.org/msg33278.html][original message]]):
2336
2337 #+begin_src emacs-lisp
2338 (defun ulf-message-send-and-org-gnus-store-link (&optional arg)
2339   "Send message with `message-send-and-exit' and store org link to message copy.
2340 If multiple groups appear in the Gcc header, the link refers to
2341 the copy in the last group."
2342   (interactive "P")
2343     (save-excursion
2344       (save-restriction
2345         (message-narrow-to-headers)
2346         (let ((gcc (car (last
2347                          (message-unquote-tokens
2348                           (message-tokenize-header
2349                            (mail-fetch-field "gcc" nil t) " ,")))))
2350               (buf (current-buffer))
2351               (message-kill-buffer-on-exit nil)
2352               id to from subject desc link newsgroup xarchive)
2353         (message-send-and-exit arg)
2354         (or
2355          ;; gcc group found ...
2356          (and gcc
2357               (save-current-buffer
2358                 (progn (set-buffer buf)
2359                        (setq id (org-remove-angle-brackets
2360                                  (mail-fetch-field "Message-ID")))
2361                        (setq to (mail-fetch-field "To"))
2362                        (setq from (mail-fetch-field "From"))
2363                        (setq subject (mail-fetch-field "Subject"))))
2364               (org-store-link-props :type "gnus" :from from :subject subject
2365                                     :message-id id :group gcc :to to)
2366               (setq desc (org-email-link-description))
2367               (setq link (org-gnus-article-link
2368                           gcc newsgroup id xarchive))
2369               (setq org-stored-links
2370                     (cons (list link desc) org-stored-links)))
2371          ;; no gcc group found ...
2372          (message "Can not create Org link: No Gcc header found."))))))
2373
2374 (define-key message-mode-map [(control c) (control meta c)]
2375   'ulf-message-send-and-org-gnus-store-link)
2376 #+end_src
2377
2378 ** Send html messages and attachments with Wanderlust
2379   -- David Maus
2380
2381 /Note/: The module [[file:org-contrib/org-mime.org][Org-mime]] in Org's contrib directory provides
2382 similar functionality for both Wanderlust and Gnus.  The hack below is
2383 still somewhat different: It allows you to toggle sending of html
2384 messages within Wanderlust transparently.  I.e. html markup of the
2385 message body is created right before sending starts.
2386
2387 *** Send HTML message
2388
2389 Putting the code below in your .emacs adds following four functions:
2390
2391 - dmj/wl-send-html-message
2392
2393   Function that does the job: Convert everything between "--text
2394   follows this line--" and first mime entity (read: attachment) or
2395   end of buffer into html markup using `org-export-region-as-html'
2396   and replaces original body with a multipart MIME entity with the
2397   plain text version of body and the html markup version.  Thus a
2398   recipient that prefers html messages can see the html markup,
2399   recipients that prefer or depend on plain text can see the plain
2400   text.
2401
2402   Cannot be called interactively: It is hooked into SEMI's
2403   `mime-edit-translate-hook' if message should be HTML message.
2404
2405 - dmj/wl-send-html-message-draft-init
2406
2407   Cannot be called interactively: It is hooked into WL's
2408   `wl-mail-setup-hook' and provides a buffer local variable to
2409   toggle.
2410
2411 - dmj/wl-send-html-message-draft-maybe
2412
2413   Cannot be called interactively: It is hooked into WL's
2414   `wl-draft-send-hook' and hooks `dmj/wl-send-html-message' into
2415   `mime-edit-translate-hook' depending on whether HTML message is
2416   toggled on or off
2417
2418 - dmj/wl-send-html-message-toggle
2419
2420   Toggles sending of HTML message.  If toggled on, the letters
2421   "HTML" appear in the mode line.
2422
2423   Call it interactively!  Or bind it to a key in `wl-draft-mode'.
2424
2425 If you have to send HTML messages regularly you can set a global
2426 variable `dmj/wl-send-html-message-toggled-p' to the string "HTML" to
2427 toggle on sending HTML message by default.
2428
2429 The image [[http://s11.directupload.net/file/u/15851/48ru5wl3.png][here]] shows an example of how the HTML message looks like in
2430 Google's web front end.  As you can see you have the whole markup of
2431 Org at your service: *bold*, /italics/, tables, lists...
2432
2433 So even if you feel uncomfortable with sending HTML messages at least
2434 you send HTML that looks quite good.
2435
2436 #+begin_src emacs-lisp
2437 (defun dmj/wl-send-html-message ()
2438   "Send message as html message.
2439 Convert body of message to html using
2440   `org-export-region-as-html'."
2441   (require 'org)
2442   (save-excursion
2443     (let (beg end html text)
2444       (goto-char (point-min))
2445       (re-search-forward "^--text follows this line--$")
2446       ;; move to beginning of next line
2447       (beginning-of-line 2)
2448       (setq beg (point))
2449       (if (not (re-search-forward "^--\\[\\[" nil t))
2450           (setq end (point-max))
2451         ;; line up
2452         (end-of-line 0)
2453         (setq end (point)))
2454       ;; grab body
2455       (setq text (buffer-substring-no-properties beg end))
2456       ;; convert to html
2457       (with-temp-buffer
2458         (org-mode)
2459         (insert text)
2460         ;; handle signature
2461         (when (re-search-backward "^-- \n" nil t)
2462           ;; preserve link breaks in signature
2463           (insert "\n#+BEGIN_VERSE\n")
2464           (goto-char (point-max))
2465           (insert "\n#+END_VERSE\n")
2466           ;; grab html
2467           (setq html (org-export-region-as-html
2468                       (point-min) (point-max) t 'string))))
2469       (delete-region beg end)
2470       (insert
2471        (concat
2472         "--" "<<alternative>>-{\n"
2473         "--" "[[text/plain]]\n" text
2474         "--" "[[text/html]]\n"  html
2475         "--" "}-<<alternative>>\n")))))
2476
2477 (defun dmj/wl-send-html-message-toggle ()
2478   "Toggle sending of html message."
2479   (interactive)
2480   (setq dmj/wl-send-html-message-toggled-p
2481         (if dmj/wl-send-html-message-toggled-p
2482             nil "HTML"))
2483   (message "Sending html message toggled %s"
2484            (if dmj/wl-send-html-message-toggled-p
2485                "on" "off")))
2486
2487 (defun dmj/wl-send-html-message-draft-init ()
2488   "Create buffer local settings for maybe sending html message."
2489   (unless (boundp 'dmj/wl-send-html-message-toggled-p)
2490     (setq dmj/wl-send-html-message-toggled-p nil))
2491   (make-variable-buffer-local 'dmj/wl-send-html-message-toggled-p)
2492   (add-to-list 'global-mode-string
2493                '(:eval (if (eq major-mode 'wl-draft-mode)
2494                            dmj/wl-send-html-message-toggled-p))))
2495
2496 (defun dmj/wl-send-html-message-maybe ()
2497   "Maybe send this message as html message.
2498
2499 If buffer local variable `dmj/wl-send-html-message-toggled-p' is
2500 non-nil, add `dmj/wl-send-html-message' to
2501 `mime-edit-translate-hook'."
2502   (if dmj/wl-send-html-message-toggled-p
2503       (add-hook 'mime-edit-translate-hook 'dmj/wl-send-html-message)
2504     (remove-hook 'mime-edit-translate-hook 'dmj/wl-send-html-message)))
2505
2506 (add-hook 'wl-draft-reedit-hook 'dmj/wl-send-html-message-draft-init)
2507 (add-hook 'wl-mail-setup-hook 'dmj/wl-send-html-message-draft-init)
2508 (add-hook 'wl-draft-send-hook 'dmj/wl-send-html-message-maybe)
2509 #+end_src
2510
2511 *** Attach HTML of region or subtree
2512
2513 Instead of sending a complete HTML message you might only send parts
2514 of an Org file as HTML for the poor souls who are plagued with
2515 non-proportional fonts in their mail program that messes up pretty
2516 ASCII tables.
2517
2518 This short function does the trick: It exports region or subtree to
2519 HTML, prefixes it with a MIME entity delimiter and pushes to killring
2520 and clipboard.  If a region is active, it uses the region, the
2521 complete subtree otherwise.
2522
2523 #+begin_src emacs-lisp
2524 (defun dmj/org-export-region-as-html-attachment (beg end arg)
2525   "Export region between BEG and END as html attachment.
2526 If BEG and END are not set, use current subtree.  Region or
2527 subtree is exported to html without header and footer, prefixed
2528 with a mime entity string and pushed to clipboard and killring.
2529 When called with prefix, mime entity is not marked as
2530 attachment."
2531   (interactive "r\nP")
2532   (save-excursion
2533     (let* ((beg (if (region-active-p) (region-beginning)
2534                   (progn
2535                     (org-back-to-heading)
2536                     (point))))
2537            (end (if (region-active-p) (region-end)
2538                   (progn
2539                     (org-end-of-subtree)
2540                     (point))))
2541            (html (concat "--[[text/html"
2542                          (if arg "" "\nContent-Disposition: attachment")
2543                          "]]\n"
2544                          (org-export-region-as-html beg end t 'string))))
2545       (when (fboundp 'x-set-selection)
2546         (ignore-errors (x-set-selection 'PRIMARY html))
2547         (ignore-errors (x-set-selection 'CLIPBOARD html)))
2548       (message "html export done, pushed to kill ring and clipboard"))))
2549 #+end_src
2550
2551 *** Adopting for Gnus
2552
2553 The whole magic lies in the special strings that mark a HTML
2554 attachment.  So you might just have to find out what these special
2555 strings are in message-mode and modify the functions accordingly.
2556 ** Add sunrise/sunset times to the agenda.
2557 #+index: Agenda!Diary s-expressions
2558   -- Nick Dokos
2559
2560 The diary package provides the function =diary-sunrise-sunset= which can be used
2561 in a diary s-expression in some agenda file like this:
2562
2563 #+begin_src org-mode
2564 %%(diary-sunrise-sunset)
2565 #+end_src
2566
2567 Seb Vauban asked if it is possible to put sunrise and sunset in
2568 separate lines. Here is a hack to do that. It adds two functions (they
2569 have to be available before the agenda is shown, so I add them early
2570 in my org-config file which is sourced from .emacs, but you'll have to
2571 suit yourself here) that just parse the output of
2572 diary-sunrise-sunset, instead of doing the right thing which would be
2573 to take advantage of the data structures that diary/solar.el provides.
2574 In short, a hack - so perfectly suited for inclusion here :-)
2575
2576 The functions (and latitude/longitude settings which you have to modify for
2577 your location) are as follows:
2578
2579 #+begin_src emacs-lisp
2580 (setq calendar-latitude 48.2)
2581 (setq calendar-longitude 16.4)
2582 (setq calendar-location-name "Vienna, Austria")
2583
2584 (autoload 'solar-sunrise-sunset "solar.el")
2585 (autoload 'solar-time-string "solar.el")
2586 (defun diary-sunrise ()
2587   "Local time of sunrise as a diary entry.
2588 The diary entry can contain `%s' which will be replaced with
2589 `calendar-location-name'."
2590   (let ((l (solar-sunrise-sunset date)))
2591     (when (car l)
2592       (concat
2593        (if (string= entry "")
2594            "Sunrise"
2595          (format entry (eval calendar-location-name))) " "
2596          (solar-time-string (caar l) nil)))))
2597
2598 (defun diary-sunset ()
2599   "Local time of sunset as a diary entry.
2600 The diary entry can contain `%s' which will be replaced with
2601 `calendar-location-name'."
2602   (let ((l (solar-sunrise-sunset date)))
2603     (when (cadr l)
2604       (concat
2605        (if (string= entry "")
2606            "Sunset"
2607          (format entry (eval calendar-location-name))) " "
2608          (solar-time-string (caadr l) nil)))))
2609 #+end_src
2610
2611 You also need to add a couple of diary s-expressions in one of your agenda
2612 files:
2613
2614 #+begin_src org-mode
2615 %%(diary-sunrise)Sunrise in %s
2616 %%(diary-sunset)
2617 #+end_src
2618
2619 This will show sunrise with the location and sunset without it.
2620
2621 The thread on the mailing list that started this can be found [[http://thread.gmane.org/gmane.emacs.orgmode/38723Here%20is%20a%20pointer%20to%20the%20thread%20on%20the%20mailing%20list][here]].
2622 In comparison to the version posted on the mailing list, this one
2623 gets rid of the timezone information and can show the location.
2624 ** Add lunar phases to the agenda.
2625 #+index: Agenda!Diary s-expressions
2626    -- Rüdiger
2627
2628 Emacs comes with =lunar.el= to display the lunar phases (=M-x lunar-phases=).
2629 This can be used to display lunar phases in the agenda display with the
2630 following function:
2631
2632 #+begin_src emacs-lisp
2633 (require 'cl-lib)
2634
2635 (org-no-warnings (defvar date))
2636 (defun org-lunar-phases ()
2637   "Show lunar phase in Agenda buffer."
2638   (require 'lunar)
2639   (let* ((phase-list (lunar-phase-list (nth 0 date) (nth 2 date)))
2640          (phase (cl-find-if (lambda (phase) (equal (car phase) date))
2641                             phase-list)))
2642     (when phase
2643       (setq ret (concat (lunar-phase-name (nth 2 phase)) " "
2644                         (substring (nth 1 phase) 0 5))))))
2645 #+end_src
2646
2647 Add the following line to an agenda file:
2648
2649 #+begin_src org-mode
2650 * Lunar phase
2651 #+CATEGORY: Lunar
2652 %%(org-lunar-phases)
2653 #+end_src
2654
2655 This should display an entry on new moon, first/last quarter moon, and on full
2656 moon.  You can customize the entries by customizing =lunar-phase-names=.
2657
2658 E.g., to add Unicode symbols:
2659
2660 #+begin_src emacs-lisp
2661 (setq lunar-phase-names
2662       '("● New Moon" ; Unicode symbol: 🌑 Use full circle as fallback
2663         "☽ First Quarter Moon"
2664         "○ Full Moon" ; Unicode symbol: 🌕 Use empty circle as fallback
2665         "☾ Last Quarter Moon"))
2666 #+end_src
2667
2668 Unicode 6 even provides symbols for the Moon with nice faces.  But those
2669 symbols are currently barely supported in fonts.
2670 See [[https://en.wikipedia.org/wiki/Astronomical_symbols#Moon][Astronomical symbols on Wikipedia]].
2671
2672 ** Export BBDB contacts to org-contacts.el
2673 #+index: Address Book!BBDB to org-contacts
2674 Try this tool by Wes Hardaker:
2675
2676 http://www.hardakers.net/code/bbdb-to-org-contacts/
2677
2678 ** Calculating date differences - how to write a simple elisp function
2679 #+index: Timestamp!date calculations
2680 #+index: Elisp!technique
2681
2682 Alexander Wingård asked how to calculate the number of days between a
2683 time stamp in his org file and today (see
2684 http://thread.gmane.org/gmane.emacs.orgmode/46881).  Although the
2685 resulting answer is probably not of general interest, the method might
2686 be useful to a budding Elisp programmer.
2687
2688 Alexander started from an already existing org function,
2689 =org-evaluate-time-range=.  When this function is called in the context
2690 of a time range (two time stamps separated by "=--="), it calculates the
2691 number of days between the two dates and outputs the result in Emacs's
2692 echo area. What he wanted was a similar function that, when called from
2693 the context of a single time stamp, would calculate the number of days
2694 between the date in the time stamp and today. The result should go to
2695 the same place: Emacs's echo area.
2696
2697 The solution presented in the mail thread is as follows:
2698
2699 #+begin_src emacs-lisp
2700 (defun aw/org-evaluate-time-range (&optional to-buffer)
2701   (interactive)
2702   (if (org-at-date-range-p t)
2703       (org-evaluate-time-range to-buffer)
2704     ;; otherwise, make a time range in a temp buffer and run o-e-t-r there
2705     (let ((headline (buffer-substring (point-at-bol) (point-at-eol))))
2706       (with-temp-buffer
2707         (insert headline)
2708         (goto-char (point-at-bol))
2709         (re-search-forward org-ts-regexp (point-at-eol) t)
2710         (if (not (org-at-timestamp-p t))
2711             (error "No timestamp here"))
2712         (goto-char (match-beginning 0))
2713         (org-insert-time-stamp (current-time) nil nil)
2714         (insert "--")
2715         (org-evaluate-time-range to-buffer)))))
2716 #+end_src
2717
2718 The function assumes that point is on some line with some time stamp
2719 (or a date range) in it. Note that =org-evaluate-time-range= does not care
2720 whether the first date is earlier than the second: it will always output
2721 the number of days between the earlier date and the later date.
2722
2723 As stated before, the function itself is of limited interest (although
2724 it satisfied Alexander's need).The *method* used might be of wider
2725 interest however, so here is a short explanation.
2726
2727 The idea is that we want =org-evaluate-time-range= to do all the
2728 heavy lifting, but that function requires that it be in a date-range
2729 context. So the function first checks whether it's in a date range
2730 context already: if so, it calls =org-evaluate-time-range= directly
2731 to do the work. The trick now is to arrange things so we can call this
2732 same function in the case where we do *not* have a date range
2733 context. In that case, we manufacture one: we create a temporary
2734 buffer, copy the line with the purported time stamp to the temp
2735 buffer, find the time stamp (signal an error if no time stamp is
2736 found) and insert a new time stamp with the current time before the
2737 existing time stamp, followed by "=--=": voilà, we now have a time range
2738 on which we can apply our old friend =org-evaluate-time-range= to
2739 produce the answer. Because of the above-mentioned property
2740 of =org-evaluate-time-range=, it does not matter if the existing
2741 time stamp is earlier or later than the current time: the correct
2742 number of days is output.
2743
2744 Note that at the end of the call to =with-temp-buffer=, the temporary
2745 buffer goes away.  It was just used as a scratch pad for the function
2746 to do some figuring.
2747
2748 The idea of using a temp buffer as a scratch pad has wide
2749 applicability in Emacs programming. The rest of the work is knowing
2750 enough about facilities provided by Emacs (e.g. regexp searching) and
2751 by Org (e.g. checking for time stamps and generating a time stamp) so
2752 that you don't reinvent the wheel, and impedance-matching between the
2753 various pieces.
2754
2755 ** ibuffer and org files
2756
2757 Neil Smithline posted this snippet to let you browse org files with
2758 =ibuffer=:
2759
2760 #+BEGIN_SRC emacs-lisp
2761 (require 'ibuffer)
2762
2763 (defun org-ibuffer ()
2764   "Open an `ibuffer' window showing only `org-mode' buffers."
2765   (interactive)
2766   (ibuffer nil "*Org Buffers*" '((used-mode . org-mode))))
2767 #+END_SRC
2768
2769 ** Enable org-mode links in other modes
2770
2771 Sean O'Halpin wrote a minor mode for this, please check it [[https://github.com/seanohalpin/org-link-minor-mode][here]].
2772
2773 See the relevant discussion [[http://thread.gmane.org/gmane.emacs.orgmode/58715/focus%3D58794][here]].
2774
2775 ** poporg.el: edit comments in org-mode
2776
2777 [[https://github.com/pinard/PopOrg/blob/master/poporg.el][poporg.el]] is a library by François Pinard which lets you edit comments
2778 from your code using a separate org-mode buffer.
2779
2780 * Hacking Org: Working with Org-mode and External Programs.
2781 ** Use Org-mode with Screen [Andrew Hyatt]
2782 #+index: Link!to screen session
2783 "The general idea is that you start a task in which all the work will
2784 take place in a shell.  This usually is not a leaf-task for me, but
2785 usually the parent of a leaf task.  From a task in your org-file, M-x
2786 ash-org-screen will prompt for the name of a session.  Give it a name,
2787 and it will insert a link.  Open the link at any time to go the screen
2788 session containing your work!"
2789
2790 http://article.gmane.org/gmane.emacs.orgmode/5276
2791
2792 #+BEGIN_SRC emacs-lisp
2793 (require 'term)
2794
2795 (defun ash-org-goto-screen (name)
2796   "Open the screen with the specified name in the window"
2797   (interactive "MScreen name: ")
2798   (let ((screen-buffer-name (ash-org-screen-buffer-name name)))
2799     (if (member screen-buffer-name
2800                 (mapcar 'buffer-name (buffer-list)))
2801         (switch-to-buffer screen-buffer-name)
2802       (switch-to-buffer (ash-org-screen-helper name "-dr")))))
2803
2804 (defun ash-org-screen-buffer-name (name)
2805   "Returns the buffer name corresponding to the screen name given."
2806   (concat "*screen " name "*"))
2807
2808 (defun ash-org-screen-helper (name arg)
2809   ;; Pick the name of the new buffer.
2810   (let ((term-ansi-buffer-name
2811          (generate-new-buffer-name
2812           (ash-org-screen-buffer-name name))))
2813     (setq term-ansi-buffer-name
2814           (term-ansi-make-term
2815            term-ansi-buffer-name "/usr/bin/screen" nil arg name))
2816     (set-buffer term-ansi-buffer-name)
2817     (term-mode)
2818     (term-char-mode)
2819     (term-set-escape-char ?\C-x)
2820     term-ansi-buffer-name))
2821
2822 (defun ash-org-screen (name)
2823   "Start a screen session with name"
2824   (interactive "MScreen name: ")
2825   (save-excursion
2826     (ash-org-screen-helper name "-S"))
2827   (insert-string (concat "[[screen:" name "]]")))
2828
2829 ;; And don't forget to add ("screen" . "elisp:(ash-org-goto-screen
2830 ;; \"%s\")") to org-link-abbrev-alist.
2831 #+END_SRC
2832
2833 ** Org Agenda + Appt + Zenity
2834     :PROPERTIES:
2835     :CUSTOM_ID: org-agenda-appt-zenity
2836     :END:
2837
2838 #+index: Appointment!reminders
2839 #+index: Appt!Zenity
2840 #+BEGIN_HTML
2841 <a name="agenda-appt-zenity"></a>
2842 #+END_HTML
2843 Russell Adams posted this setup [[http://article.gmane.org/gmane.emacs.orgmode/5806][on the list]].  It makes sure your agenda
2844 appointments are known by Emacs, and it displays warnings in a [[http://live.gnome.org/Zenity][zenity]]
2845 popup window.
2846
2847 #+BEGIN_SRC emacs-lisp
2848 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2849 ; For org appointment reminders
2850
2851 ;; Get appointments for today
2852 (defun my-org-agenda-to-appt ()
2853   (interactive)
2854   (setq appt-time-msg-list nil)
2855   (let ((org-deadline-warning-days 0))    ;; will be automatic in org 5.23
2856         (org-agenda-to-appt)))
2857
2858 ;; Run once, activate and schedule refresh
2859 (my-org-agenda-to-appt)
2860 (appt-activate t)
2861 (run-at-time "24:01" nil 'my-org-agenda-to-appt)
2862
2863 ; 5 minute warnings
2864 (setq appt-message-warning-time 15)
2865 (setq appt-display-interval 5)
2866
2867 ; Update appt each time agenda opened.
2868 (add-hook 'org-finalize-agenda-hook 'my-org-agenda-to-appt)
2869
2870 ; Setup zenify, we tell appt to use window, and replace default function
2871 (setq appt-display-format 'window)
2872 (setq appt-disp-window-function (function my-appt-disp-window))
2873
2874 (defun my-appt-disp-window (min-to-app new-time msg)
2875   (save-window-excursion (shell-command (concat
2876     "/usr/bin/zenity --info --title='Appointment' --text='"
2877     msg "' &") nil nil)))
2878 #+END_SRC
2879
2880 ** Org and appointment notifications on Mac OS 10.8
2881
2882 Sarah Bagby [[http://mid.gmane.org/EA76104A-9ACD-4141-8D33-2E4D810D9B5A%2540geol.ucsb.edu][posted some code]] on how to get appointments notifications on
2883 Mac OS 10.8 with [[https://github.com/alloy/terminal-notifier][terminal-notifier]].
2884
2885 ** Org-Mode + gnome-osd
2886 #+index: Appointment!reminders
2887 #+index: Appt!gnome-osd
2888 Richard Riley uses gnome-osd in interaction with Org-Mode to display
2889 appointments.  You can look at the code on the [[http://www.emacswiki.org/emacs-en/OrgMode-OSD][emacswiki]].
2890
2891 ** txt2org convert text data to org-mode tables
2892 From Eric Schulte
2893
2894 I often find it useful to generate Org-mode tables on the command line
2895 from tab-separated data.  The following awk script makes this easy to
2896 do.  Text data is read from STDIN on a pipe and any command line
2897 arguments are interpreted as rows at which to insert hlines.
2898
2899 Here are two usage examples.
2900 1. running the following
2901    : $ cat <<EOF|~/src/config/bin/txt2org
2902    : one 1
2903    : two 2
2904    : three 3
2905    : twenty 20
2906    : EOF                  
2907    results in
2908    : |    one |  1 |
2909    : |    two |  2 |
2910    : |  three |  3 |
2911    : | twenty | 20 |
2912
2913 2. and the following (notice the command line argument)
2914    : $ cat <<EOF|~/src/config/bin/txt2org 1
2915    : strings numbers                                          
2916    : one 1
2917    : two 2
2918    : three 3
2919    : twenty 20
2920    : EOF 
2921    results in
2922    : | strings | numbers |
2923    : |---------+---------|
2924    : |     one |       1 |
2925    : |     two |       2 |
2926    : |   three |       3 |
2927    : |  twenty |      20 |
2928
2929 Here is the script itself
2930 #+begin_src awk
2931   #!/usr/bin/gawk -f
2932   #
2933   # Read tab separated data from STDIN and output an Org-mode table.
2934   #
2935   # Optional command line arguments specify row numbers at which to
2936   # insert hlines.
2937   #
2938   BEGIN {
2939       for(i=1; i<ARGC; i++){
2940           hlines[ARGV[i]+1]=1; ARGV[i] = "-"; } }
2941   
2942   {
2943       if(NF > max_nf){ max_nf = NF; };
2944       for(f=1; f<=NF; f++){
2945           if(length($f) > lengths[f]){ lengths[f] = length($f); };
2946           row[NR][f]=$f; } }
2947   
2948   END {
2949       hline_str="|"
2950       for(f=1; f<=max_nf; f++){
2951           for(i=0; i<(lengths[f] + 2); i++){ hline_str=hline_str "-"; }
2952           if( f != max_nf){ hline_str=hline_str "+"; }
2953           else            { hline_str=hline_str "|"; } }
2954   
2955       for(r=1; r<=NR; r++){ # rows
2956           if(hlines[r] == 1){ print hline_str; }
2957           printf "|";
2958           for(f=1; f<=max_nf; f++){ # columns
2959               cell=row[r][f]; padding=""
2960               for(i=0; i<(lengths[f] - length(cell)); i++){ padding=padding " "; }
2961               # for now just print everything right-aligned
2962               # if(cell ~ /[0-9.]/){ printf " %s%s |", cell, padding; }
2963               # else{                printf " %s%s |", padding, cell; }
2964               printf " %s%s |", padding, cell; }
2965           printf "\n"; }
2966       
2967       if(hlines[NR+1]){ print hline_str; } }
2968 #+end_src
2969
2970 ** remind2org
2971 #+index: Agenda!Views
2972 #+index: Agenda!and Remind (external program)
2973 From Detlef Steuer
2974
2975 http://article.gmane.org/gmane.emacs.orgmode/5073
2976
2977 #+BEGIN_QUOTE
2978 Remind (http://www.roaringpenguin.com/products/remind) is a very powerful
2979 command line calendaring program. Its features supersede the possibilities
2980 of orgmode in the area of date specifying, so that I want to use it
2981 combined with orgmode.
2982
2983 Using the script below I'm able use remind and incorporate its output in my
2984 agenda views.  The default of using 13 months look ahead is easily
2985 changed. It just happens I sometimes like to look a year into the
2986 future. :-)
2987 #+END_QUOTE
2988
2989 ** Useful webjumps for conkeror
2990 #+index: Shortcuts!conkeror
2991 If you are using the [[http://conkeror.org][conkeror browser]], maybe you want to put this into
2992 your =~/.conkerorrc= file:
2993
2994 #+begin_example
2995 define_webjump("orglist", "http://search.gmane.org/?query=%s&group=gmane.emacs.orgmode");
2996 define_webjump("worg", "http://www.google.com/cse?cx=002987994228320350715%3Az4glpcrritm&ie=UTF-8&q=%s&sa=Search&siteurl=orgmode.org%2Fworg%2F");
2997 #+end_example
2998
2999 It creates two [[http://conkeror.org/Webjumps][webjumps]] for easily searching the Worg website and the
3000 Org-mode mailing list.
3001
3002 ** Use MathJax for HTML export without requiring JavaScript
3003 #+index: Export!MathJax
3004 As of 2010-08-14, MathJax is the default method used to export math to HTML.
3005
3006 If you like the results but do not want JavaScript in the exported pages,
3007 check out [[http://www.jboecker.de/2010/08/15/staticmathjax.html][Static MathJax]], a XULRunner application which generates a static
3008 HTML file from the exported version. It can also embed all referenced fonts
3009 within the HTML file itself, so there are no dependencies to external files.
3010
3011 The download archive contains an elisp file which integrates it into the Org
3012 export process (configurable per file with a "#+StaticMathJax:" line).
3013
3014 Read README.org and the comments in org-static-mathjax.el for usage instructions.
3015 ** Search Org files using lgrep
3016 #+index: search!lgrep
3017 Matt Lundin suggests this:
3018
3019 #+begin_src emacs-lisp
3020   (defun my-org-grep (search &optional context)
3021     "Search for word in org files.
3022
3023 Prefix argument determines number of lines."
3024     (interactive "sSearch for: \nP")
3025     (let ((grep-find-ignored-files '("#*" ".#*"))
3026           (grep-template (concat "grep <X> -i -nH "
3027                                  (when context
3028                                    (concat "-C" (number-to-string context)))
3029                                  " -e <R> <F>")))
3030       (lgrep search "*org*" "/home/matt/org/")))
3031
3032   (global-set-key (kbd "<f8>") 'my-org-grep)
3033 #+end_src
3034
3035 ** Automatic screenshot insertion
3036 #+index: Link!screenshot
3037 Suggested by Russell Adams
3038
3039 #+begin_src emacs-lisp
3040   (defun my-org-screenshot ()
3041     "Take a screenshot into a time stamped unique-named file in the
3042   same directory as the org-buffer and insert a link to this file."
3043     (interactive)
3044     (setq filename
3045           (concat
3046            (make-temp-name
3047             (concat (buffer-file-name)
3048                     "_"
3049                     (format-time-string "%Y%m%d_%H%M%S_")) ) ".png"))
3050     (call-process "import" nil nil nil filename)
3051     (insert (concat "[[" filename "]]"))
3052     (org-display-inline-images))
3053 #+end_src
3054
3055 ** Capture invitations/appointments from MS Exchange emails
3056 #+index: Appointment!MS Exchange
3057 Dirk-Jan C.Binnema [[http://article.gmane.org/gmane.emacs.orgmode/27684/][provided]] code to do this.  Please check
3058 [[file:code/elisp/org-exchange-capture.el][org-exchange-capture.el]]
3059
3060 ** Audio/video file playback within org mode
3061 #+index: Link!audio/video
3062 Paul Sexton provided code that makes =file:= links to audio or video files
3063 (MP3, WAV, OGG, AVI, MPG, et cetera) play those files using the [[https://github.com/dbrock/bongo][Bongo]] Emacs
3064 media player library. The user can pause, skip forward and backward in the
3065 track, and so on from without leaving Emacs. Links can also contain a time
3066 after a double colon -- when this is present, playback will begin at that
3067 position in the track.
3068
3069 See the file [[file:code/elisp/org-player.el][org-player.el]]
3070
3071 ** Under X11 Keep a window with the current agenda items at all time
3072 #+index: Agenda!dedicated window
3073 I struggle to keep (in emacs) a window with the agenda at all times.
3074 For a long time I have wanted a sticky window that keeps this
3075 information, and then use my window manager to place it and remove its
3076 decorations (I can also force its placement in the stack: top always,
3077 for example).
3078
3079 I wrote a small program in qt that simply monitors an HTML file and
3080 displays it. Nothing more. It does the work for me, and maybe somebody
3081 else will find it useful. It relies on exporting the agenda as HTML
3082 every time the org file is saved, and then this little program
3083 displays the html file. The window manager is responsible of removing
3084 decorations, making it sticky, and placing it in same place always.
3085
3086 Here is a screenshot (see window to the bottom right). The decorations
3087 are removed by the window manager:
3088
3089 http://turingmachine.org/hacking/org-mode/orgdisplay.png
3090
3091 Here is the code. As I said, very, very simple, but maybe somebody will
3092 find if useful.
3093
3094 http://turingmachine.org/hacking/org-mode/
3095
3096 --daniel german
3097
3098 ** Script (thru procmail) to output emails to an Org file
3099 #+index: Conversion!email to org file
3100 Tycho Garen sent [[http://comments.gmane.org/gmane.emacs.orgmode/44773][this]]:
3101
3102 : I've [...] created some procmail and shell glue that takes emails and
3103 : inserts them into an org-file so that I can capture stuff on the go using
3104 : the email program.
3105
3106 Everything is documented [[http://tychoish.com/code/org-mail/][here]].
3107
3108 ** Save File With Different Format for Headings (fileconversion)
3109    :PROPERTIES:
3110    :CUSTOM_ID: fileconversion
3111    :END:
3112 #+index: Conversion!fileconversion
3113
3114 Using hooks and on the fly
3115 - when writing a buffer to the file replace the leading stars from headings
3116   with a file char
3117 - when reading a file into the buffer replace the file chars with leading
3118   stars for headings
3119
3120 To change to save an Org file in one of the formats or back just add or
3121 remove the keyword in the STARTUP line and save.
3122
3123 Now you can also change to Fundamental mode to see how the file looks like
3124 on the level of the file, go back to Org mode, reenter Org mode or change to
3125 any other major mode and the conversion gets done whenever necessary.
3126
3127 *** Headings Without Leading Stars (hidestarsfile and nbspstarsfile)
3128     :PROPERTIES:
3129     :CUSTOM_ID: hidestarsfile
3130     :END:
3131 #+index: Conversion!fileconversion hidestarsfile
3132
3133 This is like "a cleaner outline view":
3134 http://orgmode.org/manual/Clean-view.html
3135
3136 Example of the _file content_ first with leading stars as usual and below
3137 without leading stars through "#+STARTUP: odd hidestars hidestarsfile":
3138
3139 #+BEGIN_EXAMPLE
3140   #+STARTUP: odd hidestars
3141   [...]
3142   ***** TODO section
3143   ******* subsection
3144   ********* subsubsec
3145             - bla bla
3146   ***** section
3147         - bla bla
3148   ******* subsection
3149 #+END_EXAMPLE
3150
3151 #+BEGIN_EXAMPLE
3152   #+STARTUP: odd hidestars hidestarsfile
3153   [...]
3154       * TODO section
3155         * subsection
3156           * subsubsec
3157             - bla bla
3158       * section
3159         - bla bla
3160         * subsection
3161 #+END_EXAMPLE
3162
3163 The latter is convenient for better human readability when an Org file,
3164 additionally to Emacs, is read with a file viewer or, for smaller edits,
3165 with an editor not capable of the Org file format.
3166
3167 hidestarsfile is a hack and can not become part of the Org core:
3168 - An Org file with hidestarsfile can not contain list items with a star as
3169   bullet due to the syntax conflict at read time. Mark E. Shoulson suggested
3170   to use the non-breaking space which is now implemented in fileconversion
3171   as nbspstarsfile as an alternative for hidestarsfile. Although I don't
3172   recommend it because an editor like typically e. g. Emacs may render the
3173   non-breaking space differently from the space 0x20.
3174 - An Org file with hidestarsfile can almost not be edited with an Org mode
3175   without added functionality of hidestarsfile as long as the file is not
3176   converted back.
3177
3178 *** Headings in Markdown Format (markdownstarsfile)
3179     :PROPERTIES:
3180     :CUSTOM_ID: markdownstarsfile
3181     :END:
3182 #+index: Conversion!fileconversion markdownstarsfile
3183
3184 For "oddeven" you can use markdownstarsfile to be readable or even basically
3185 editable with Markdown (does not make much sense with "odd", see
3186 org-convert-to-odd-levels and org-convert-to-oddeven-levels for how to
3187 convert).
3188
3189 Example of the _file content_:
3190
3191 #+BEGIN_EXAMPLE
3192   #+STARTUP: oddeven markdownstarsfile
3193   # section level 1
3194     1. first item of numbered list (same format in Org and Markdown)
3195   ## section level 2
3196      - first item of unordered list (same format in Org and Markdown)
3197   ### section level 3
3198       + first item of unordered list (same format in Org and Markdown)
3199   #### section level 4
3200        * first item of unordered list (same format in Org and Markdown)
3201        * avoid this item type to be compatible with Org hidestarsfile
3202 #+END_EXAMPLE
3203
3204 An Org file with markdownstarsfile can not contain code comment lines
3205 prefixed with "#", even not when within source blocks.
3206
3207 *** emacs-lisp code
3208     :PROPERTIES:
3209     :CUSTOM_ID: fileconversion-code
3210     :END:
3211 #+index: Conversion!fileconversion emacs-lisp code
3212
3213 #+BEGIN_SRC emacs-lisp
3214   ;; - fileconversion version 0.7
3215   ;; - DISCLAIMER: Make a backup of your Org files before using
3216   ;;   my-org-fileconv-*.
3217   ;; - supported formats: hidestarsfile, markdownstarsfile
3218
3219   ;; design summary: fileconversion is a round robin of two states
3220   ;; linked by two actions:
3221   ;; - state v-org-fileconv-level-org-p is nil: the level is “file”
3222   ;;   (encoded)
3223   ;; - action f-org-fileconv-decode: replace file char with “*”
3224   ;; - state v-org-fileconv-level-org-p is t: the level is “Org”
3225   ;;   (decoded)
3226   ;; - action f-org-fileconv-encode: replace “*” with file char
3227   ;; naming convention of prefix:
3228   ;; - f-[...]: “my function”, instead of the unspecific prefix “my-”
3229   ;; - v-[...]: “my variable”, instead of the unspecific prefix “my-”
3230
3231   (defvar v-org-fileconv-level-org-p nil
3232     "Whether level of buffer is Org or only file.
3233   nil means the level is file (encoded), non-nil means the level is Org
3234   (decoded).")
3235   (make-variable-buffer-local 'v-org-fileconv-level-org-p)
3236   ;; survive a change of major mode that does kill-all-local-variables,
3237   ;; e. g. when reentering Org mode through “C-c C-c” on a STARTUP line
3238   (put 'v-org-fileconv-level-org-p 'permanent-local t)
3239
3240   (add-hook 'org-mode-hook 'f-org-fileconv-init
3241             ;; _append_ to hook to have a higher chance that a message
3242             ;; from this function will be visible as the last message in
3243             ;; the minibuffer
3244             t
3245             ;; hook addition globally
3246             nil)
3247
3248   (defun f-org-fileconv-init ()
3249     (interactive)
3250     ;; instrument only when converting really from/to an Org _file_, not
3251     ;; e. g. for a temp Org buffer unrelated to a file like used e. g.
3252     ;; when calling the old Org exporter
3253     (when (buffer-file-name)
3254       (message "INF: f-org-fileconv-init, buffer: %s" (buffer-name))
3255       (f-org-fileconv-decode)
3256       ;; the hooks are not permanent-local, this way and as needed they
3257       ;; will disappear when the major mode of the buffer changes
3258       (add-hook 'change-major-mode-hook 'f-org-fileconv-encode nil
3259                 ;; hook addition limited to buffer locally
3260                 t)
3261       (add-hook 'before-save-hook 'f-org-fileconv-encode nil
3262                 ;; hook addition limited to buffer locally
3263                 t)
3264       (add-hook 'after-save-hook 'f-org-fileconv-decode nil
3265                 ;; hook addition limited to buffer locally
3266                 t)))
3267
3268   (defun f-org-fileconv-re ()
3269     "Check whether there is a STARTUP line for fileconversion.
3270   If found then return the expressions required for the conversion."
3271     (save-excursion
3272       (goto-char (point-min))  ;; beginning-of-buffer not allowed
3273       (let (re-list (count 0))
3274         (while (re-search-forward "^#\\+STARTUP:" nil t)
3275           ;; #+STARTUP: hidestarsfile
3276           (when (string-match-p "\\bhidestarsfile\\b"
3277                                 (thing-at-point 'line))
3278             ;; exclude e. g.:
3279             ;; - line starting with star for bold emphasis
3280             ;; - line of stars to underline section title in loosely
3281             ;;   quoted ASCII style (star at end of line)
3282             (setq re-list '("\\(\\* \\)"  ; common-re
3283                             ?\ ))         ; file-char
3284             (setq count (1+ count)))
3285           ;; #+STARTUP: nbspstarsfile
3286           (when (string-match-p "\\bnbspstarsfile\\b"
3287                                 (thing-at-point 'line))
3288             (setq re-list '("\\(\\* \\)"  ; common-re
3289                             ?\xa0))       ; file-char non-breaking space
3290             (setq count (1+ count)))
3291           ;; #+STARTUP: markdownstarsfile
3292           (when (string-match-p "\\bmarkdownstarsfile\\b"
3293                                 (thing-at-point 'line))
3294             ;; exclude e. g.:
3295             ;; - #STARTUP:
3296             (setq re-list '("\\( \\)"  ; common-re
3297                             ?#))       ; file-char
3298             (setq count (1+ count))))
3299         (when (> count 1)
3300           (error "More than one fileconversion found"))
3301         re-list)))
3302
3303   (defun f-org-fileconv-decode ()
3304     "In headings replace file char with '*'."
3305     (let ((re-list (f-org-fileconv-re)))
3306       (when (and re-list (not v-org-fileconv-level-org-p))
3307         ;; no `save-excursion' to be able to keep point in case of error
3308         (let* ((common-re (nth 0 re-list))
3309                (file-char (nth 1 re-list))
3310                (file-re   (concat "^" (string file-char) "+" common-re))
3311                (org-re    (concat "^\\*+" common-re))
3312                len
3313                (p         (point)))
3314           (goto-char (point-min))  ;; beginning-of-buffer not allowed
3315           ;; syntax check
3316           (when (re-search-forward org-re nil t)
3317             (goto-char (match-beginning 0))
3318             (org-reveal)
3319             (error "Org fileconversion dec: syntax conflict at point"))
3320           (goto-char (point-min))  ;; beginning-of-buffer not allowed
3321           ;; substitution
3322           (with-silent-modifications
3323             (while (re-search-forward file-re nil t)
3324               (goto-char (match-beginning 0))
3325               ;; faster than a lisp call of insert and delete on each
3326               ;; single char
3327               (setq len (- (match-beginning 1) (match-beginning 0)))
3328               (insert-char ?* len)
3329               (delete-char len)))
3330           (goto-char p))))
3331
3332           ;; notes for ediff when only one file has fileconversion:
3333           ;; - The changes to the buffer with fileconversion until here
3334           ;;   are not regarded by ediff-files because the first call to
3335           ;;   diff is made with the bare files directly. Only
3336           ;;   ediff-update-diffs and ediff-buffers write the decoded
3337           ;;   buffers to temp files and then call diff with them.
3338           ;; - Workarounds (choose one):
3339           ;;   - after ediff-files first do a "!" (ediff-update-diffs)
3340           ;;     in the "*Ediff Control Panel*"
3341           ;;   - instead of using ediff-files first open the files and
3342           ;;     then run ediff-buffers (better for e. g. a script that
3343           ;;     takes two files as arguments and uses "emacs --eval")
3344
3345     ;; the level is Org most of all when no fileconversion is in effect
3346     (setq v-org-fileconv-level-org-p t))
3347
3348   (defun f-org-fileconv-encode ()
3349     "In headings replace '*' with file char."
3350     (let ((re-list (f-org-fileconv-re)))
3351       (when (and re-list v-org-fileconv-level-org-p)
3352         ;; no `save-excursion' to be able to keep point in case of error
3353         (let* ((common-re (nth 0 re-list))
3354                (file-char (nth 1 re-list))
3355                (file-re   (concat "^" (string file-char) "+" common-re))
3356                (org-re    (concat "^\\*+" common-re))
3357                len
3358                (p         (point)))
3359           (goto-char (point-min))  ;; beginning-of-buffer not allowed
3360           ;; syntax check
3361           (when (re-search-forward file-re nil t)
3362             (goto-char (match-beginning 0))
3363             (org-reveal)
3364             (error "Org fileconversion enc: syntax conflict at point"))
3365           (goto-char (point-min))  ;; beginning-of-buffer not allowed
3366           ;; substitution
3367           (with-silent-modifications
3368             (while (re-search-forward org-re nil t)
3369               (goto-char (match-beginning 0))
3370               ;; faster than a lisp call of insert and delete on each
3371               ;; single char
3372               (setq len (- (match-beginning 1) (match-beginning 0)))
3373               (insert-char file-char len)
3374               (delete-char len)))
3375           (goto-char p)
3376           (setq v-org-fileconv-level-org-p nil))))
3377     nil)  ;; for the hook
3378 #+END_SRC
3379
3380 Michael Brand
3381
3382 ** Meaningful diff for org files in a git repository
3383 #+index: git!diff org files
3384 Since most diff utilities are primarily meant for source code, it is
3385 difficult to read diffs of text files like ~.org~ files easily. If you
3386 version your org directory with a SCM like git you will know what I
3387 mean. However for git, there is a way around. You can use
3388 =gitattributes= to define a custom diff driver for org files. Then a
3389 regular expression can be used to configure how the diff driver
3390 recognises a "function".
3391
3392 Put the following in your =<org_dir>/.gitattributes=.
3393 : *.org diff=org
3394 Then put the following lines in =<org_dir>/.git/config=
3395 : [diff "org"]
3396 :       xfuncname = "^(\\*+ [a-zA-Z0-9]+.+)$"
3397
3398 This will let you see diffs for org files with each hunk identified by
3399 the unmodified headline closest to the changes. After the
3400 configuration a diff should look something like the example below.
3401
3402 #+begin_example
3403 diff --git a/org-hacks.org b/org-hacks.org
3404 index a0672ea..92a08f7 100644
3405 --- a/org-hacks.org
3406 +++ b/org-hacks.org
3407 @@ -2495,6 +2495,22 @@ ** Script (thru procmail) to output emails to an Org file
3408  
3409  Everything is documented [[http://tychoish.com/code/org-mail/][here]].
3410  
3411 +** Meaningful diff for org files in a git repository
3412 +
3413 +Since most diff utilities are primarily meant for source code, it is
3414 +difficult to read diffs of text files like ~.org~ files easily. If you
3415 +version your org directory with a SCM like git you will know what I
3416 +mean. However for git, there is a way around. You can use
3417 +=gitattributes= to define a custom diff driver for org files. Then a
3418 +regular expression can be used to configure how the diff driver
3419 +recognises a "function".
3420 +
3421 +Put the following in your =<org_dir>/.gitattributes=.
3422 +: *.org        diff=org
3423 +Then put the following lines in =<org_dir>/.git/config=
3424 +: [diff "org"]
3425 +:      xfuncname = "^(\\*+ [a-zA-Z0-9]+.+)$"
3426 +
3427  * Musings
3428  
3429  ** Cooking?  Brewing?
3430 #+end_example
3431
3432 ** Opening devonthink links
3433
3434 John Wiegley wrote [[https://github.com/jwiegley/dot-emacs/blob/master/lisp/org-devonthink.el][org-devonthink.el]], which lets you handle devonthink
3435 links from org-mode.
3436
3437 * Musings
3438
3439 ** Cooking?  Brewing?
3440 #+index: beer!brewing
3441 #+index: cooking!conversions
3442 See [[http://article.gmane.org/gmane.emacs.orgmode/44981][this message]] from Erik Hetzner:
3443
3444 It currently does metric/english conversion, and a few other tricks.
3445 Basically I just use calc’s units code.  I think scaling recipes, or
3446 turning percentages into weights would be pretty easy.
3447
3448   https://gitorious.org/org-cook/org-cook
3449
3450 There is also, for those interested:
3451
3452   https://gitorious.org/org-brew/org-brew
3453
3454 for brewing beer. This is again, mostly just calc functions, including
3455 hydrometer correction, abv calculation, priming sugar for a given CO_2
3456 volume, etc. More integration with org-mode should be possible: for
3457 instance it would be nice to be able to use a lookup table (of ingredients)
3458 to calculate target original gravity, IBUs, etc.
3459