org-web: Embarassing typo...
[worg.git] / org-glossary.org
1 #+TITLE:      Org Glossary: An Explanation of Basic Org-Mode Concepts
2 #+AUTHOR:     Worg people
3 #+EMAIL:      mdl AT imapmail DOT org
4 #+OPTIONS:    H:3 num:nil toc:1 \n:nil @:t ::t |:t ^:nil -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
5 #+STARTUP:    align fold nodlcheck 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 [[file:index.org][{Back to Worg's index}]]
13
14 # Please feel free to add items or to complete any of the unfinished items.
15
16 * The Glossary
17
18 #+index: Glossary!Definition
19
20 The org-manual does a great job of explaining the myriad features of
21 org-mode. But for new users, the sheer number of options and features
22 can be overwhelming.
23
24 #+begin_quote
25
26 What exactly are properties? How should I use them? Do I need to know
27 how they work in order to use org mode?
28
29 What are categories? How do they differ from tags?
30
31 #+end_quote
32
33 If you find yourself asking such questions, this document is for you.
34 In the table of contents, you will find an alphabetical list of basic
35 concepts/features in org-mode. Click on any of them to jump to a brief
36 definition, a more detailed explanation of the feature, and a
37 description of possible uses. And feel free to add your own
38 definitions by [[file:worg-about.org][editing Worg]].
39
40 * Agenda
41   :PROPERTIES:
42   :CUSTOM_ID: agenda
43   :END: 
44
45 #+index: Agenda!Definition
46
47 ** Definition
48
49 The agenda allows you to create filtered views of the items in your
50 [[#agenda-files][agenda files]]. These include "day-planner" views of your schedule,
51 lists of your todos, and the results of queries (for tags, words,
52 regular expressions, etc.). You might think of the agenda as a
53 combination of a task manager and a very powerful search interface.
54
55 ** Details
56
57 Provided you have followed the manual's instructions on setting up
58 org-mode and have designated some [[#agenda-files][agenda files]], simply type =C-c C-a=
59 (or =M-x org-agenda=) to gain access to the various views available.
60
61 Here are brief explanations of the options:
62
63  - a (Agenda) :: Presents a view of today's (or, optionally, this
64    week's) scheduled items, appointments, and upcoming deadlines.
65
66  - t (Todo entries) :: Presents a list of all active [[#todo-keywords][todo
67    keywords]] in your agenda files.
68
69  - m (Match) :: Allows you to search your agenda files for headlines
70    with particular metadata (tags, properties, or TOD0s). 
71
72      + The simplest way to query your files is to enter the name of a
73        tag, e.g., "@computer".
74
75      + To construct more advanced queries, please [[http://orgmode.org/manual/Matching-tags-and-properties.html][consult the manual]].
76
77  - L (Timeline for current buffer) :: Shows a chronological view of
78    all items with dates in the file you are currently visiting.
79
80  - s (Search) :: Allows you to search entries in your agenda files for
81    particular words or regular expressions.
82
83  - / (multi-occur) :: Shows all lines in your agenda files matching a
84    regular expression.
85
86  - < :: Restricts the agenda view to the file you are currently
87    visiting.
88
89  - << :: Restricts the agenda view to the subtree you are currently
90    visiting.
91
92 Within the agenda view, each item is linked to its location in your
93 files, so you can jump directly to that location from the agenda (by
94 pressing =TAB= or =RET=).
95
96 ** Uses
97
98 The uses of the agenda are limitless!
99
100 The agenda frees you from having to worry too much about the
101 organization of your org-mode files. If you are new to org-mode,
102 simply start by creating todos in your outlines and notes and
103 (optionally) adding tags and scheduling information to them. Even if
104 your file is cluttered with extraneous notes and ramblings, the agenda
105 will find the relevant lines and display them in a clean and readable
106 fashion.
107
108   - One use of the agenda is as a day planner system. If you prefer to
109     schedule your tasks and to see a daily agenda of TODOs, you'll
110     probably be pressing =C-c a a= a lot.
111
112   - The agenda can also be used for a powerful GTD system. If you like
113     to filter your "next actions" by context, then you'll probably
114     make frequent use of =C-c a t= to see a list of all your active
115     TODOs and to filter them by tag/context.
116
117   - While the agenda is a powerful task management tool, it is also a
118     fantastic research tool. If you keep a file full of reading notes,
119     for instance, you can use the agenda to locate entries containing
120     a particular word or labeled by a particular tag.
121
122 There are many more possibilities of configuring the agenda with
123 [[http://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.php][custom agenda commands]].
124     
125 * Agenda files
126   :PROPERTIES:
127   :CUSTOM_ID: agenda-files
128   :END:
129
130 #+index: Agenda Files!Definition
131
132 ** Definition
133
134 These are the files that are used to generate your [[#agenda][agenda]] views. When
135 you call your agenda, the TODOs and scheduling information in your
136 agenda files will be displayed.
137
138 ** Details
139
140 There are different ways to designate these files:
141
142   1. Add a file manually with =C-c [= (=M-x
143      org-agenda-file-to-front=).
144      
145      - Remove with =C-c ]= (=M-x org-remove-file=).
146
147   2. Type =M-x customize-variable [RET] org-agenda-files= and enter
148      the names of your agenda files.
149
150      - If you enter a directory, all org files in that directory will
151        be included in your agenda files.
152
153 ** Tips: Organizing agenda files
154
155 One of the most common questions for new (and seasoned) users of
156 org-mode is how to organize agenda files. Should you put everything in
157 one big file organized by project? Should you create a new file for
158 each project? Or should you have separate "containers" for different
159 types of data: i.e., one file (or subtree) for appointments, one for
160 reference, one for todos, and so on.
161
162 The short answer: it doesn't matter. The agenda will be able to parse
163 and organize your TODOs, appointments, and deadlines no matter how
164 they are organized in your files.
165
166 If you are using org-mode for the first time, the simplest approach
167 may be to use a single file and to enter projects or todos as the
168 appear. Then, whenever you review your file, reorganize your todos and
169 projects into "groupings" (i.e., trees) that make sense to you. If a
170 tree starts to get too big, then start a new file. Perhaps you'll
171 discover that you want to keep your "work" and "personal" tasks in
172 different files.
173
174 Perhaps the main consideration in organizing your files is to consider
175 [[#inheritance][inheritance]] and [[#file-restriction][restriction]]. If you'd like a number of items to belong
176 to the same category or to have the same tags for easy agenda
177 filtering, then they probably belong in the same tree and/or file.
178
179 An example:
180
181   - If you'd like all your appointments to belong to the [[#category][category]]
182     "appts", then it probably doesn't make sense to scatter them as
183     first level headings among multiple files. It would make more
184     sense to create an appointments file or heading with the category
185     "appts".
186
187   - On the other hand, if you'd prefer to organize your appointments
188     by area of responsibility (e.g., work, personal, health, etc.),
189     then it would make perfect sense to place them in separate trees
190     and/or files.
191
192 * Archiving
193   :PROPERTIES:
194   :CUSTOM_ID: archiving
195   :END:
196
197 #+index: Archiving!Definition
198
199 ** Definition
200
201 Archiving is a way of hiding and/or getting rid of old or unwanted
202 items in your org files without deleting them altogether.
203
204 ** Details
205
206 Archiving works on [[#tree][subtrees]] in your org-file by doing the following:
207
208   - Preventing them from opening when you cycle visibility with =TAB=
209     or =Shift-TAB=. (They will stay closed unless you explictly open
210     them with =Control-TAB=.)
211
212   - Keeping them out of your [[#agenda][agenda]] views. (They will only be included
213     if you type =v a= or =v A= in the agenda.)
214
215 There are three different ways to archiving an item/tree:
216
217   - C-c C-x a :: Mark the subtree as archived (i.e., give it an
218      =:ARCHIVE:= tag) but leave it in its current location.
219
220        - The headline remains visible in your org file but its contents
221          will not open during cycling and it will not be included in
222          the agenda.
223
224   - C-c C-x A :: Move the subtree to a separate archive headline
225      within the parent tree and/or file.
226
227        - This is useful for maintaining a clean org-file, since it
228          removes archived headlines from view.
229
230   - C-c C-x C-s :: Move the subtree to a separate file. The default
231      name of the file is =[filename].org_archive=.
232
233        - This is useful for getting rid of subtrees altogether. You
234          might want to use this when you finish a project.
235
236        - Since this is a relatively drastic action, org-mode offers an
237          alternate version of the command (=C-u C-c C-x C-s=) that
238          checks the subtree to make sure there are no active TODOs
239          before archiving it.
240
241 ** Uses
242
243 Archiving is very useful for keeping your org files free of clutter.
244 But which type of archiving should you use?
245
246 Here are a few ideas:
247
248   - Use =C-c C-x a= when you'd like to archive an entry/subtree but
249     want to be reminded of its presence (e.g., to be reminded of a
250     completed task) when you view your org file.
251
252   - Use =C-c C-x A= when you want to remove an entry/subtree from view but
253     want it to remain together with its context (i.e., within the file
254     or parent tree). This is often useful for archiving TODO items
255     that are part of an incomplete project.
256
257   - Use =C-c C-x C-s= when you are sure you no longer require an
258     entry/subtree except for reference. This is often useful for
259     archiving completed projects.
260
261 * Attachment
262   :PROPERTIES:
263   :CUSTOM_ID: Attachment
264   :END:
265
266 #+index: Attachment!Definition
267
268 ** Definition
269 Attachments allow the addition of arbitrary reference material (e.g. binary files, images, audio, etc.) 
270 to a node in an org file.
271
272 ** Details
273 Attachments are files located in a directory belonging to an outline
274 node.  Org uses directories named by the unique ID of each entry
275 and stored the ID as a special property of the node
276 These directories are located in the `data' directory which lives in
277 the same directory where your Org file lives(1).  If you initialize
278 this directory with `git init', Org will automatically commit changes
279 when it sees them.
280
281 ** Uses
282 Attachments can be used essentially for the purposes as links, to allow
283 access to documents related to a particular node. If there is a large number
284 of such links, it may be more convenient to just put them in a directory
285 and plant a link to the directory. Attachments provide a more convenient
286 way to do this latter task.
287
288 * Category
289   :PROPERTIES:
290   :CUSTOM_ID: category
291   :END:
292
293 #+index: Category!Definition
294
295 ** Definition
296 A category is the group an item belongs to.
297
298 ** Details
299 The category of an item is shown in the left hand column of the
300 daily/weekly agenda view.
301
302 : Day-agenda (W38):
303 : Wednesday  16 September 2009
304 :   badclient:  Scheduled:  TODO Call angry client to calm him down
305 :   appts:      Dinner at Julio's 
306
307 By default an item's category is the name of the file (minus the
308 extension) to which it belongs.
309
310 You can specify a different category for a file by placing the
311 following line at the top of your org file:
312
313 #+begin_src org
314   ,#+CATEGORY: CompanyABC
315 #+end_src
316
317 Or, you can set a category as the property of a [[#tree][tree]]. All items in
318 that tree will [[#inheritance][inherit]] that category and be labeled with it in the
319 agenda.
320
321 #+begin_src org
322   ,* Birthdays
323   ,  :PROPERTIES:
324   ,  :CATEGORY: birthdays
325   ,  :END:
326 #+end_src
327
328 ** Uses
329
330 The main purpose of a category is to increase visibility in the
331 daily/weekly agenda --- i.e., to allow you to see which "group" an
332 item belongs to. 
333
334 Apart from visibility and compartmentalization, categories do not add
335 much additional functionality to an item. It is certainly *not*
336 necessary to set them for every file and/or heading.
337
338 You can search for items by category in the agenda using the following
339 key sequence:
340
341 : C-c C-a m CATEGORY="birthdays"
342
343 In general, categories are *not* an efficient way of searching
344 for and/or filtering tasks. It is much faster to use [[#tag][tags]] or filetags
345 for this.
346
347 Here's one way to distinguish between categories and tags: an entry
348 can belong to only one category but it can have multiple tags.
349
350 * DEADLINE
351
352 #+index: DEADLINE!Definition
353
354 ** Definition
355
356 A deadline is a special timestamp for indicating items that should be
357 performed by a certain time. Reminders about deadlines appear in your
358 agenda a specified number of days before they due.
359
360 ** Details
361
362 You can add a deadline to a headline/entry by typing C-c C-d. You can
363 remove a deadline by typing C-u C-c C-d.
364
365 Here is the syntax for deadlines:
366
367 #+begin_src org
368   ,* My big project
369   ,  DEADLINE: <2009-09-20 Sun>
370 #+end_src
371
372 You will be alerted of this deadline ahead of time when you select the
373 daily/weekly agenda (=C-c C-a a=).
374
375 :  index:      In   3 d.:  My big project
376
377 How soon the warning appears in your agenda is controlled by the
378 variable =org-deadline-warning-days=. The default number of days is 14.
379
380 The deadline will remain in your agenda (as an overdue item) until it
381 is marked done.
382
383 You can change the a warning period for a particular headline by
384 adding something like "-3d" (3 days) or "-2m" (two months) to the
385 timestamp:
386
387 #+begin_src org
388   ,* My big project
389   ,  DEADLINE: <2009-09-20 Sun -2m>
390 #+end_src
391
392 ** Uses
393
394 The obvious use of a deadline is to reminder yourself of tasks that
395 need to be completed by a certain date. 
396
397 Deadlines can also be useful as an "advanced notice" system --- e.g.,
398 reminding yourself to prepare for an event or project.
399
400 You can add both a deadline and a scheduling timestamp to the same
401 entry.
402
403 * Docstring
404   :PROPERTIES:
405   :CUSTOM_ID: docstring
406   :END:
407
408 #+index: Docstring!Definition
409
410 ** Definition
411 A [[http://en.wikipedia.org/wiki/Docstring][docstring]] is the documentation written as part of a emacs lisp
412 variable or a function. It is part of Emacs' wonderful interactive
413 help system.
414
415 (Note: This definition is not org-mode specific, but is rather a more
416 general org-mode/lisp/coding concept. It's included here because
417 mailing list posts often reference a "docstring," an obscure phrase
418 for anyone not familiar with coding lingo.)
419
420 ** Details and uses
421
422 If you are wondering what a particular org-mode key combination,
423 function, or variable does, the manual is not your only source of
424 information. Carsten has also embedded a wealth of resources into the
425 org-mode source code itself. These can be easily viewed using Emacs
426 built-in help functions.
427
428 For instance, let's say you want to learn more about creating a clock
429 report in org mode. One way to do this is to type =C-h k= or =M-x
430 describe-key= and then to enter the relevant key combination (=C-c
431 C-x-C-r=). This will provide the following very helpful information:
432
433 : org-clock-report is an interactive compiled Lisp function in
434 : `org-clock.el'.
435
436 : It is bound to C-c C-x C-r, <menu-bar> <Org> <Logging work> <Create
437 : clock table>.
438
439 : (org-clock-report &optional arg)
440
441 : Create a table containing a report about clocked time.
442 : If the cursor is inside an existing clocktable block, then the table
443 : will be updated.  If not, a new clocktable will be inserted.
444 : When called with a prefix argument, move to the first clock table in the
445 : buffer and update it.
446
447 : [back]
448
449 If you happened to know the name of the function, you could also
450 locate the same information using =C-h f= or =M-x describe-function=
451 and entering =org-clock-report=. Or you could use =C-h a= or
452 =apropos-command= to browse all functions that contain the words "org
453 clock".
454
455 Finally, if you want to learn more about variables, you can read their
456 docstrings by browsing the customize interface (=M-x customize-group
457 [RET] org=) or by typing =C-h v= or =M-x describe-variable=).
458
459 * Drawers
460   :PROPERTIES:
461   :CUSTOM_ID: drawers
462   :END:
463
464 #+index: Drawers!Definition
465
466 ** Definition
467
468 A drawer is a container that can hide information you don't want to
469 see during normal viewing and/or cycling of your outline.
470
471 ** Details
472
473 A drawer looks like this:
474
475 #+begin_src org
476   ,* Daily sleep log
477   ,  :LOGBOOK:
478   ,  - Note taken on [2009-09-16 Wed 04:02] \\
479   ,    Didn't sleep at all.
480   ,  - Note taken on [2009-09-15 Tue 05:25] \\
481   ,    Slept fitfully.
482   ,  - Note taken on [2009-09-14 Mon 09:30] \\
483   ,    Slept like a log.
484   ,  :END:
485 #+end_src
486
487 When you cycle the visibility of your outline, the contents of the
488 drawer will remain hidden. 
489
490 #+begin_src org
491   ,* Daily sleep log
492   ,  :LOGBOOK:
493 #+end_src
494
495 The only way to view the contents is to press =TAB= directly on the
496 drawer.
497
498 If you want a new name for a drawer, such as :NOTES:, you must
499 customize the variable "org-drawers". Simply type =M-x
500 customize-variable [RET] org-drawers" and add a new label.
501
502 ** Uses
503
504 By default, org-mode uses drawers to hide a variety of information,
505 such as [[#property][properties]] and clocked times.
506
507 But drawers are also quite useful for storing comments that you don't
508 want to see all the time. For instance, if you are writing a paper,
509 you might add a =:NOTE:= drawer to the variable =org-drawers=. Then
510 you can deposit any notes to yourself in such drawers. By default, the
511 information you put in drawers will not be exported to HTML, LaTeX,
512 etc.
513
514 * Entry
515   :PROPERTIES:
516   :CUSTOM_ID: entry
517   :END:
518
519 #+index: Entry!Definition
520
521 ** Definition
522
523 An entry is the basic unit of data in org-mode. It consists of a
524 [[#headline][headline]], metadata (tags, todo keyword, properties, priority, etc.),
525 and whatever other text it contains.
526
527 ** Details
528
529 An entry is to be distinguished from a [[#tree][tree]], which consists of all
530 headlines and entries beneath a particular entry within the outline
531 structure. Entries nested within other entries form a tree.
532
533 Here is a sample entry with a lot of data:
534
535 #+begin_src org
536   ,* TODO [#B] Headline                                                   :tags:
537   ,  :PROPERTIES:
538   ,  :DESCRIPTION: This is a sample property.
539   ,  :CATEGORY: documentation
540   ,  :CUSTOM_ID: an-extra-special-headline
541   ,  :END:
542   
543   ,And here is the text of an entry. You can put an unlimited amount of
544   ,text in an entry!
545   
546   ,You can also add lists:
547   
548   , - First item
549   
550   , - Second item
551   
552   , - Third item
553   
554   ,And tables:
555   
556   ,| Meal      | Food            | Calories |
557   ,|-----------+-----------------+----------|
558   ,| Breakfast | Eggs            |      500 |
559   ,| Lunch     | Escargot        |      800 |
560   ,| Dinner    | Bread and Water |      200 |
561   ,|-----------+-----------------+----------|
562   ,| Total     |                 |     1500 |
563 #+end_src
564
565 * Headline
566   :PROPERTIES:
567   :CUSTOM_ID: headline
568   :END: 
569
570 #+index: Headline!Definition
571
572 ** Definition
573 A headline is the name for an outline heading in an org file.
574
575 ** Details
576 Headlines begin with one or more asterisks. 
577
578 #+begin_src org
579   ,* A headline
580 #+end_src
581
582 The "level" of a headline corresponds to the number of asterisks. The more asterisks,
583 the deeper the level in the outline.
584
585 #+begin_src org
586   ,***** A "level 5" outline heading
587 #+end_src
588
589 As are all outlines, org-files are organized hierarchically. Deeper
590 headlines are "children" of higher-level "parent" headlines (and can
591 "inherit" their properties). Headlines on the same level are known as
592 siblings.
593
594 #+begin_src org
595   ,* A parent
596   ,** A child
597   ,*** Sibling one (also a child of "A child")
598   ,*** Sibling two
599   ,*** Sibling three
600 #+end_src
601
602 You can move headlines (and their corresponding [[#entry][entries]]) by using the
603 cursor keys in conjunction with the =Meta= key.
604
605  - =M-Left= and =M-Right= move the headline horizontally (i.e., change
606    its level).
607
608    - The org documentation often uses the terms "promote" and "demote"
609      for this action.
610
611  - =M-Up= and =M-Down= move the headline vertically.
612
613 You can easily jump to another headline using =M-x org-goto= (=C-c
614 C-j=).
615
616 You can easily "refile" a headline in a different location using =M-x
617 org-refile= (=C-c C-w=).
618
619 ** Uses
620
621 The basic use of headings, of course, is to distinguish separate
622 sections within your outline and to organize them hierarchically.
623
624 The other major use of headings is as TODO "items" that appear in your
625 agenda.
626
627 The power of org-mode lies in its treatment of headlines as
628 "containers" of information to which you can attach all sorts of data
629 ([[#todo-keywords][todo keywords]], [[tag][tags]], priorities, timestamps, [[#property][properties]], and an
630 unlimited amount of text). This turns org-mode's deceptively simple
631 outline structure into a powerful "database" of information, in which
632 units of data can be nested within one another.
633
634 * Inheritance
635
636 #+index: Inheritance!Definition
637
638 ** Definition
639
640 Inheritance is a term used to describe the way in which [[#entry][entries]] in a
641 [[#tree][tree]] can share the properties of their "parent" [[#headline][headlines]].
642
643 ** Details
644
645 Org-mode takes full advantage of the hierarchical structure of
646 outlines by allowing lower level headlines to "inherit" (or share) the
647 properties of their parents.
648
649 The most common form of inheritance in org-mode is "[[http://orgmode.org/manual/Tag-inheritance.html][tag inheritance]]".
650 This is controlled by the variable org-use-tag-inheritance (true by
651 default). When turned on, lower level outline headings share the tags
652 of their parents. Thus in the following tree, all the headlines have
653 the tag "=:reading:=", even though it is only explicitly set for the
654 top level headline:
655
656 #<<tag-inheritance-example>>
657 #+begin_src org
658   ,* Summer reading list                                               :reading:
659   ,  DEADLINE: <1965-06-06 Sun>
660   
661   ,** /To Kill a Mockingbird/
662   
663   ,** /Catch 22/
664   
665   ,** /Herzog/
666 #+end_src
667
668 Some properties, such as [[#category][category]], are also inherited by default. See
669 [[http://orgmode.org/manual/Property-inheritance.html][the manual]] for more details.
670
671 ** Uses
672
673 The most common use of tag inheritance is in agenda views and agenda
674 filtering. For instance, if you searched for the tag "reading" in your
675 agenda files, all of the headings in the [[tag-inheritance-example][example above]] would appear. 
676
677 As a result it is easy to add a tag and/or category to a whole subtree
678 of items simply by adding a single tag to the parent headline.
679
680 Let's say for instance, that you want to designate a whole bunch of
681 tasks as belonging to the project "topsecret". By adding =:topsecret:=
682 to the top headline of the group, you are in effect labeling all the
683 items in the tree as "topsecret". An agenda search for the TODOs with
684 the tag "topsecret" (=C-c a M [RET] topsecret=) would then return any
685 active TODOs in the entire tree.
686
687 Another common use of inheritance is to allow a special setting (e.g.,
688 logging or archive location) to apply to an entire subtree.
689
690 Finally, inheritance plays an important role in org-mode's column
691 view.
692
693 * Property
694   :PROPERTIES:
695   :CUSTOM_ID: property
696   :END:
697
698 #+index: Property!Definition
699
700 ** Definition
701
702 A property is an arbitrary piece of "metadata" you can attach to an
703 entry. A property takes the form of a "data pair," which consists of
704 a key and its value.
705
706 ** Details
707 Properties are stored in [[#drawer][drawers]] beneath a headline. Here is a sample
708 property drawer:
709
710 #+begin_src org
711   ,* Invoice for fixing the toilet
712   ,  :PROPERTIES:
713   ,  :LOGGING:  lognoterepeat
714   ,  :BILLED: 102.13
715   ,  :BILLING_DATE: 2009-09-11
716   ,  :CLIENT:   ABC Company
717   ,  :END:
718 #+end_src
719
720 Though org-mode reserves a handful of property keys for special uses
721 (e.g., LOGGING in the example above), you are otherwise free to add
722 whatever property keys and values you'd like.
723
724 Though you can type properties by hand, the simplest way to add them
725 is to type =C-c C-x p= or =M-x org-set-property=.
726
727 ** Uses
728
729 For new org users, properties can seem a bit puzzling. What exactly
730 are they for? Here are some of their uses:
731
732    1. To specify settings for the local org-mode [[#tree][tree]]. 
733
734       - For instance, though you may not normally want to be prompted
735         for a note when you mark an item as DONE, you might want to
736         make an exception for a particular task or project. To do so,
737         you would set the LOGGING property to "lognotedone" in the
738         relevant subtree.
739
740    2. To create a small database of information.
741
742       - The manual offers an nice example of this: [[http://orgmode.org/manual/Property-syntax.html#Property-syntax][keeping track
743         of a information about a CD collection]].
744
745       - Similarly, you might keep bibliographical information about
746         books you've read in properties.
747
748    3. To enter data that can be viewed as a "spreadsheet" in column view.
749
750    4. To create more specific labels for headlines than generic tags allow.
751
752       - For instance, if you are keeping track of expenses, you could
753         put the type of expense in a tag, but then it would be mixed
754         up with your other tags. A solution would be to create a
755         special property (e.g., EXPENSE_TYPE) to hold the information.
756
757    5. To label a particular tree with a unique ID so that it can be
758       referenced easily via hyperlinks.
759
760 * Tag
761   :PROPERTIES:
762   :CUSTOM_ID: tag
763   :END:
764
765 #+index: Tag!Definition
766
767 ** Definition
768
769 A tag is a label (or piece of "metadata") that is attached to a
770 headline for easy identification and filtering later. Several tags can
771 be attached to the same headline.
772
773 ** Details
774
775 Tags can be added to headlines with the key combination =C-c C-q= or
776 =C-c C-c=.
777
778 Tags have the following syntax:
779
780 #+begin_src org
781   ,* A headline with tags                               :Richard:URGENT:errands:
782 #+end_src
783
784 You may be familiar with tags from blogs or sites like [[http://del.icio.us][del.icio.us]].
785 Tags are a way of labeling information without having to rely on a
786 rigid hierarchical structure. Unlike categories, you can give a
787 headline/entry multiple tags. In many ways, org-mode offers the best
788 of both worlds: the hierarchical organization of an outline and the
789 impromptu labeling of tags.
790
791 The entry above would appear in queries for any of the tags:
792 "Richard", "URGENT", or "errands".
793
794 The syntax for searching tags via the [[#agenda][agenda]] is quite simple. For
795 instance, you could create a targeted agenda search for all items
796 tagged "Richard" and "urgent".
797
798 : C-c a m Richard+URGENT
799
800 Or for items tagged Richard that are not urgent:
801
802 : C-c a m Richard-URGENT
803
804 You can also use sparse view searches to display all tags within a
805 particular org-file.
806
807 If you find yourself commonly using certain tags, you can create a
808 list of shortcuts for them by typing =M-x customize-variable [RET]
809 org-tags-alist=. You can also set special tags for a particular file.
810 See [[http://orgmode.org/manual/Setting-tags.html][the manual]] for more details.
811
812 ** Uses
813
814 One common use of tags is as [[http://en.wikipedia.org/wiki/Getting_Things_Done#GTD_methodology][GTD contexts]]. You might, for instance,
815 define a list of tags in org-tags-alist that correspond to the various
816 contexts in a "next action" can be completed: @computer, @home,
817 @errands, @work, and so on. Then you can quickly filter for these tags
818 by pressing "=/=" in the agenda. See [[http://orgmode.org/manual/Agenda-commands.html#Agenda-commands][the manual]] for more details.
819
820 Another common use of a tag is to label a group of tasks as belonging
821 to a particular project or area of responsibility. For instance, you
822 might create a subtree in your file that contains all your house
823 repair projects and tag it with ":houserepair:". Let's say that when
824 Saturday rolls around, you decide to work exclusively on repairs.
825 Thanks to [[#inheritance][inheritance]], you can quickly locate all your tasks that
826 inherit the ":houserepair:" tag.
827
828 Here's what this would look like:
829
830 #+begin_src org
831   ,* Tasks around the house                                        :houserepair:
832   
833   ,** TODO Fix sink
834   
835   ,** TODO Mow lawn
836   
837   ,** TODO Tear up carpet
838 #+end_src
839
840 Tags are also extremely useful for notetaking and research. You might,
841 for instance, create a file of reading notes in which each entry is a
842 snippet of information tagged with relevant keywords. The beauty of
843 org-mode is that these snippets can be easily rearranged within the
844 outline and yet remain easy to find via tags.
845
846 ** Considerations: Tags vs. TODO keywords vs. Properties
847
848 One question that often emerges for new users of org mode is how to
849 decide when tags, [[#todo-keyword][TODO keywords]], or [[#property][properties]] are appropriate.
850
851 For instance, should you define your projects by creating a special
852 todo keyword for them (=PROJECT=) or by giving them a "=:project:="
853 tag? Similarly, should you create a TODO keyword for items that are
854 waiting, or should you add a "=:waiting:=" tag?
855
856 Either choice would be fine, of course, but here are a few
857 considerations to keep in mind:
858
859 1. Do you want quickly to filter for the item in the agenda view? If
860    so, a tag is probably your best choice.
861
862    - Note, you can add a setting to your .emacs that automatically
863      adds a tag whenever you assign a particular TODO keyword. Type
864      "=C-c v org-todo-state-tags-triggers=" for more information.
865
866 2. How visible do you want the keyword and/or tag to be? When viewing
867    an org-mode file, TODO Keywords are highly visible, tags somewhat
868    less so, and properties not at all.
869
870 3. Is the keyword part of your workflow? Do you want to be able to log
871    information (such as a timestamp and a note) when you add or remove
872    the keyword? If so, then use a TODO keyword.
873
874    - An example: While a "waiting" tag might make it easier to filter
875      for items in your todo list that are waiting/pending, a =WAITING=
876      todo keyword would allow you to keep track of when an item
877      entered the "waiting" state and when it left it.
878
879    - Similarly, if you want to keep track of a sequence of actions on
880      phone calls you receive, it would be relatively inefficient to
881      add and remove tags to designate each stage. It would probably be
882      better to set up a TODO sequence, such as ACT -> CALL -> MESSAGE
883      -> FOLLOWUP -> etc.
884
885 * Tree (subtree)
886   :PROPERTIES:
887   :CUSTOM_ID: tree
888   :END:
889
890 #+index: Tree!Definition
891 #+index: Subtree!Definition
892
893 ** Definition
894
895 A tree is created by the structure of an outline. It consists of a
896 heading and all subheadings/entries beneath it within the outline
897 hierarchy.
898
899 ** Details
900
901 A tree is to be distinguished from an [[#entry][entry]]. Whereas an entry
902 indicates only a single headline and its data, a tree consists of
903 multiple nested entries. And, of course, subtrees are nested within
904 larger trees.
905
906 * Todo Keywords
907   :PROPERTIES:
908   :CUSTOM_ID: todo-keyword
909   :END:
910
911 #+index: Todo Keywords!Definition
912
913 ** Definition
914
915 A TODO keyword is a small keyword at the beginning of a headline that
916 defines the TODO state of the entry. 
917
918 ** Details
919
920 The default TODO keywords in org-mode are TODO and DONE. They are
921 automatically given nice colors to make them stand out.
922
923 #+begin_src org
924   ,* DONE Check cupboard to see if I'm out of bread 
925   ,  CLOSED: [2009-09-16 Wed 13:14] 
926   ,* TODO Buy bread at the store
927 #+end_src
928
929 Org mode distinguishes between two types of keywords, active and
930 inactive (corresponding with the default TODO and DONE). By default,
931 active TODOs will be shown in [[#agenda][agenda views]]. Inactive todos will not be
932 shown.
933
934 You can select a TODO keyword by typing =C-c C-t= on an item. Or you
935 can move sequentially through TODOs by typing =Shift-Left= or
936 =Shift-Right=.
937
938 While the default keywords TODO and DONE will suffice for many users,
939 you can define your own TODO keywords (such as PROJECT, WAITING,
940 etc.) by following the instructions in the manual:
941
942 - http://orgmode.org/manual/TODO-Items.html
943
944 ** Uses
945 :PROPERTIES:
946 :ID:       e0f76b6c-411f-4df1-88f5-445e11d9ca1d
947 :END:
948
949 Not surprisingly, the most common use of TODO keywords is to indicate
950 items in your outline files that require action. Where other task
951 management systems often separate notes and todos, org-mode allows you
952 to mark items in your notes as TODOs.
953
954 Another common use of TODO keywords is to follow a single item through
955 an extended workflow. For instance, you might create a special TODO
956 keyword sequence for invoices by placing the following at the top of
957 your org file:
958
959 #+begin_src org
960 , #+SEQ_TODO: INVOICE(i) MAIL(m) WAITING(w) FOLLOWUP(f) | RECEIVED(r)
961 #+end_src
962
963 Note: The "|" separates active from inactive todos.
964
965 You can combine such todo sequences with logging in order to keep a
966 record of when each event in the sequence happened.
967
968 * TODO Awaiting definitions
969 ** Agenda filtering
970
971 #+index: Agenda filtering!Definition
972
973 ** CLOCK 
974
975 #+index: Clock!Definition
976
977 ** Column view
978
979 #+index: Column view!Definition
980
981 ** Cycling
982
983 #+index: Cycling!Definition
984
985 ** Effort estimate
986
987 #+index: Effort estimate!Definition
988
989 ** Filetag
990
991 #+index: Filetag!Definition
992
993 ** Project
994
995 #+index: Project!Definition
996
997 ** Note
998
999 #+index: Note!Definition
1000
1001 ** List 
1002
1003 #+index: List !Definition
1004
1005 ** Level
1006
1007 #+index: Level!Definition
1008
1009 ** Logging
1010
1011 #+index: Logging!Definition
1012
1013 ** SCHEDULED 
1014
1015 #+index: SCHEDULED!Definition
1016
1017 ** Restriction lock
1018
1019 #+index: Restriction lock!Definition
1020
1021 ** Table
1022
1023 #+index: Table!Definition
1024
1025 ** Timestamp
1026
1027 #+index: Timestamp!Definition