Fix org-glossary.org
[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:
494 #+end_src
495
496 The only way to view the contents is to press =TAB= directly on the
497 drawer.
498
499 If you want a new name for a drawer, such as :NOTES:, you must
500 customize the variable "org-drawers". Simply type =M-x
501 customize-variable [RET] org-drawers" and add a new label.
502
503 ** Uses
504
505 By default, org-mode uses drawers to hide a variety of information,
506 such as [[#property][properties]] and clocked times.
507
508 But drawers are also quite useful for storing comments that you don't
509 want to see all the time. For instance, if you are writing a paper,
510 you might add a =:NOTE:= drawer to the variable =org-drawers=. Then
511 you can deposit any notes to yourself in such drawers. By default, the
512 information you put in drawers will not be exported to HTML, LaTeX,
513 etc.
514
515 * Entry
516   :PROPERTIES:
517   :CUSTOM_ID: entry
518   :END:
519
520 #+index: Entry!Definition
521
522 ** Definition
523
524 An entry is the basic unit of data in org-mode. It consists of a
525 [[#headline][headline]], metadata (tags, todo keyword, properties, priority, etc.),
526 and whatever other text it contains.
527
528 ** Details
529
530 An entry is to be distinguished from a [[#tree][tree]], which consists of all
531 headlines and entries beneath a particular entry within the outline
532 structure. Entries nested within other entries form a tree.
533
534 Here is a sample entry with a lot of data:
535
536 #+begin_src org
537   ,* TODO [#B] Headline                                                   :tags:
538      :PROPERTIES:
539      :DESCRIPTION: This is a sample property.
540      :CATEGORY: documentation
541      :CUSTOM_ID: an-extra-special-headline
542      :END:
543   
544    And here is the text of an entry. You can put an unlimited amount of
545    text in an entry!
546   
547    You can also add lists:
548   
549     - First item
550   
551     - Second item
552   
553     - Third item
554   
555    And tables:
556   
557    | Meal      | Food            | Calories |
558    |-----------+-----------------+----------|
559    | Breakfast | Eggs            |      500 |
560    | Lunch     | Escargot        |      800 |
561    | Dinner    | Bread and Water |      200 |
562    |-----------+-----------------+----------|
563    | Total     |                 |     1500 |
564 #+end_src
565
566 * Headline
567   :PROPERTIES:
568   :CUSTOM_ID: headline
569   :END: 
570
571 #+index: Headline!Definition
572
573 ** Definition
574 A headline is the name for an outline heading in an org file.
575
576 ** Details
577 Headlines begin with one or more asterisks. 
578
579 #+begin_src org
580   ,* A headline
581 #+end_src
582
583 The "level" of a headline corresponds to the number of asterisks. The more asterisks,
584 the deeper the level in the outline.
585
586 #+begin_src org
587   ,***** A "level 5" outline heading
588 #+end_src
589
590 As are all outlines, org-files are organized hierarchically. Deeper
591 headlines are "children" of higher-level "parent" headlines (and can
592 "inherit" their properties). Headlines on the same level are known as
593 siblings.
594
595 #+begin_src org
596   ,* A parent
597   ,** A child
598   ,*** Sibling one (also a child of "A child")
599   ,*** Sibling two
600   ,*** Sibling three
601 #+end_src
602
603 You can move headlines (and their corresponding [[#entry][entries]]) by using the
604 cursor keys in conjunction with the =Meta= key.
605
606  - =M-Left= and =M-Right= move the headline horizontally (i.e., change
607    its level).
608
609    - The org documentation often uses the terms "promote" and "demote"
610      for this action.
611
612  - =M-Up= and =M-Down= move the headline vertically.
613
614 You can easily jump to another headline using =M-x org-goto= (=C-c
615 C-j=).
616
617 You can easily "refile" a headline in a different location using =M-x
618 org-refile= (=C-c C-w=).
619
620 ** Uses
621
622 The basic use of headings, of course, is to distinguish separate
623 sections within your outline and to organize them hierarchically.
624
625 The other major use of headings is as TODO "items" that appear in your
626 agenda.
627
628 The power of org-mode lies in its treatment of headlines as
629 "containers" of information to which you can attach all sorts of data
630 ([[#todo-keywords][todo keywords]], [[tag][tags]], priorities, timestamps, [[#property][properties]], and an
631 unlimited amount of text). This turns org-mode's deceptively simple
632 outline structure into a powerful "database" of information, in which
633 units of data can be nested within one another.
634
635 * Inheritance
636
637 #+index: Inheritance!Definition
638
639 ** Definition
640
641 Inheritance is a term used to describe the way in which [[#entry][entries]] in a
642 [[#tree][tree]] can share the properties of their "parent" [[#headline][headlines]].
643
644 ** Details
645
646 Org-mode takes full advantage of the hierarchical structure of
647 outlines by allowing lower level headlines to "inherit" (or share) the
648 properties of their parents.
649
650 The most common form of inheritance in org-mode is "[[http://orgmode.org/manual/Tag-inheritance.html][tag inheritance]]".
651 This is controlled by the variable org-use-tag-inheritance (true by
652 default). When turned on, lower level outline headings share the tags
653 of their parents. Thus in the following tree, all the headlines have
654 the tag "=:reading:=", even though it is only explicitly set for the
655 top level headline:
656
657 #<<tag-inheritance-example>>
658 #+begin_src org
659   ,* Summer reading list                                               :reading:
660     DEADLINE: <1965-06-06 Sun>
661   
662   ,** /To Kill a Mockingbird/
663   
664   ,** /Catch 22/
665   
666   ,** /Herzog/
667 #+end_src
668
669 Some properties, such as [[#category][category]], are also inherited by default. See
670 [[http://orgmode.org/manual/Property-inheritance.html][the manual]] for more details.
671
672 ** Uses
673
674 The most common use of tag inheritance is in agenda views and agenda
675 filtering. For instance, if you searched for the tag "reading" in your
676 agenda files, all of the headings in the [[tag-inheritance-example][example above]] would appear. 
677
678 As a result it is easy to add a tag and/or category to a whole subtree
679 of items simply by adding a single tag to the parent headline.
680
681 Let's say for instance, that you want to designate a whole bunch of
682 tasks as belonging to the project "topsecret". By adding =:topsecret:=
683 to the top headline of the group, you are in effect labeling all the
684 items in the tree as "topsecret". An agenda search for the TODOs with
685 the tag "topsecret" (=C-c a M [RET] topsecret=) would then return any
686 active TODOs in the entire tree.
687
688 Another common use of inheritance is to allow a special setting (e.g.,
689 logging or archive location) to apply to an entire subtree.
690
691 Finally, inheritance plays an important role in org-mode's column
692 view.
693
694 * Property
695   :PROPERTIES:
696   :CUSTOM_ID: property
697   :END:
698
699 #+index: Property!Definition
700
701 ** Definition
702
703 A property is an arbitrary piece of "metadata" you can attach to an
704 entry. A property takes the form of a "data pair," which consists of
705 a key and its value.
706
707 ** Details
708 Properties are stored in [[#drawer][drawers]] beneath a headline. Here is a sample
709 property drawer:
710
711 #+begin_src org
712   ,* Invoice for fixing the toilet
713      :PROPERTIES:
714      :LOGGING:  lognoterepeat
715      :BILLED: 102.13
716      :BILLING_DATE: 2009-09-11
717      :CLIENT:   ABC Company
718      :END:
719 #+end_src
720
721 Though org-mode reserves a handful of property keys for special uses
722 (e.g., LOGGING in the example above), you are otherwise free to add
723 whatever property keys and values you'd like.
724
725 Though you can type properties by hand, the simplest way to add them
726 is to type =C-c C-x p= or =M-x org-set-property=.
727
728 ** Uses
729
730 For new org users, properties can seem a bit puzzling. What exactly
731 are they for? Here are some of their uses:
732
733    1. To specify settings for the local org-mode [[#tree][tree]]. 
734
735       - For instance, though you may not normally want to be prompted
736         for a note when you mark an item as DONE, you might want to
737         make an exception for a particular task or project. To do so,
738         you would set the LOGGING property to "lognotedone" in the
739         relevant subtree.
740
741    2. To create a small database of information.
742
743       - The manual offers an nice example of this: [[http://orgmode.org/manual/Property-syntax.html#Property-syntax][keeping track
744         of a information about a CD collection]].
745
746       - Similarly, you might keep bibliographical information about
747         books you've read in properties.
748
749    3. To enter data that can be viewed as a "spreadsheet" in column view.
750
751    4. To create more specific labels for headlines than generic tags allow.
752
753       - For instance, if you are keeping track of expenses, you could
754         put the type of expense in a tag, but then it would be mixed
755         up with your other tags. A solution would be to create a
756         special property (e.g., EXPENSE_TYPE) to hold the information.
757
758    5. To label a particular tree with a unique ID so that it can be
759       referenced easily via hyperlinks.
760
761 * Tag
762   :PROPERTIES:
763   :CUSTOM_ID: tag
764   :END:
765
766 #+index: Tag!Definition
767
768 ** Definition
769
770 A tag is a label (or piece of "metadata") that is attached to a
771 headline for easy identification and filtering later. Several tags can
772 be attached to the same headline.
773
774 ** Details
775
776 Tags can be added to headlines with the key combination =C-c C-q= or
777 =C-c C-c=.
778
779 Tags have the following syntax:
780
781 #+begin_src org
782   ,* A headline with tags                               :Richard:URGENT:errands:
783 #+end_src
784
785 You may be familiar with tags from blogs or sites like [[http://del.icio.us][del.icio.us]].
786 Tags are a way of labeling information without having to rely on a
787 rigid hierarchical structure. Unlike categories, you can give a
788 headline/entry multiple tags. In many ways, org-mode offers the best
789 of both worlds: the hierarchical organization of an outline and the
790 impromptu labeling of tags.
791
792 The entry above would appear in queries for any of the tags:
793 "Richard", "URGENT", or "errands".
794
795 The syntax for searching tags via the [[#agenda][agenda]] is quite simple. For
796 instance, you could create a targeted agenda search for all items
797 tagged "Richard" and "urgent".
798
799 : C-c a m Richard+URGENT
800
801 Or for items tagged Richard that are not urgent:
802
803 : C-c a m Richard-URGENT
804
805 You can also use sparse view searches to display all tags within a
806 particular org-file.
807
808 If you find yourself commonly using certain tags, you can create a
809 list of shortcuts for them by typing =M-x customize-variable [RET]
810 org-tags-alist=. You can also set special tags for a particular file.
811 See [[http://orgmode.org/manual/Setting-tags.html][the manual]] for more details.
812
813 ** Uses
814
815 One common use of tags is as [[http://en.wikipedia.org/wiki/Getting_Things_Done#GTD_methodology][GTD contexts]]. You might, for instance,
816 define a list of tags in org-tags-alist that correspond to the various
817 contexts in a "next action" can be completed: @computer, @home,
818 @errands, @work, and so on. Then you can quickly filter for these tags
819 by pressing "=/=" in the agenda. See [[http://orgmode.org/manual/Agenda-commands.html#Agenda-commands][the manual]] for more details.
820
821 Another common use of a tag is to label a group of tasks as belonging
822 to a particular project or area of responsibility. For instance, you
823 might create a subtree in your file that contains all your house
824 repair projects and tag it with ":houserepair:". Let's say that when
825 Saturday rolls around, you decide to work exclusively on repairs.
826 Thanks to [[#inheritance][inheritance]], you can quickly locate all your tasks that
827 inherit the ":houserepair:" tag.
828
829 Here's what this would look like:
830
831 #+begin_src org
832   ,* Tasks around the house                                        :houserepair:
833   
834   ,** TODO Fix sink
835   
836   ,** TODO Mow lawn
837   
838   ,** TODO Tear up carpet
839 #+end_src
840
841 Tags are also extremely useful for notetaking and research. You might,
842 for instance, create a file of reading notes in which each entry is a
843 snippet of information tagged with relevant keywords. The beauty of
844 org-mode is that these snippets can be easily rearranged within the
845 outline and yet remain easy to find via tags.
846
847 ** Considerations: Tags vs. TODO keywords vs. Properties
848
849 One question that often emerges for new users of org mode is how to
850 decide when tags, [[#todo-keyword][TODO keywords]], or [[#property][properties]] are appropriate.
851
852 For instance, should you define your projects by creating a special
853 todo keyword for them (=PROJECT=) or by giving them a "=:project:="
854 tag? Similarly, should you create a TODO keyword for items that are
855 waiting, or should you add a "=:waiting:=" tag?
856
857 Either choice would be fine, of course, but here are a few
858 considerations to keep in mind:
859
860 1. Do you want quickly to filter for the item in the agenda view? If
861    so, a tag is probably your best choice.
862
863    - Note, you can add a setting to your .emacs that automatically
864      adds a tag whenever you assign a particular TODO keyword. Type
865      "=C-c v org-todo-state-tags-triggers=" for more information.
866
867 2. How visible do you want the keyword and/or tag to be? When viewing
868    an org-mode file, TODO Keywords are highly visible, tags somewhat
869    less so, and properties not at all.
870
871 3. Is the keyword part of your workflow? Do you want to be able to log
872    information (such as a timestamp and a note) when you add or remove
873    the keyword? If so, then use a TODO keyword.
874
875    - An example: While a "waiting" tag might make it easier to filter
876      for items in your todo list that are waiting/pending, a =WAITING=
877      todo keyword would allow you to keep track of when an item
878      entered the "waiting" state and when it left it.
879
880    - Similarly, if you want to keep track of a sequence of actions on
881      phone calls you receive, it would be relatively inefficient to
882      add and remove tags to designate each stage. It would probably be
883      better to set up a TODO sequence, such as ACT -> CALL -> MESSAGE
884      -> FOLLOWUP -> etc.
885
886 * Tree (subtree)
887   :PROPERTIES:
888   :CUSTOM_ID: tree
889   :END:
890
891 #+index: Tree!Definition
892 #+index: Subtree!Definition
893
894 ** Definition
895
896 A tree is created by the structure of an outline. It consists of a
897 heading and all subheadings/entries beneath it within the outline
898 hierarchy.
899
900 ** Details
901
902 A tree is to be distinguished from an [[#entry][entry]]. Whereas an entry
903 indicates only a single headline and its data, a tree consists of
904 multiple nested entries. And, of course, subtrees are nested within
905 larger trees.
906
907 * Todo Keywords
908   :PROPERTIES:
909   :CUSTOM_ID: todo-keyword
910   :END:
911
912 #+index: Todo Keywords!Definition
913
914 ** Definition
915
916 A TODO keyword is a small keyword at the beginning of a headline that
917 defines the TODO state of the entry. 
918
919 ** Details
920
921 The default TODO keywords in org-mode are TODO and DONE. They are
922 automatically given nice colors to make them stand out.
923
924 #+begin_src org
925   ,* DONE Check cupboard to see if I'm out of bread 
926     CLOSED: [2009-09-16 Wed 13:14] 
927   ,* TODO Buy bread at the store
928 #+end_src
929
930 Org mode distinguishes between two types of keywords, active and
931 inactive (corresponding with the default TODO and DONE). By default,
932 active TODOs will be shown in [[#agenda][agenda views]]. Inactive todos will not be
933 shown.
934
935 You can select a TODO keyword by typing =C-c C-t= on an item. Or you
936 can move sequentially through TODOs by typing =Shift-Left= or
937 =Shift-Right=.
938
939 While the default keywords TODO and DONE will suffice for many users,
940 you can define your own TODO keywords (such as PROJECT, WAITING,
941 etc.) by following the instructions in the manual:
942
943 - http://orgmode.org/manual/TODO-Items.html
944
945 ** Uses
946 :PROPERTIES:
947 :ID:       e0f76b6c-411f-4df1-88f5-445e11d9ca1d
948 :END:
949
950 Not surprisingly, the most common use of TODO keywords is to indicate
951 items in your outline files that require action. Where other task
952 management systems often separate notes and todos, org-mode allows you
953 to mark items in your notes as TODOs.
954
955 Another common use of TODO keywords is to follow a single item through
956 an extended workflow. For instance, you might create a special TODO
957 keyword sequence for invoices by placing the following at the top of
958 your org file:
959
960 #+begin_src org
961   ,#+SEQ_TODO: INVOICE(i) MAIL(m) WAITING(w) FOLLOWUP(f) | RECEIVED(r)
962 #+end_src
963
964 Note: The "|" separates active from inactive todos.
965
966 You can combine such todo sequences with logging in order to keep a
967 record of when each event in the sequence happened.
968
969 * TODO Awaiting definitions
970 ** Agenda filtering
971
972 #+index: Agenda filtering!Definition
973
974 ** CLOCK 
975
976 #+index: Clock!Definition
977
978 ** Column view
979
980 #+index: Column view!Definition
981
982 ** Cycling
983
984 #+index: Cycling!Definition
985
986 ** Effort estimate
987
988 #+index: Effort estimate!Definition
989
990 ** Filetag
991
992 #+index: Filetag!Definition
993
994 ** Project
995
996 #+index: Project!Definition
997
998 ** Note
999
1000 #+index: Note!Definition
1001
1002 ** List 
1003
1004 #+index: List !Definition
1005
1006 ** Level
1007
1008 #+index: Level!Definition
1009
1010 ** Logging
1011
1012 #+index: Logging!Definition
1013
1014 ** SCHEDULED 
1015
1016 #+index: SCHEDULED!Definition
1017
1018 ** Restriction lock
1019
1020 #+index: Restriction lock!Definition
1021
1022 ** Table
1023
1024 #+index: Table!Definition
1025
1026 ** Timestamp
1027
1028 #+index: Timestamp!Definition