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