org-hacks.org

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