d6135afda0d4bfc3b00d74577236f5e97f169abc
[worg.git] / org-contrib / org-index.org
1 #+OPTIONS:    H:3 num:nil toc:t \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 lognotestate
3 #+TITLE:      org-index.el --- A personal index for org and beyond
4 #+AUTHOR:     Marc-Oliver Ihm
5 #+EMAIL:      org-index@ferntreffer.de
6 #+LANGUAGE:   en
7 #+CATEGORY:   worg-tutorial
8
9 * Introduction and Overview
10
11   org-index helps you to create an index table of favorite locations and
12   references, keeping the most frequently visited lines right at the top.
13
14   Or, citing from its documentation:
15
16 #+BEGIN_EXAMPLE
17
18   Mark and find your favorite org-locations and other things easily:
19   Create and update a lookup table of references and links. Frequently
20   used entries bubble to the top. Entering some keywords narrows down the
21   displayed results to matching entries only, so that the right one can
22   be spotted easily.
23
24   References are essentially small numbers (e.g. "R237" or "-455-"),
25   which are created by this package; they are well suited to be used
26   outside org. Links are normal org-mode links.;;
27
28 #+END_EXAMPLE
29
30   org-index helps to find a selected set of org-nodes and other things easily;
31   you may see it as your private, adaptive index or search engine; it can be
32   used inside and outside of org.
33
34 * Three scenarios of typical usage
35
36   See also [[id:7ab63909-1f2a-4131-ae5c-f30a53f840c9][A working example]] for complete examples, that you can readily try out.
37
38 ** Taking notes in a meeting
39
40    Lets say, you have a meeting for a project for which you already have a
41    node in org-mode. Now as the meeting starts, you want to go to that
42    node, open it an start taking notes. However, the process of finding
43    that node takes too long and you want to accelerate it.
44
45    For this, use org-index and create a line for this meeting in your
46    index table. This line contains a link to the node, where you want
47    to take your meeting-notes and additionally some keywords that you
48    associate with this meeting (e.g. its name).
49
50    Next time, that you want to find this node, simply:
51
52    - Invoke org-index with a keystroke (typically "C-+") and choose the
53      command "occur" (see [[id:940a8103-55a1-4d72-9d56-6ee6851c46ec][The commands of org-index]] for a list of
54      commands and their description).
55    - Type one or more keywords, specific for the project.
56    - From the list of results, choose the entry you are looking for.
57      - Remark: Your entry will probably appear at the top of the list,
58        because this list is sorted by frequency of usage.
59    - Type RET to go to this entry and start taking notes.
60    
61    This might or might not be faster, than finding your node by navigating the
62    outline hierarchy around it.
63
64
65 ** Finding the right folder for incoming mail
66    
67    This assumes that, in your mail program, you have created folders for
68    your favorite projects. An example would be an email folder for a
69    project "R624 Moving to a new internet provider". "R624" in this example
70    is a reference; see [[id:da8b6a60-5b02-4fa6-81de-8a3d9dee0267][References]] for an explanation.
71
72    Now, when a new mail arrives for this project, you may follow these
73    steps to find the correct folder:
74
75    - Invoke org-index with a keystroke (typically "C-+") and choose the
76      command "occur".
77    - Type a keyword (e.g. "internet").
78    - From the list of results, it is easy to spot the right reference
79      ("R624"); more frequent used entries appear at the top.
80    - With this reference it is easy to find the associated folder within
81      your email-client (assuming, that folders in your email program are
82      sorted alphabetically).
83
84    This works, because references, like "R624", can easily be used within
85    the names of email-folders.
86    
87 ** Marking printed documents with references
88
89    By paper mail or in a meeting you receive a printed document. You
90    want to associate it with a certain project and store it away for
91    later. You could proceed like this:
92
93    - Invoke org-index with a keystroke (typically "C-+") and choose the
94      command "ref", which gives you a new reference (e.g. "R237"). Type
95      some keywords into this new line within your index table.
96    - If you want, you may also record the location, where you keep the document.
97    - Now, take a pen and write down this reference "R237" onto the printed
98      document.
99
100    Some day later, you might want to read the document again and wonder,
101    where you have stored it:
102
103    - Invoke org-index and choose the command "occur".
104    - Enter some keywords for this document; they should overlap with
105      those, that you entered when creating the line within the index table.
106    - You see the matching lines from your index table, pick the right one and
107      read the location information, that you recorded initially.
108
109    Later again, you might find this document in one of your desk drawers and
110    ask yourself, which project it is associated with. For an answer, you just
111    need the handwritten reference "R237" from the document:
112
113    - Invoke org-index and choose the command "goto".
114    - Enter the reference number "237".
115    - This brings you to the matching line within your index table, where you
116      can read, what you have entered previously.
117    - If your want to visit the org-mode node itself (and not only its line in
118      the index table), invoke org-index again and choose "head".
119
120    This shows, how org-index might help to bridge the gap between
121    org-mode and the paper-world.
122
123 * Some concepts of org-index
124 ** References
125    :PROPERTIES:
126    :ID:       da8b6a60-5b02-4fa6-81de-8a3d9dee0267
127    :END:
128
129    References (as used within org-index) are small numbers with
130    decorations; examples are "R237", "-455-" or "#323#". You are free, to
131    choose the text before or after the number; org-index inspects the
132    already existing references and creates new references along the same
133    lines. So the next reference after "R237" would be "R238".
134
135    References are meant to be easy to type, to write down and remember; you
136    can use them everywhere (not only within org !), where you want to refer to
137    a line within your index table. You may also store additional information
138    Within your index table, e.g. remarks or links to org-mode nodes.
139
140 ** The index table
141
142    The index table keeps all your references and links; it counts, how often
143    they have been used. Additionally it also records the date of creation and
144    last access. Moreover it is highly useful to keep some description or a set
145    of keywords within your index table, which can then be searched with the
146    command "occur".
147
148    You do not need to create your index table by hand. Just invoke org-index,
149    which will create a new table from your input.
150
151    Further down below there is [[id:62e632e9-38ff-4210-acd5-133d7b13db07][A working example]]; here is the actual table from
152    this example:
153
154 #+BEGIN_EXAMPLE
155
156    |     | Type    | description    | Keywords       |         |      |                 |                       |
157    | Ref |         | ;c             |                | count;s | link | created         | last-accessed         |
158    |     |         |                |                |         | <4>  |                 |                       |
159    |-----+---------+----------------+----------------+---------+------+-----------------+-----------------------|
160    | R2  | project | bar            | support, legal |       8 |      | [2012-12-07 Fr] | [2013-03-16 Sa 10:24] |
161    | R3  | paper   | printed report |                |       3 |      | [2012-12-04 Di] | [2013-03-15 Fr 22:07] |
162    | R5  | project | baz            | financial      |       5 |      | [2012-12-05 Mi] | [2012-12-08 Sa 23:03] |
163    | R6  | project | qux            | sport          |       3 |      | [2012-12-08 Sa] | [2012-12-08 Sa 23:01] |
164    | R1  | project | foo            | support        |       3 |      | [2012-12-03 Mo] | [2013-03-15 Fr 19:26] |
165    | R4  | folder  | directory      |                |       2 |      | [2012-12-08 Sa] | [2012-12-08 Sa 23:04] |
166
167 #+END_EXAMPLE
168    
169 ** Links
170
171    org-index also supports links, which are just normal org-mode links as
172    described in the documentation of org-mode.
173
174 * Installation and setup
175   :PROPERTIES:
176   :ID:       8ac78731-6c7d-432e-901f-741a804236b6
177   :END:
178
179   Please note, that the working example below brings its own, non-permanent
180   setup instructions: [[id:579ca3fc-1b42-4f0b-adde-e52f8d495fe0][Setting up things for this example]]
181
182   If, however, you want to install org-index permanently, just read on.
183
184 ** Obtaining
185
186    An older version of org-index.el carried the name org-index.el. It comes
187    as a contributed package of org and can be found within the
188    contrib-directory.
189
190    However, the latest version (which e.g. comes with a setup assistant) is
191    recommended and can be downloaded from:
192
193    http://orgmode.org/worg/code/elisp/org-index.el
194
195    You should put this file into one of the directories within your load-path.
196
197 ** Modifying your .emacs
198
199    Citing from org-index own documentation:
200
201 #+BEGIN_EXAMPLE
202
203 Setup:
204
205  - Add these lines to your .emacs:
206
207    (require 'org-index)
208
209    ;; Optionally assign a key. Pick your own.
210    (global-set-key (kbd "C-+") 'org-index)
211
212  - Invoke `org-index', which will assist you to create your 
213    index table.
214
215  - Do not forget to restart emacs to make these lines effective.
216
217 #+END_EXAMPLE
218
219    Thats it. You may now invoke org-index. Or read below first, to learn what
220    will happen.
221    
222 ** Let the builtin assistent create your index table
223
224    When you invoke org-index for the first time, it will notice, that the
225    index table needs to be created first. For that goal the builtin assistant
226    will ask you some questions (like the location of your index table and the
227    name of its node).
228
229    Afterwards you will be dropped within the newly created node, where you may
230    read the notes explaining its structure.
231
232 * A working example
233   :PROPERTIES:
234   :ID:       7ab63909-1f2a-4131-ae5c-f30a53f840c9
235   :END:
236
237   This node contains a simple setup, which can be used to explore
238   org-index. Further below there is also [[id:848c6d2a-6e8b-4c93-8481-19e6db7e6ca8][A sample for an index table]].
239
240   These examples revolve around the few most common usecases and only
241   employ a very limited set of commands (mainly "occur" and "ref"). Below
242   at [[id:940a8103-55a1-4d72-9d56-6ee6851c46ec][The commands of org-index]] you will find much more commands
243   (e.g. "sort" or "highlight") that become quite helpful, once you have
244   mastered the basic functionality.
245
246 ** Setting up things for this example
247    :PROPERTIES:
248    :ID:       579ca3fc-1b42-4f0b-adde-e52f8d495fe0
249    :END:
250
251    To really try out the things described here, you need to go through some
252    minimal preperations: Open two files in your browser, copy-and-paste
253    them into emacs and execute two lines of elisp-code.
254
255    These instructions are non-permanent; after your next emacs restart you
256    wont be able to use org-index. To install it permanently follow
257    these instructions: [[id:8ac78731-6c7d-432e-901f-741a804236b6][Installation and setup]], which are quite easy to follow.
258    
259 *** Get org-index.org
260
261     Read this text within org-mode in emacs, especially to have all the
262     org-mode nodes, that are used in this example.  Reading this text in a
263     browser is still instructive but does not give you the full hands-on
264     experience. So, if you are reading the browser-version of
265     org-index.org, open:
266
267     http://orgmode.org/worg/org-contrib/org-index.org
268
269     in your browser. Mark the whole page and copy-and-paste it into your
270     emacs: Create a new buffer "org-index.org", do "M-x org-mode" and
271     paste. Continue reading within this new emacs-buffer.
272
273 *** Get org-index.el
274
275     Open
276
277     http://orgmode.org/worg/code/elisp/org-index.el
278   
279     in your browser. Mark the whole page and copy-and-paste it into your
280     emacs: Create a new buffer "org-index.el", do "M-x emacs-lisp-mode"
281     and paste.
282
283     To make emacs read and evaluate the the elisp-code you need to "M-x
284     eval-buffer" within the new buffer.
285
286 *** Configuration
287
288     Finally, you have to execute two lines of elisp: place your cursor at
289     the end of each line and type "C-x C-e" (which runs "eval-last-sexp").
290
291 #+BEGIN_EXAMPLE
292
293     (setq org-index-id "848c6d2a-6e8b-4c93-8481-19e6db7e6ca8")
294     (global-set-key (kbd "C-+") 'org-index)
295
296 #+END_EXAMPLE
297
298 ** First example: Finding a node by its name
299
300    Say, your are in a meeting about project "bar" and want to take
301    notes. For this you need to visit the node for project "bar".
302
303    Type "C-+" to invoke org-index and then type "bar" and RET. This will
304    create a new buffer named *org-index-occur* with one line:
305
306 #+BEGIN_EXAMPLE
307
308    | R2 | project | bar | support, legal | 8 |   | [2012-12-07 Fr] | [2012-12-08 Sa 23:37] |
309
310 #+END_EXAMPLE
311
312    Now, to visit the node with the reference R2, move the cursor onto this
313    line and type RET. This will also increment the count of this line
314    within the index table from 8 to 9, giving it a higher rank in future
315    searches.
316
317    This search resembles emacs classical occur-feature (whence its name);
318    however, it is incremental: If you are not satisfied with the results of
319    your initial search, you may correct your search term anytime by
320    deleting characters or typing new ones. Your content of the occur-buffer
321    will change accordingly after each character.
322
323    Remark: even though the initial prompt of org-index offers only a
324    fixed set of choices, you may just as well type something else
325    (e.g. "bar") to implicitly accept the first choice (here: "occur").
326
327 ** Secound example: Finding a node by keyword
328
329    Later you want to take some notes for project "bar" but do not recall
330    its name. However, you know that the project is related with "support".
331
332    So you type "C-+" to invoke org-index. Then type "support" and RET.
333
334    After this you will see these two lines (R2 and R1) from your index table,
335    which contain the keyword "support":
336
337 #+BEGIN_EXAMPLE
338
339    | R2 | project | bar | support, legal | 8 |   | [2012-12-07 Fr] | [2012-12-08 Sa 23:37] |
340    | R1 | project | foo | support        | 3 |   | [2012-12-03 Mo] |                       |
341
342 #+END_EXAMPLE
343    
344    The first line "R2" is the one with the highest access count (8),
345    because the table is kept sorted for this. And this is already your
346    project "bar".  Now just need to hit RET, to visit this node.
347
348 ** Third example: Find the right folder for an incoming mail
349
350    This example assumes, that within your email-client you have organised
351    messages in folders, the names of which start with a reference, 
352    e.g. "R2 bar". 
353
354    Compared to the straightforward approach of naming the folder just
355    "bar", the overhead related with including the reference within the name
356    allows you to use org-index as your search-engine for email-folders.
357
358    This is especially helpful, if you have dozens or even hundreds of
359    folders, too many to spot the right one easily.
360
361    Moreover, if you later need to rename your project from "bar" to "qux",
362    the reference can be left unchanged and your mail folder appears at its
363    usual place.
364
365    Now you get an email related to project "bar" and want to put it into
366    the right folder.
367
368    So you type "C-+" to invoke org-index and then "bar" and RET.
369
370    Just as in the first example, this is what you get:
371
372 #+BEGIN_EXAMPLE
373
374    | R2 | project | bar | support, legal | 8 |   | [2012-12-07 Fr] | [2012-12-08 Sa 23:37] |
375
376 #+END_EXAMPLE
377
378    From this line you can easily spot the reference "R2" and find the
379    right folder in your email-client.
380
381 ** Fourth example: Create a new reference for a new piece of paper
382
383    In a meeting, you get handed a printout; a discussion starts and
384    you want to keep track of it. And within your org-mode notes you want to
385    refer to the printout, that is the focus of the discussion.
386
387    For this you can create a new reference: Type "C-+" to invoke
388    org-index and then "ref" and RET.
389
390    This will create a new row within your table of favorites with a new
391    reference already filled in (if you try it out yourself, it will
392    probably be "R7"). Now, you can fill out the other columns, especially
393    description and keywords. 
394
395    The new reference (e.g. "R7") should then be written onto the printout,
396    so that later (see the next example) you will be able to look it up.
397    
398    Once you are done, leave the index table by typing "C-+" and "leave" RET.
399
400    Remark: The closely related example below assumes reference "R3"; it is
401    just as good as "R7".
402
403 ** Fifth example: Looking up a reference you find on a piece of paper
404
405    Lets assume, that in one of your drawers you find a lengthy printout. On
406    its cover page you spot the handwritten reference "R3".
407    
408    Remark: If you worked throught the example above, you have created a new
409    reference "R7"; it is just as good as "R3".
410
411    First you would like to know the date, when you received this
412    document. For this, simply type "C-+", then "3" and RET.
413
414    As a result you will see something similar to the lines below: 
415
416    continue here 
417
418 #+BEGIN_EXAMPLE
419
420 9 matches total for "\bR-3\b":
421 9 matches in buffer: org-index.org
422     160:   | R-3  | paper   | printed report |                |       3 |      | [2012-12-04 Di] | [2013-03-15 Fr 22:07] |
423     399:   Remark: The closely related example below assumes reference "R-3"; it is
424     405:   its cover page you spot the handwritten reference "R-3".
425     408:   reference "R7"; it is just as good as "R-3".
426     428:   Which is a multi-occur for reference "R-3". 
427     430:   Please note, that in the cited example output above, the reference "R-3"
428     435:   reference "R-3"; that way it should be easy, to find your org-mode notes
429     446:    - [ ] Read paper R-3
430     474:   | R-3  | paper   | printed report |                |5|      | [2012-12-04 Di] | [2013-07-27 Sa 21:51]                      |
431
432 #+END_EXAMPLE
433
434    Which is a multi-occur for reference "R3". 
435
436    Please note, that in the cited example output above, the reference "R3"
437    has been replaced with "R-3". This avoids, that this citation itself
438    appears in your output again, if you try the example yourself.
439
440    The output tells you, where in all your org-mode files, you have used
441    reference "R3"; that way it should be easy, to find your org-mode notes
442    about this paper. The list also includes the matching line from your
443    index table, which tells you, when this reference has once been created.
444
445 ** Example nodes 
446
447    The subnodes below are made up to be used within the examples
448    above. Their contents is therefore fictous.
449   
450 *** TODO R1 Project foo
451
452     - [ ] Read paper R3
453
454 *** TODO R2 Project bar
455
456     - [ ] Talk to Jim
457
458 *** DONE R5 Project baz
459     CLOSED: [2012-12-08 Sa 23:01]
460
461      - [X] Clean up directory R4
462
463 *** TODO R6 Project qux
464
465     - [ ] Clean running shoes
466
467 ** A sample for an index table
468    :PROPERTIES:
469    :ID:       848c6d2a-6e8b-4c93-8481-19e6db7e6ca8
470    :END:
471
472 #+BEGIN_EXAMPLE
473
474    |     | Type    | description    | Keywords       |         |      |                 |                       |
475    | Ref |         | ;c             |                | count;s | link | created         | last-accessed         |
476    |     |         |                |                |         | <4>  |                 |                       |
477    |-----+---------+----------------+----------------+---------+------+-----------------+-----------------------|
478    | R2  | project | bar            | support, legal |       8 |      | [2012-12-07 Fr] | [2013-03-16 Sa 10:24] |
479    | R3  | paper   | printed report |                |       3 |      | [2012-12-04 Di] | [2013-03-15 Fr 22:07] |
480    | R5  | project | baz            | financial      |       5 |      | [2012-12-05 Mi] | [2012-12-08 Sa 23:03] |
481    | R6  | project | qux            | sport          |       3 |      | [2012-12-08 Sa] | [2012-12-08 Sa 23:01] |
482    | R1  | project | foo            | support        |       3 |      | [2012-12-03 Mo] | [2013-03-15 Fr 19:26] |
483    | R4  | folder  | directory      |                |       2 |      | [2012-12-08 Sa] | [2012-12-08 Sa 23:04] |
484
485 #+END_EXAMPLE
486
487 * The commands of org-index
488   :PROPERTIES:
489   :ID:       940a8103-55a1-4d72-9d56-6ee6851c46ec
490   :END:
491
492   When you invoke org-index, it prompts you to choose one from a
493   set of commands:
494   
495 #+BEGIN_EXAMPLE
496
497   occur: Incremental search, that after each keystroke shows
498     matching lines from index table. You may enter a list of words
499     seperated by comma (\",\"), to select lines that contain all
500     of the given words.
501
502     If you supply a number (e.g. \"237\"): Apply emacs standard
503     multi-occur operation on all org-mode buffers to search for
504     this specific reference.
505
506     You may also read the note at the end of this help on saving
507     the keystroke RET with this frequent default command.
508
509   head: If invoked outside the index table, ask for a
510     reference number and search for a heading containing it. If
511     invoked within index table dont ask; rather use the reference or
512     link from the current line.
513
514   ref: Create a new reference, copy any previously selected text.
515     If already within index table, fill in ref-column.
516
517   link: Create a new line in index table with a link to the
518     current node.  Do not populate the ref column; this can later
519     be populated by calling the \"fill\" command from within the
520     index table.
521
522   leave: Leave the index table. If the last command has
523     been \"ref\", the new reference is copied and ready to yank.
524     This \"org-mark-ring-goto\" and can be called several times
525     in succession. If you invoke org-index with a prefix argument,
526     this command \"leave\" is executed without further questions.
527
528   enter: Just enter the node with the index table.
529
530   goto: Search for a specific reference within the index table.
531
532   help: Show this text.
533
534   +: Show all commands including the less frequently used ones
535     given below. If \"+\" is followd by enough letters of such a
536     command (e.g. \"+fi\"), then this command is invoked
537     directly.
538
539   reorder: Temporarily reorder the index table, e.g. by
540     count, reference or last access.
541
542   fill: If either ref or link is missing, fill it.
543
544   sort: Sort a set of lines (either the active region or the
545     whole buffer) by the references found in each line.
546
547   update: For the given reference, update the line in the
548     index table.
549
550   highlight: Highlight references in region or buffer.
551
552   unhighlight: Remove highlights.
553
554   missing : Search for missing reference numbers (which do not
555     appear in the reference table). If requested, add additional
556     lines for them, so that the command \"ref\" is able to reuse
557     them.
558
559   statistics : Show some statistics (e.g. minimum and maximum
560     reference) about index table.
561
562 #+END_EXAMPLE
563
564   Please note, that you are not required to explicitly choose one. Simply
565   typing something else (e.g. "237") accepts the default-command and
566   supplies your input as an argument.
567   
568 * Further Reading, Version, Contact
569
570   org-index.el itself contains embedded documentation, which can be
571   easily accessed through the command "help".  Most, but not all of it has
572   already been cited within this document.
573
574
575   As of [2013-06-23 So] this document describes version 2.3 of org-index.
576
577
578   Remaining questions can be sent to: 
579
580     org-index@ferntreffer.de
581
582   I will try to help.
583