~bzg/worg

ref: 559025d3195c39306b5a5546c06a4e375fe4ff7f worg/org-glossary.org -rw-r--r-- 32.8 KiB
559025d3Bastien org-contribute.org: Add a note to maintainers 3 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
#+TITLE:      Org Glossary: An Explanation of Basic Org-Mode Concepts
#+AUTHOR:     Worg people
#+OPTIONS:    H:3 num:nil toc:1 \n:nil ::t |:t ^:nil -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
#+STARTUP:    align fold nodlcheck oddeven lognotestate
#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
#+TAGS:       Write(w) Update(u) Fix(f) Check(c)
#+LANGUAGE:   en
#+PRIORITIES: A C B
#+CATEGORY:   worg
#+HTML_LINK_UP:    index.html
#+HTML_LINK_HOME:  https://orgmode.org/worg/

# This file is released by its authors and contributors under the GNU
# Free Documentation license v1.3 or later, code examples are released
# under the GNU General Public License v3 or later.

# Please feel free to add items or to complete any of the unfinished items.

* The Glossary

#+index: Glossary!Definition

The org-manual does a great job of explaining the myriad features of
org-mode. But for new users, the sheer number of options and features
can be overwhelming.

#+begin_quote

What exactly are properties? How should I use them? Do I need to know
how they work in order to use org mode?

What are categories? How do they differ from tags?

#+end_quote

If you find yourself asking such questions, this document is for you.
In the table of contents, you will find an alphabetical list of basic
concepts/features in org-mode. Click on any of them to jump to a brief
definition, a more detailed explanation of the feature, and a
description of possible uses. And feel free to add your own
definitions by [[file:worg-about.org][editing Worg]].

* Agenda
  :PROPERTIES:
  :CUSTOM_ID: agenda
  :END:

#+index: Agenda!Definition

** Definition

