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