dotfiles/emacs.d/org.org

#+TITLE: Mike Gerwitz's Emacs Org Mode Configuration
#+AUTHOR: Mike Gerwitz
#+EMAIL: mtg@gnu.org

[[http://orgmode.org][<<<Org mode>>>]] is an incredibly flexible system for note taking, task
management, authoring, content generation, literate programming, and
countless other things.  It is amazing, and if you use it, so are
you.  Many have began using Emacs purely to use Org; it was one of my
considerations, since there is no equivalent for Vim (or any other
editor, for that matter).  This configuration file (and the output
that you may be reading) is written in and generated by Org.

If you do not know what Org mode is, then you should start researching
it immediately.

#+BEGIN_SRC emacs-lisp
  (setq org-directory "~/org")
#+END_SRC

* Outline Display
Some of the options herein are default, but it helps to clarify them
for rationale, certainty, and ensuring that future changes in defaults
doesn't eff with my shit.

** Folding
Org, by default, collapses the outline (into an "overview") upon
entering =org-mode=.  This is a convenient view for large outlines,
but is not something I particularly enjoy; I'll handle my own
collapsing if need be; I find it useful to see the whole document
immediately.

It is also an incredibly confusing option for beginners that have no
idea what is going on, or how to expand the outline.  Not that I know
that from personal experience or anything.  (Evil mode's keybinding
overrides didn't help that learning process any, either; I did
contribute a patch for vim-style folding that was accepted, though, so
that's solved.)

#+BEGIN_SRC emacs-lisp
  (setq org-startup-folded nil)
#+END_SRC

The =foldout= package performs folding via buffer narrowing, which can be
convenient to relieve mental stress for larger documents.

#+BEGIN_SRC emacs-lisp
  (eval-after-load "outline" '(require 'foldout))
#+END_SRC

** Indentation
Org's outline format is great, but it can be a bit obnoxious to
determine nesting at an arbitrary point: you have to visually
backtrack to the nearest heading to see its depth.

The easy solution is =org-indent-mode=, which indents text according
to the outline structure.

#+BEGIN_SRC emacs-lisp
  (setq org-startup-indented t)
#+END_SRC

** Line Truncation
Line length is a constant debate, and is one that I (naturally) have
strong opinions on.  Specifically, long lines (what I consider to be
"long") are a plague. =org-startup-truncated= can set
=truncate-lines= for you such that one line only gets one visual line
on the screen.  That is a terrible idea!  I do not want to scroll
horizontally to read someone else's terribly formatted text.

There may be some acceptable reasons for long line length, like long
URIs, or (very rarely) lines in programming languages that are not
easily broken due to syntatic peculiarities.

#+BEGIN_SRC emacs-lisp
  (setq org-startup-truncated nil)
#+END_SRC

* Task Management
Org is an excellent tool for task management.  Not only does it offer
varying degrees of flexibility with highly configurable options
(without having to write elisp), but it also has flexible constraint,
workflow, and reporting capabilities.

** Dependencies
It is useful to provide dependency constraints in TODO lists for both
data integrity and, well, sense.  Org offers a couple different
options for this out of the box.[fn:: There is also [[http://orgmode.org/worg/org-contrib/org-depend.html][=org-depend=]],
a contributed module, that provides even greated flexibility.  I have
not yet explored it, so I cannot provide any input as to its utility.]

#+BEGIN_SRC emacs-lisp
  (setq org-enforce-todo-dependencies          t
        org-enforce-todo-checkbox-dependencies t)
#+END_SRC

To help make apparent those items that cannot be completed due to
dependency constraints, they can be visually dimmed in agenda views:

#+BEGIN_SRC emacs-lisp
  (setq org-agenda-dim-blocked-tasks t)
#+END_SRC

** Capture
Org's "capture" feature (=org-capture=) allows for the quick capture
of notes (aha!) with little workflow interruption.  I do not make as
much use of it as I should; I constantly have thoughts that result in
TODOs or other notes.

Org recommends a keybinding to invoke =org-capture=:

#+BEGIN_SRC emacs-lisp
  (define-key global-map
    "\C-cc" 'org-capture)
#+END_SRC

I call my default notes file my scratchpad; if things stay there too
long without being organized, then that's generally a bad thing, or
they're not all that important.

#+BEGIN_SRC emacs-lisp
  (setq org-default-notes-file
        (concat org-directory "/scratch.org"))
#+END_SRC

I need to create some templates; they'll be here when I do.

* Source Code
#+BEGIN_SRC emacs-lisp
  (setq org-src-fontify-natively t)
#+END_SRC

#+BEGIN_SRC emacs-lisp
  (push '("el" "#+BEGIN_SRC emacs-lisp\n?\n#+END_SRC"
          "<src lang=\"emacs-lisp\">\n?\n</src>")
        org-structure-template-alist)
#+END_SRC