The agenda allows you to create filtered views of the items in your
[[#agenda-files][agenda files]]. These include "day-planner" views of your schedule,
lists of your todos, and the results of queries (for tags, words,
regular expressions, etc.). You might think of the agenda as a
combination of a task manager and a very powerful search interface.

** Details

Provided you have followed the manual's instructions on setting up
org-mode and have designated some [[#agenda-files][agenda files]], simply type =C-c C-a=
(or =M-x org-agenda=) to gain access to the various views available.

Here are brief explanations of the options:

 - a (Agenda) :: Presents a view of today's (or, optionally, this
   week's) scheduled items, appointments, and upcoming deadlines.

 - t (Todo entries) :: Presents a list of all active [[#todo-keywords][todo
   keywords]] in your agenda files.

 - m (Match) :: Allows you to search your agenda files for headlines
   with particular metadata (tags, properties, or TOD0s).

     + The simplest way to query your files is to enter the name of a
       tag, e.g., "@computer".

     + To construct more advanced queries, please [[https://orgmode.org/manual/Matching-tags-and-properties.html][consult the manual]].

 - L (Timeline for current buffer) :: Shows a chronological view of
   all items with dates in the file you are currently visiting.

 - s (Search) :: Allows you to search entries in your agenda files for
   particular words or regular expressions.

 - / (multi-occur) :: Shows all lines in your agenda files matching a
   regular expression.

 - < :: Restricts the agenda view to the file you are currently
   visiting.

 - << :: Restricts the agenda view to the subtree you are currently
   visiting.

Within the agenda view, each item is linked to its location in your
files, so you can jump directly to that location from the agenda (by
pressing =TAB= or =RET=).

** Uses

The uses of the agenda are limitless!

The agenda frees you from having to worry too much about the
organization of your org-mode files. If you are new to org-mode,
simply start by creating todos in your outlines and notes and
(optionally) adding tags and scheduling information to them. Even if
your file is cluttered with extraneous notes and ramblings, the agenda
will find the relevant lines and display them in a clean and readable
fashion.

  - One use of the agenda is as a day planner system. If you prefer to
    schedule your tasks and to see a daily agenda of TODOs, you'll
    probably be pressing =C-c a a= a lot.

  - The agenda can also be used for a powerful GTD system. If you like
    to filter your "next actions" by context, then you'll probably
    make frequent use of =C-c a t= to see a list of all your active
    TODOs and to filter them by tag/context.

  - While the agenda is a powerful task management tool, it is also a
    fantastic research tool. If you keep a file full of reading notes,
    for instance, you can use the agenda to locate entries containing
    a particular word or labeled by a particular tag.

There are many more possibilities of configuring the agenda with
[[https://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.php][custom agenda commands]].

* Agenda files
  :PROPERTIES:
  :CUSTOM_ID: agenda-files
  :END:

#+index: Agenda Files!Definition

** Definition

These are the files that are used to generate your [[#agenda][agenda]] views. When
you call your agenda, the TODOs and scheduling information in your
agenda files will be displayed.

** Details

There are different ways to designate these files:

  1. Add a file manually with =C-c [= (=M-x
     org-agenda-file-to-front=).

     - Remove with =C-c ]= (=M-x org-remove-file=).

  2. Type =M-x customize-variable [RET] org-agenda-files= and enter
     the names of your agenda files.

     - If you enter a directory, all org files in that directory will
       be included in your agenda files.

** Tips: Organizing agenda files

One of the most common questions for new (and seasoned) users of
org-mode is how to organize agenda files. Should you put everything in
one big file organized by project? Should you create a new file for
each project? Or should you have separate "containers" for different
types of data: i.e., one file (or subtree) for appointments, one for
reference, one for todos, and so on.

The short answer: it doesn't matter. The agenda will be able to parse
and organize your TODOs, appointments, and deadlines no matter how
they are organized in your files.

If you are using org-mode for the first time, the simplest approach
may be to use a single file and to enter projects or todos as the
appear. Then, whenever you review your file, reorganize your todos and
projects into "groupings" (i.e., trees) that make sense to you. If a
tree starts to get too big, then start a new file. Perhaps you'll
discover that you want to keep your "work" and "personal" tasks in
different files.

Perhaps the main consideration in organizing your files is to consider
[[#inheritance][inheritance]] and [[#file-restriction][restriction]]. If you'd like a number of items to belong
to the same category or to have the same tags for easy agenda
filtering, then they probably belong in the same tree and/or file.

An example:

  - If you'd like all your appointments to belong to the [[#category][category]]
    "appts", then it probably doesn't make sense to scatter them as
    first level headings among multiple files. It would make more
    sense to create an appointments file or heading with the category
    "appts".

  - On the other hand, if you'd prefer to organize your appointments
    by area of responsibility (e.g., work, personal, health, etc.),
    then it would make perfect sense to place them in separate trees
    and/or files.

* Archiving
  :PROPERTIES:
  :CUSTOM_ID: archiving
  :END:

#+index: Archiving!Definition

** Definition

Archiving is a way of hiding and/or getting rid of old or unwanted
items in your org files without deleting them altogether.

** Details

Archiving works on [[#tree][subtrees]] in your org-file by doing the following:

  - Preventing them from opening when you cycle visibility with =TAB=
    or =Shift-TAB=. (They will stay closed unless you explictly open
    them with =Control-TAB=.)

  - Keeping them out of your [[#agenda][agenda]] views. (They will only be included
    if you type =v a= or =v A= in the agenda.)

There are three different ways to archiving an item/tree:

  - C-c C-x a :: Mark the subtree as archived (i.e., give it an
     =:ARCHIVE:= tag) but leave it in its current location.

       - The headline remains visible in your org file but its contents
         will not open during cycling and it will not be included in
         the agenda.

  - C-c C-x A :: Move the subtree to a separate archive headline
     within the parent tree and/or file.

       - This is useful for maintaining a clean org-file, since it
         removes archived headlines from view.

  - C-c C-x C-s :: Move the subtree to a separate file. The default
     name of the file is =[filename].org_archive=.

       - This is useful for getting rid of subtrees altogether. You
         might want to use this when you finish a project.

       - Since this is a relatively drastic action, org-mode offers an
         alternate version of the command (=C-u C-c C-x C-s=) that
         checks the subtree to make sure there are no active TODOs
         before archiving it.

** Uses

Archiving is very useful for keeping your org files free of clutter.
But which type of archiving should you use?

Here are a few ideas:

  - Use =C-c C-x a= when you'd like to archive an entry/subtree but
    want to be reminded of its presence (e.g., to be reminded of a
    completed task) when you view your org file.

  - Use =C-c C-x A= when you want to remove an entry/subtree from view but
    want it to remain together with its context (i.e., within the file
    or parent tree). This is often useful for archiving TODO items
    that are part of an incomplete project.

  - Use =C-c C-x C-s= when you are sure you no longer require an
    entry/subtree except for reference. This is often useful for
    archiving completed projects.

* Attachment
  :PROPERTIES:
  :CUSTOM_ID: Attachment
  :END:

#+index: Attachment!Definition

** Definition
Attachments allow the addition of arbitrary reference material (e.g. binary files, images, audio, etc.)
to a node in an org file.

** Details
Attachments are files located in a directory belonging to an outline
node.  Org uses directories named by the unique ID of each entry
and stored the ID as a special property of the node
These directories are located in the `data' directory which lives in
the same directory where your Org file lives(1).  If you initialize
this directory with `git init', Org will automatically commit changes
when it sees them.

** Uses
Attachments can be used essentially for the purposes as links, to allow
access to documents related to a particular node. If there is a large number
of such links, it may be more convenient to just put them in a directory
and plant a link to the directory. Attachments provide a more convenient
way to do this latter task.

* Category
  :PROPERTIES:
  :CUSTOM_ID: category
  :END:

#+index: Category!Definition

** Definition
A category is the group an item belongs to.

** Details
The category of an item is shown in the left hand column of the
daily/weekly agenda view.

: Day-agenda (W38):
: Wednesday  16 September 2009
:   badclient:  Scheduled:  TODO Call angry client to calm him down
:   appts:      Dinner at Julio's

By default an item's category is the name of the file (minus the
extension) to which it belongs.

You can specify a different category for a file by placing the
following line at the top of your org file:

#+begin_src org
  ,#+CATEGORY: CompanyABC
#+end_src

Or, you can set a category as the property of a [[#tree][tree]]. All items in
that tree will [[#inheritance][inherit]] that category and be labeled with it in the
agenda.

#+begin_src org
  ,* Birthdays
    :PROPERTIES:
    :CATEGORY: birthdays
    :END:
#+end_src

** Uses

The main purpose of a category is to increase visibility in the
daily/weekly agenda --- i.e., to allow you to see which "group" an
item belongs to.

Apart from visibility and compartmentalization, categories do not add
much additional functionality to an item. It is certainly *not*
necessary to set them for every file and/or heading.

You can search for items by category in the agenda using the following
key sequence:

: C-c C-a m CATEGORY="birthdays"

In general, categories are *not* an efficient way of searching
for and/or filtering tasks. It is much faster to use [[#tag][tags]] or filetags
for this.

Here's one way to distinguish between categories and tags: an entry
can belong to only one category but it can have multiple tags.

* DEADLINE

#+index: DEADLINE!Definition

** Definition

A deadline is a special timestamp for indicating items that should be
performed by a certain time. Reminders about deadlines appear in your
agenda a specified number of days before they due.

** Details

You can add a deadline to a headline/entry by typing C-c C-d. You can
remove a deadline by typing C-u C-c C-d.

Here is the syntax for deadlines:

#+begin_src org
  ,* My big project
    DEADLINE: <2009-09-20 Sun>
#+end_src

You will be alerted of this deadline ahead of time when you select the
daily/weekly agenda (=C-c C-a a=).

:  index:      In   3 d.:  My big project

How soon the warning appears in your agenda is controlled by the
variable =org-deadline-warning-days=. The default number of days is 14.

The deadline will remain in your agenda (as an overdue item) until it
is marked done.

You can change the a warning period for a particular headline by
adding something like "-3d" (3 days) or "-2m" (two months) to the
timestamp:

#+begin_src org
  ,* My big project
    DEADLINE: <2009-09-20 Sun -2m>
#+end_src

** Uses

The obvious use of a deadline is to reminder yourself of tasks that
need to be completed by a certain date.

Deadlines can also be useful as an "advanced notice" system --- e.g.,
reminding yourself to prepare for an event or project.

You can add both a deadline and a scheduling timestamp to the same
entry.

* Docstring
  :PROPERTIES:
  :CUSTOM_ID: docstring
  :END:

#+index: Docstring!Definition

** Definition
A [[https://en.wikipedia.org/wiki/Docstring][docstring]] is the documentation written as part of a emacs lisp
variable or a function. It is part of Emacs' wonderful interactive
help system.

(Note: This definition is not org-mode specific, but is rather a more
general org-mode/lisp/coding concept. It's included here because
mailing list posts often reference a "docstring," an obscure phrase
for anyone not familiar with coding lingo.)

** Details and uses

If you are wondering what a particular org-mode key combination,
function, or variable does, the manual is not your only source of
information. Carsten has also embedded a wealth of resources into the
org-mode source code itself. These can be easily viewed using Emacs
built-in help functions.

For instance, let's say you want to learn more about creating a clock
report in org mode. One way to do this is to type =C-h k= or =M-x
describe-key= and then to enter the relevant key combination (=C-c
C-x-C-r=). This will provide the following very helpful information:

: org-clock-report is an interactive compiled Lisp function in
: `org-clock.el'.
:
: It is bound to C-c C-x C-r, <menu-bar> <Org> <Logging work> <Create
: clock table>.
:
: (org-clock-report &optional arg)
:
: Create a table containing a report about clocked time.
: If the cursor is inside an existing clocktable block, then the table
: will be updated.  If not, a new clocktable will be inserted.
: When called with a prefix argument, move to the first clock table in the
: buffer and update it.
:
: [back]

If you happened to know the name of the function, you could also
locate the same information using =C-h f= or =M-x describe-function=
and entering =org-clock-report=. Or you could use =C-h a= or
=apropos-command= to browse all functions that contain the words "org
clock".

Finally, if you want to learn more about variables, you can read their
docstrings by browsing the customize interface (=M-x customize-group
[RET] org=) or by typing =C-h v= or =M-x describe-variable=).

* Drawers
  :PROPERTIES:
  :CUSTOM_ID: drawer
  :END:

#+index: Drawers!Definition

** Definition

A drawer is a container that can hide information you don't want to
see during normal viewing and/or cycling of your outline.

** Details

A drawer looks like this:

#+begin_src org
  ,* Daily sleep log
    :LOGBOOK:
    - Note taken on [2009-09-16 Wed 04:02] \\
      Didn't sleep at all.
    - Note taken on [2009-09-15 Tue 05:25] \\
      Slept fitfully.
    - Note taken on [2009-09-14 Mon 09:30] \\
      Slept like a log.
    :END:
#+end_src

When you cycle the visibility of your outline, the contents of the
drawer will remain hidden.

#+begin_src org
  ,* Daily sleep log
      :LOGBOOK:
      :END:
#+end_src

The only way to view the contents is to press =TAB= directly on the
drawer.

If you want a new name for a drawer, such as :NOTES:, you must
customize the variable "org-drawers". Simply type =M-x
customize-variable [RET] org-drawers" and add a new label.

** Uses

By default, org-mode uses drawers to hide a variety of information,
such as [[#property][properties]] and clocked times.

But drawers are also quite useful for storing comments that you don't
want to see all the time. For instance, if you are writing a paper,
you might add a =:NOTE:= drawer to the variable =org-drawers=. Then
you can deposit any notes to yourself in such drawers. By default, the
information you put in drawers will not be exported to HTML, LaTeX,
etc.

* Entry
  :PROPERTIES:
  :CUSTOM_ID: entry
  :END:

#+index: Entry!Definition

** Definition

An entry is the basic unit of data in org-mode. It consists of a
[[#headline][headline]], metadata (tags, todo keyword, properties, priority, etc.),
and whatever other text it contains.

** Details

An entry is to be distinguished from a [[#tree][tree]], which consists of all
headlines and entries beneath a particular entry within the outline
structure. Entries nested within other entries form a tree.

Here is a sample entry with a lot of data:

#+begin_src org
  ,* TODO [#B] Headline                                                   :tags:
     :PROPERTIES:
     :DESCRIPTION: This is a sample property.
     :CATEGORY: documentation
     :CUSTOM_ID: an-extra-special-headline
     :END:

   And here is the text of an entry. You can put an unlimited amount of
   text in an entry!

   You can also add lists:

    - First item

    - Second item

    - Third item

   And tables:

   | Meal      | Food            | Calories |
   |-----------+-----------------+----------|
   | Breakfast | Eggs            |      500 |
   | Lunch     | Escargot        |      800 |
   | Dinner    | Bread and Water |      200 |
   |-----------+-----------------+----------|
   | Total     |                 |     1500 |
#+end_src

* Headline
  :PROPERTIES:
  :CUSTOM_ID: headline
  :END:

#+index: Headline!Definition

** Definition
A headline is the name for an outline heading in an org file.

** Details
Headlines begin with one or more asterisks.

#+begin_src org
  ,* A headline
#+end_src

The "level" of a headline corresponds to the number of asterisks. The more asterisks,
the deeper the level in the outline.

#+begin_src org
  ,***** A "level 5" outline heading
#+end_src

As are all outlines, org-files are organized hierarchically. Deeper
headlines are "children" of higher-level "parent" headlines (and can
"inherit" their properties). Headlines on the same level are known as
siblings.

#+begin_src org
  ,* A parent
  ,** A child
  ,*** Sibling one (also a child of "A child")
  ,*** Sibling two
  ,*** Sibling three
#+end_src

You can move headlines (and their corresponding [[#entry][entries]]) by using the
cursor keys in conjunction with the =Meta= key.

 - =M-Left= and =M-Right= move the headline horizontally (i.e., change
   its level).

   - The org documentation often uses the terms "promote" and "demote"
     for this action.

 - =M-Up= and =M-Down= move the headline vertically.

You can easily jump to another headline using =M-x org-goto= (=C-c
C-j=).

You can easily "refile" a headline in a different location using =M-x
org-refile= (=C-c C-w=).

** Uses

The basic use of headings, of course, is to distinguish separate
sections within your outline and to organize them hierarchically.

The other major use of headings is as TODO "items" that appear in your
agenda.

The power of org-mode lies in its treatment of headlines as
"containers" of information to which you can attach all sorts of data
([[#todo-keywords][todo keywords]], [[#tag][tags]], priorities, timestamps, [[#property][properties]], and an
unlimited amount of text). This turns org-mode's deceptively simple
outline structure into a powerful "database" of information, in which
units of data can be nested within one another.

* Inheritance
  :PROPERTIES:
  :CUSTOM_ID: inheritance
  :END:

#+index: Inheritance!Definition

** Definition

Inheritance is a term used to describe the way in which [[#entry][entries]] in a
[[#tree][tree]] can share the properties of their "parent" [[#headline][headlines]].

** Details

Org-mode takes full advantage of the hierarchical structure of
outlines by allowing lower level headlines to "inherit" (or share) the
properties of their parents.

The most common form of inheritance in org-mode is "[[https://orgmode.org/manual/Tag-inheritance.html][tag inheritance]]".
This is controlled by the variable org-use-tag-inheritance (true by
default). When turned on, lower level outline headings share the tags
of their parents. Thus in the following tree, all the headlines have
the tag "=:reading:=", even though it is only explicitly set for the
top level headline:

#+name: tag-inheritance-example
#+begin_src org
  ,* Summer reading list                                               :reading:
    DEADLINE: <1965-06-06 Sun>

  ,** /To Kill a Mockingbird/

  ,** /Catch 22/

  ,** /Herzog/
#+end_src

Some properties, such as [[#category][category]], are also inherited by default. See
[[https://orgmode.org/manual/Property-inheritance.html][the manual]] for more details.

** Uses

The most common use of tag inheritance is in agenda views and agenda
filtering. For instance, if you searched for the tag "reading" in your
agenda files, all of the headings in the [[tag-inheritance-example][example above]] would appear.

As a result it is easy to add a tag and/or category to a whole subtree
of items simply by adding a single tag to the parent headline.

Let's say for instance, that you want to designate a whole bunch of
tasks as belonging to the project "topsecret". By adding =:topsecret:=
to the top headline of the group, you are in effect labeling all the
items in the tree as "topsecret". An agenda search for the TODOs with
the tag "topsecret" (=C-c a M [RET] topsecret=) would then return any
active TODOs in the entire tree.

Another common use of inheritance is to allow a special setting (e.g.,
logging or archive location) to apply to an entire subtree.

Finally, inheritance plays an important role in org-mode's column
view.

* Property
  :PROPERTIES:
  :CUSTOM_ID: property
  :END:

#+index: Property!Definition

** Definition

A property is an arbitrary piece of "metadata" you can attach to an
entry. A property takes the form of a "data pair," which consists of
a key and its value.

** Details
Properties are stored in [[#drawer][drawers]] beneath a headline. Here is a sample
property drawer:

#+begin_src org
  ,* Invoice for fixing the toilet
     :PROPERTIES:
     :LOGGING:  lognoterepeat
     :BILLED: 102.13
     :BILLING_DATE: 2009-09-11
     :CLIENT:   ABC Company
     :END:
#+end_src

Though org-mode reserves a handful of property keys for special uses
(e.g., LOGGING in the example above), you are otherwise free to add
whatever property keys and values you'd like.

Though you can type properties by hand, the simplest way to add them
is to type =C-c C-x p= or =M-x org-set-property=.

** Uses

For new org users, properties can seem a bit puzzling. What exactly
are they for? Here are some of their uses:

   1. To specify settings for the local org-mode [[#tree][tree]].

      - For instance, though you may not normally want to be prompted
        for a note when you mark an item as DONE, you might want to
        make an exception for a particular task or project. To do so,
        you would set the LOGGING property to "lognotedone" in the
        relevant subtree.

   2. To create a small database of information.

      - The manual offers an nice example of this: [[https://orgmode.org/manual/Property-syntax.html#Property-syntax][keeping track
        of a information about a CD collection]].

      - Similarly, you might keep bibliographical information about
        books you've read in properties.

   3. To enter data that can be viewed as a "spreadsheet" in column view.

   4. To create more specific labels for headlines than generic tags allow.

      - For instance, if you are keeping track of expenses, you could
        put the type of expense in a tag, but then it would be mixed
        up with your other tags. A solution would be to create a
        special property (e.g., EXPENSE_TYPE) to hold the information.

   5. To label a particular tree with a unique ID so that it can be
      referenced easily via hyperlinks.

* Tag
  :PROPERTIES:
  :CUSTOM_ID: tag
  :END:

#+index: Tag!Definition

** Definition

A tag is a label (or piece of "metadata") that is attached to a
headline for easy identification and filtering later. Several tags can
be attached to the same headline.

** Details

Tags can be added to headlines with the key combination =C-c C-q= or
=C-c C-c=.

Tags have the following syntax:

#+begin_src org
  ,* A headline with tags                               :Richard:URGENT:errands:
#+end_src

You may be familiar with tags from blogs or sites like [[http://del.icio.us][del.icio.us]].
Tags are a way of labeling information without having to rely on a
rigid hierarchical structure. Unlike categories, you can give a
headline/entry multiple tags. In many ways, org-mode offers the best
of both worlds: the hierarchical organization of an outline and the
impromptu labeling of tags.

The entry above would appear in queries for any of the tags:
"Richard", "URGENT", or "errands".

The syntax for searching tags via the [[#agenda][agenda]] is quite simple. For
instance, you could create a targeted agenda search for all items
tagged "Richard" and "urgent".

: C-c a m Richard+URGENT

Or for items tagged Richard that are not urgent:

: C-c a m Richard-URGENT

You can also use sparse view searches to display all tags within a
particular org-file.

If you find yourself commonly using certain tags, you can create a
list of shortcuts for them by typing =M-x customize-variable [RET]
org-tags-alist=. You can also set special tags for a particular file.
See [[https://orgmode.org/manual/Setting-tags.html][the manual]] for more details.

** Uses

One common use of tags is as [[https://en.wikipedia.org/wiki/Getting_Things_Done#GTD_methodology][GTD contexts]]. You might, for instance,
define a list of tags in org-tags-alist that correspond to the various
contexts in a "next action" can be completed: @computer, @home,
@errands, @work, and so on. Then you can quickly filter for these tags
by pressing "=/=" in the agenda. See [[https://orgmode.org/manual/Agenda-commands.html#Agenda-commands][the manual]] for more details.

Another common use of a tag is to label a group of tasks as belonging
to a particular project or area of responsibility. For instance, you
might create a subtree in your file that contains all your house
repair projects and tag it with ":houserepair:". Let's say that when
Saturday rolls around, you decide to work exclusively on repairs.
Thanks to [[#inheritance][inheritance]], you can quickly locate all your tasks that
inherit the ":houserepair:" tag.

Here's what this would look like:

#+begin_src org
  ,* Tasks around the house                                        :houserepair:

  ,** TODO Fix sink

  ,** TODO Mow lawn

  ,** TODO Tear up carpet
#+end_src

Tags are also extremely useful for notetaking and research. You might,
for instance, create a file of reading notes in which each entry is a
snippet of information tagged with relevant keywords. The beauty of
org-mode is that these snippets can be easily rearranged within the
outline and yet remain easy to find via tags.

** Considerations: Tags vs. TODO keywords vs. Properties

One question that often emerges for new users of org mode is how to
decide when tags, [[#todo-keywords][TODO keywords]], or [[#property][properties]] are appropriate.

For instance, should you define your projects by creating a special
todo keyword for them (=PROJECT=) or by giving them a "=:project:="
tag? Similarly, should you create a TODO keyword for items that are
waiting, or should you add a "=:waiting:=" tag?

Either choice would be fine, of course, but here are a few
considerations to keep in mind:

1. Do you want quickly to filter for the item in the agenda view? If
   so, a tag is probably your best choice.

   - Note, you can add a setting to your .emacs that automatically
     adds a tag whenever you assign a particular TODO keyword. Type
     "=C-c v org-todo-state-tags-triggers=" for more information.

2. How visible do you want the keyword and/or tag to be? When viewing
   an org-mode file, TODO Keywords are highly visible, tags somewhat
   less so, and properties not at all.

3. Is the keyword part of your workflow? Do you want to be able to log
   information (such as a timestamp and a note) when you add or remove
   the keyword? If so, then use a TODO keyword.

   - An example: While a "waiting" tag might make it easier to filter
     for items in your todo list that are waiting/pending, a =WAITING=
     todo keyword would allow you to keep track of when an item
     entered the "waiting" state and when it left it.

   - Similarly, if you want to keep track of a sequence of actions on
     phone calls you receive, it would be relatively inefficient to
     add and remove tags to designate each stage. It would probably be
     better to set up a TODO sequence, such as ACT -> CALL -> MESSAGE
     -> FOLLOWUP -> etc.

* Tree (subtree)
  :PROPERTIES:
  :CUSTOM_ID: tree
  :END:

#+index: Tree!Definition
#+index: Subtree!Definition

** Definition

A tree is created by the structure of an outline. It consists of a
heading and all subheadings/entries beneath it within the outline
hierarchy.

** Details

A tree is to be distinguished from an [[#entry][entry]]. Whereas an entry
indicates only a single headline and its data, a tree consists of
multiple nested entries. And, of course, subtrees are nested within
larger trees.

* Todo Keywords
  :PROPERTIES:
  :CUSTOM_ID: todo-keywords
  :END:

#+index: Todo Keywords!Definition

** Definition

A TODO keyword is a small keyword at the beginning of a headline that
defines the TODO state of the entry.

** Details

The default TODO keywords in org-mode are TODO and DONE. They are
automatically given nice colors to make them stand out.

#+begin_src org
  ,* DONE Check cupboard to see if I'm out of bread
    CLOSED: [2009-09-16 Wed 13:14]
  ,* TODO Buy bread at the store
#+end_src

Org mode distinguishes between two types of keywords, active and
inactive (corresponding with the default TODO and DONE). By default,
active TODOs will be shown in [[#agenda][agenda views]]. Inactive todos will not be
shown.

You can select a TODO keyword by typing =C-c C-t= on an item. Or you
can move sequentially through TODOs by typing =Shift-Left= or
=Shift-Right=.

While the default keywords TODO and DONE will suffice for many users,
you can define your own TODO keywords (such as PROJECT, WAITING,
etc.) by following the instructions in the manual:

- https://orgmode.org/manual/TODO-items.html

** Uses
:PROPERTIES:
:ID:       e0f76b6c-411f-4df1-88f5-445e11d9ca1d
:END:

Not surprisingly, the most common use of TODO keywords is to indicate
items in your outline files that require action. Where other task
management systems often separate notes and todos, org-mode allows you
to mark items in your notes as TODOs.

Another common use of TODO keywords is to follow a single item through
an extended workflow. For instance, you might create a special TODO
keyword sequence for invoices by placing the following at the top of
your org file:

#+begin_src org
  ,#+SEQ_TODO: INVOICE(i) MAIL(m) WAITING(w) FOLLOWUP(f) | RECEIVED(r)
#+end_src

Note: The "|" separates active from inactive todos.

You can combine such todo sequences with logging in order to keep a
record of when each event in the sequence happened.

* TODO Awaiting definitions
** Agenda filtering

#+index: Agenda filtering!Definition

** CLOCK

#+index: Clock!Definition

** Column view

#+index: Column view!Definition

** Cycling

#+index: Cycling!Definition

** Effort estimate

#+index: Effort estimate!Definition

** Filetag

#+index: Filetag!Definition

** Project

#+index: Project!Definition

** Note

#+index: Note!Definition

** List

#+index: List !Definition

** Level

#+index: Level!Definition

** Logging

#+index: Logging!Definition

** SCHEDULED

#+index: SCHEDULED!Definition

** Restriction lock
  :PROPERTIES:
  :CUSTOM_ID: file-restriction
  :END:
# roklein AT roklein DOT de: is this the right place for the tag?
#+index: Restriction lock!Definition

** Table

#+index: Table!Definition

** Timestamp

#+index: Timestamp!Definition