org-customization-guide.org

   1 #+TITLE:     Org-Mode Beginners Customization Guide
   2 #+AUTHOR:    Carsten Dominik
   3 #+EMAIL:     carsten.dominik@gmail.com
   4 #+LANGUAGE:  en
   5 #+OPTIONS:   H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:nil skip:t d:nil tags:not-in-toc
   6
   7 * Introduction
   8   :PROPERTIES:
   9   :ID:       68EE02FB-4F09-4BDC-8577-AD4F60DE1B1B
  10   :END:
  11
  12 Org-mode is a highly customizable package.  It currently contains
  13 close to 400 customization variables that can be changed to tweak
  14 every detail, and more than 260 are known to be actually used out
  15 there.
  16
  17 However, as a beginner you do not care about this kind of flexibility.
  18 On this page, we have a list of five settings that you might want to
  19 try first in order to personalize your system.
  20
  21 Once you are done with that, we also have a list of some 40 variables
  22 that are [[http://orgmode.org/worg/org-customization-survey.php][changed by many users]].
  23
  24
  25 * The Basics
  26
  27 ** Minimal customization
  28
  29 The minimal customization needed to use Org-mode is -- *Nothing at
  30 all!* \par Org-mode works out of the box, and besides the steps described
  31 in the manual to [[http://orgmode.org/manual/Activation.html#Activation][activate]] it, /nothing is needed at all/.  Just open a
  32 /.org/ file, press =C-c [= to tell org that this is a file you want to
  33 use in your agenda, and start putting your life into plain text.
  34
  35 OK, for completeness, let's just repeat what is needed to activate
  36 Org-mode in files with /.org/ extension, and a few important key
  37 assignments.
  38
  39 #+begin_src emacs-lisp
  40 (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
  41 (global-set-key "\C-cl" 'org-store-link)
  42 (global-set-key "\C-ca" 'org-agenda)
  43 (global-font-lock-mode 1)
  44 #+end_src
  45
  46 ** Five small steps toward a personalized system
  47
  48 *** One: More TODO keywords
  49
  50 Define the TODO states you find useful and single letters for fast
  51 selection.  Customize the variable =org-todo-keywords= or simply do
  52 this right in the file with[fn:1:press =C-c C-c= in the line after
  53 changing it]:
  54
  55 #+begin_src org
  56 ,#+TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d) CANCELED(c)
  57 #+end_src
  58
  59 *** Two: Which tags do you use most?
  60
  61 You can always add tags freely and by hand, but if you configure the
  62 most important ones along with fast-access keys, life will be better.
  63 Configure the variable =org-tags-alist= or simply do this right in the
  64 file with[fn:1]
  65
  66 #+begin_src org
  67 ,#+TAGS: home(h) work(w) @computer(c) @phone(p) errants(e)
  68 #+end_src
  69
  70 *** Three: Which files are relevant for the agenda?
  71
  72 When Org compiles agenda views like the the agenda for the current
  73 week (=C-c a a=) or the global TODO list (=C-c a t=), it checks all
  74 files in the variable =org-agenda-files=.  Instead of setting this
  75 variable explicitly, it is much easier to just add and remove the
  76 current buffer with =C-c [= and =C-c ]=, respectively.
  77
  78 *** Four: Find what you need to see now
  79
  80 If you need to sharpen the predefined agenda commands, define your [[http://orgmode.org/manual/Custom-agenda-views.html#Custom-agenda-views][own]]
  81 Agenda commands, using the variable =org-agenda-custom-commands=.
  82 This is a pretty complex variable, but if you use the customize
  83 interface[fn:2: =M-x customize-variable RET
  84 org-agenda-custom-commands RET=], it is not too hard.  Everyone
  85 ends up customizing this one after getting comfortable with Org-mode.
  86 Do checkout [[http://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.php][this tutorial]] on building your own custom agenda commands
  87 as well.
  88
  89 *** Five: Capture ideas with predefined templates
  90
  91 Use /remember/ to quickly capture ideas, tasks, and notes.  Add
  92 #+begin_src emacs-lisp
  93 (org-remember-insinuate)
  94 #+end_src
  95 to your setup and populate[fn:3: =M-x customize-variable RET
  96 org-remember-templates RET=] the variable =org-remember-templates=
  97 with templates and target locations.
  98
  99
 100 * Pretend to be a power-user
 101
 102 Here is a list of the variables most frequently changed by power
 103 users.  The variables mentioned above are repeated in this list.  Yes,
 104 some power users change 60 options or more, but these showed up most
 105 frequently in the [[http://orgmode.org/worg/org-customization-survey.php][customization survey]].
 106
 107 *** Basic setup
 108
 109 Here are a few things about basic setup that many people change.
 110
 111 - org-directory :: Where are my Org files typically located?  Org
 112      acutally uses this variable only under rare circumstances, like
 113      when filing remember notes in an interactive way and prompting
 114      you for an Org file to put the note into.
 115
 116 - org-agenda-files :: Which [[http://orgmode.org/manual/Agenda-files.html#Agenda-files][files]] do I want to be checked for entries
 117      when compiling my agenda?  Many people do not customize this one,
 118      but just use =C-c [= and =C-c ]= to add or remove the current
 119      file, respectively.
 120
 121 - org-startup-folded :: When visiting an Org file, in what [[http://orgmode.org/manual/Visibility-cycling.html#Visibility-cycling][folding
 122      state]] do I first want to see it?  Many use =#+STARTUP= options to
 123      set this on a [[http://orgmode.org/manual/In_002dbuffer-settings.html#In_002dbuffer-settings][per-file basis]].
 124
 125 - org-archive-location :: When [[http://orgmode.org/manual/Archiving.html#Archiving][archiving]] an entry, where will it go?
 126
 127 *** Editing behavior and appearance
 128
 129 Besides being an organizer, Org-mode is also a text mode for writing
 130 and taking notes.  The following variables that influence basic
 131 editing behavior and the appearance of the buffer are often
 132 customized:
 133
 134 - org-hide-leading-stars :: Make the outline more list-like be [[http://orgmode.org/manual/Clean-view.html#Clean-view][hiding]]
 135      all leading stars but one.
 136
 137 - org-odd-levels-only :: Should [[http://orgmode.org/manual/Clean-view.html#Clean-view][2 stars]] be added per level?  This
 138      makes the indentation more like in a book.
 139
 140 - org-special-ctrl-a/e :: Should =C-a= and =C-e= behave specially,
 141      considering the headline and not the leading stars, todo
 142      keywords, or the trailing tags?  About equal numbers of users set
 143      this to =t= or to =reversed=
 144
 145 - org-special-ctrl-k :: Should =C-k= behave [[http://orgmode.org/worg/org-faq.php#C-k-is-killing-subtrees][specially]] in headlines,
 146      considering tags and visibility state?
 147
 148 - org-completion-use-ido :: Should /ido.el/ be used for completion
 149      whenever it makes sense?
 150
 151 - org-return-follows-link :: Should pressing RET on a hyperlink [[http://orgmode.org/manual/Handling-links.html#Handling-links][follow]]
 152      the link?  People who are used to this from web browsers often
 153      make this choice.
 154
 155 - org-blank-before-new-entry :: Org-mode tries to be smart about
 156      inserting blank lines before [[http://orgmode.org/manual/Structure-editing.html#Structure-editing][new entries/items]], by looking at
 157      what is before the previous entry/item.  Customize this to
 158      out-smart it.
 159
 160 *** The TODO keywords
 161
 162 - org-todo-keywords :: Which [[http://orgmode.org/manual/TODO-extensions.html#TODO-extensions][TODO keywords]] should be used?  Also you
 163      can define keys for [[http://orgmode.org/manual/Fast-access-to-TODO-states.html#Fast-access-to-TODO-states][fast access]] here.  Very many people use this,
 164      or define the keywords with a =#+TODO:= setting in the buffer.
 165
 166 - org-todo-keyword-faces :: Here you can define different faces for
 167      different TODO keywords.
 168
 169 - org-enforce-todo-dependencies :: Should unfinished children [[http://orgmode.org/manual/TODO-dependencies.html#TODO-dependencies][block]]
 170      state changes in the parent?
 171
 172 - org-enforce-todo-checkbox-dependencies :: Should unfinished
 173      checkboxes [[http://orgmode.org/manual/TODO-dependencies.html#TODO-dependencies][block]] state changes in the parent?
 174
 175 *** Tags
 176
 177 - org-tag-alist :: Which [[http://orgmode.org/manual/Tags.html#Tags][tags]] should be available?  Note that tags
 178      besides the configured one can be used, but for the important
 179      ones you can define keys for [[http://orgmode.org/manual/Setting-tags.html#Setting-tags][fast access]] here.
 180
 181 - org-tags-column :: How should tags be aligned in the headline?
 182
 183 - org-fast-tag-selection-single-key :: Set this to make the tags
 184      interface even faster, if all you normally do is changing a single
 185      tag.
 186
 187 *** Progress logging
 188
 189 - org-log-done :: Do you want to [[http://orgmode.org/manual/Progress-logging.html#Progress-logging][capture]] time stamps and/or notes when
 190      TODO state changes, in particular when a task is DONE?  A simple
 191      setting that many use is =(setq org-log-done 'time)=.
 192
 193 *** Remember and Refile
 194
 195 - org-reverse-note-order :: When adding new entries (or tasks) to a
 196      list, do I want the entry to be first or last in the list?
 197
 198 /Remember/ is great for fast capture of ideas, notes, and tasks.  It
 199 is one of the primary capture methods in Org-mode.
 200
 201 - org-remember-templates :: Prepare [[http://orgmode.org/manual/Remember-templates.html#Remember-templates][templates]] for the typical notes
 202      and tasks you want to capture quickly using remember.  I believe
 203      everyone using /Remember/ with Org customizes this.  Don't forget
 204      to also call =org-remember-insinuate= in your startup file.
 205
 206 - org-default-notes-file :: If you do not set up templates with target
 207      files, at least tell Org where to put captured notes.
 208
 209 /Refiling/ means moving entries around, for example from a capturing
 210 location to the correct project.
 211
 212 - org-refile-targets :: What should be on the [[http://orgmode.org/manual/Refiling-notes.html#Refiling-notes][menu]] when you refile
 213      tasks with =C-c C-w=?
 214
 215 - org-refile-use-outline-path :: How would you like to select refile
 216      targets. Headline only, or the path along the outline hierarchy?
 217
 218 *** Agenda Views
 219
 220 - org-agenda-start-on-weekday :: Should the [[http://orgmode.org/manual/Weekly_002fdaily-agenda.html#Weekly_002fdaily-agenda][agenda]] start on Monday, or
 221      better today?
 222
 223 - org-agenda-ndays :: How many days should the default agenda show?
 224      Default is 7, a whole week.
 225
 226 - org-agenda-include-diary :: Should the agenda also show [[http://orgmode.org/manual/Weekly_002fdaily-agenda.html#Weekly_002fdaily-agenda][entries]] from
 227      the Emacs diary?
 228
 229 - org-agenda-custom-commands :: Define your [[http://orgmode.org/manual/Custom-agenda-views.html#Custom-agenda-views][own]] Agenda commands.
 230      Complex, advanced variable, but pretty much everyone ends up
 231      configuring it.  Use customize to configure it, this is the best
 232      and safest way.  Do checkout [[http://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.php][this tutorial]] on building your own
 233      custom agenda commands as well.
 234
 235 - org-agenda-sorting-strategy :: How should things be [[http://orgmode.org/manual/Sorting-of-agenda-items.html#Sorting-of-agenda-items][sorted]] in the
 236      agenda display.  Even though I think the defaults are very usable,
 237      power users tend to tweak this.
 238
 239 - org-stuck-projects :: How to find projects that need [[http://orgmode.org/manual/Stuck-projects.html#Stuck-projects][attention]]?
 240
 241 To reduce clutter in the task list for today, many users like to
 242 remove tasks from the daily list right when they are done.  The
 243 following variables give detailed control to what kind of entries this
 244 should apply:
 245
 246 - org-agenda-skip-scheduled-if-done :: Scheduled entries.  Many users
 247      turn this on.
 248
 249 - org-agenda-skip-deadline-if-done  :: Deadlines.  Many users turn
 250      this on.
 251
 252 - org-agenda-skip-timestamp-if-done :: Entries with any timestamp,
 253      appointments just like scheduled and deadline entries.
 254      Relatively few users select this one.
 255
 256 People who use Org like a [[http://www.newartisans.com/blog/2007/08/using-org-mode-as-a-day-planner.html][day planner]], who [[http://orgmode.org/manual/Deadlines-and-scheduling.html#Deadlines-and-scheduling][schedule]] all tasks to
 257 specific dates, often like to not have scheduled tasks listed in their
 258 global TODO list, because scheduling it already means to have taking
 259 care of it in a sense, and because they know they will run into these
 260 tasks in the agenda anyway.
 261
 262 - org-agenda-todo-ignore-deadlines :: Don't show deadline tasks in
 263      global TODO list.
 264
 265 - org-agenda-todo-ignore-with-date :: Don't show any tasks with a date
 266      in the global TODO list.
 267
 268 - org-agenda-todo-ignore-scheduled :: Don't show scheduled tasks
 269      in the global TODO list.
 270
 271 *** Export/Publishing setup
 272
 273 - org-export-with-LaTeX-fragments :: Should [[http://orgmode.org/manual/LaTeX-fragments.html#LaTeX-fragments][LaTeX fragments]] be
 274      converted to inline images for HTML output?
 275
 276 - org-export-html-style :: Customize the default [[http://orgmode.org/manual/CSS-support.html#CSS-support][style]] for HTML
 277      export.
 278
 279 - org-publish-project-alist :: Set up projects that allow many files
 280      to be exported and [[http://orgmode.org/manual/Publishing.html#Publishing][published]] with a single command.
 281
 282
 283 * Become a true power user
 284
 285 If you want to become a true power user, [[http://thread.gmane.org/gmane.emacs.orgmode/10804][see]] for yourself what
 286 some users do.  The Emacs customization system[fn:5:=M-x
 287 org-customize RET=] organizes all variables into a structure that can
 288 be used to easily [[http://orgmode.org/worg/org-tutorials/org-customize.php][find the one particular option]] you might be looking
 289 for.  Also, the [[http://orgmode.org/manual/][Org-mode manual]] and the [[http://orgmode.org/worg/org-faq.php][FAQ]] mention many variables in
 290 the appropriate context.
 291