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