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