updated org-index.org to reflect the new location of org-index.el
[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@2484.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    org-index.el comes as a contributed package of org and can be found within
187    the contrib-directory.
188
189    You should put the file into one of the directories within your load-path,
190    or make the contrib-directory part of your load-path.
191
192 ** Modifying your .emacs
193
194    Citing from org-index own documentation:
195
196 #+BEGIN_EXAMPLE
197
198 Setup:
199
200  - Add these lines to your .emacs:
201
202    (require 'org-index)
203
204    ;; Optionally assign a key. Pick your own.
205    (global-set-key (kbd "C-+") 'org-index)
206
207  - Invoke `org-index', which will assist you to create your 
208    index table.
209
210  - Do not forget to restart emacs to make these lines effective.
211
212 #+END_EXAMPLE
213
214    Thats it. You may now invoke org-index. Or read below first, to learn what
215    will happen.
216    
217 ** Let the builtin assistent create your index table
218
219    When you invoke org-index for the first time, it will notice, that the
220    index table needs to be created first. For that goal the builtin assistant
221    will ask you some questions (like the location of your index table and the
222    name of its node).
223
224    Afterwards you will be dropped within the newly created node, where you may
225    read the notes explaining its structure.
226
227 * A working example
228   :PROPERTIES:
229   :ID:       7ab63909-1f2a-4131-ae5c-f30a53f840c9
230   :END:
231
232   This node contains a simple setup, which can be used to explore
233   org-index. Further below there is also [[id:848c6d2a-6e8b-4c93-8481-19e6db7e6ca8][A sample for an index table]].
234
235   These examples revolve around the few most common usecases and only
236   employ a very limited set of commands (mainly "occur" and "ref"). Below
237   at [[id:940a8103-55a1-4d72-9d56-6ee6851c46ec][The commands of org-index]] you will find much more commands
238   (e.g. "sort" or "highlight") that become quite helpful, once you have
239   mastered the basic functionality.
240
241 ** Setting up things for this example
242    :PROPERTIES:
243    :ID:       579ca3fc-1b42-4f0b-adde-e52f8d495fe0
244    :END:
245
246    To really try out the things described here, you need to go through some
247    minimal preperations: Open two files in your browser, copy-and-paste
248    them into emacs and execute two lines of elisp-code.
249
250    These instructions are non-permanent; after your next emacs restart you
251    wont be able to use org-index. To install it permanently follow
252    these instructions: [[id:8ac78731-6c7d-432e-901f-741a804236b6][Installation and setup]], which are quite easy to follow.
253    
254 *** Get org-index.org
255
256     Read this text within org-mode in emacs, especially to have all the
257     org-mode nodes, that are used in this example.  Reading this text in a
258     browser is still instructive but does not give you the full hands-on
259     experience. So, if you are reading the browser-version of
260     org-index.org, open:
261
262     http://orgmode.org/worg/org-contrib/org-index.org
263
264     in your browser. Mark the whole page and copy-and-paste it into your
265     emacs: Create a new buffer "org-index.org", do "M-x org-mode" and
266     paste. Continue reading within this new emacs-buffer.
267
268 *** Eval org-index.el
269
270     Open org-index.el from the contrib-directory of your org-installation.
271   
272     To make emacs read and evaluate the the elisp-code you need to say "M-x
273     eval-buffer" within the new buffer.
274
275 *** Configuration
276
277     Finally, you have to execute two lines of elisp: place your cursor at
278     the end of each line and type "C-x C-e" (which runs "eval-last-sexp").
279
280 #+BEGIN_EXAMPLE
281
282     (setq org-index-id "848c6d2a-6e8b-4c93-8481-19e6db7e6ca8")
283     (global-set-key (kbd "C-+") 'org-index)
284
285 #+END_EXAMPLE
286
287 ** First example: Finding a node by its name
288
289    Say, your are in a meeting about project "bar" and want to take
290    notes. For this you need to visit the node for project "bar".
291
292    Type "C-+" to invoke org-index and then type "bar" and RET. This will
293    create a new buffer named *org-index-occur* with one line:
294
295 #+BEGIN_EXAMPLE
296
297    | R2 | project | bar | support, legal | 8 |   | [2012-12-07 Fr] | [2012-12-08 Sa 23:37] |
298
299 #+END_EXAMPLE
300
301    Now, to visit the node with the reference R2, move the cursor onto this
302    line and type RET. This will also increment the count of this line
303    within the index table from 8 to 9, giving it a higher rank in future
304    searches.
305
306    This search resembles emacs classical occur-feature (whence its name);
307    however, it is incremental: If you are not satisfied with the results of
308    your initial search, you may correct your search term anytime by
309    deleting characters or typing new ones. Your content of the occur-buffer
310    will change accordingly after each character.
311
312    Remark: even though the initial prompt of org-index offers only a
313    fixed set of choices, you may just as well type something else
314    (e.g. "bar") to implicitly accept the first choice (here: "occur").
315
316 ** Secound example: Finding a node by keyword
317
318    Later you want to take some notes for project "bar" but do not recall
319    its name. However, you know that the project is related with "support".
320
321    So you type "C-+" to invoke org-index. Then type "support" and RET.
322
323    After this you will see these two lines (R2 and R1) from your index table,
324    which contain the keyword "support":
325
326 #+BEGIN_EXAMPLE
327
328    | R2 | project | bar | support, legal | 8 |   | [2012-12-07 Fr] | [2012-12-08 Sa 23:37] |
329    | R1 | project | foo | support        | 3 |   | [2012-12-03 Mo] |                       |
330
331 #+END_EXAMPLE
332    
333    The first line "R2" is the one with the highest access count (8),
334    because the table is kept sorted for this. And this is already your
335    project "bar".  Now just need to hit RET, to visit this node.
336
337 ** Third example: Find the right folder for an incoming mail
338
339    This example assumes, that within your email-client you have organised
340    messages in folders, the names of which start with a reference, 
341    e.g. "R2 bar". 
342
343    Compared to the straightforward approach of naming the folder just
344    "bar", the overhead related with including the reference within the name
345    allows you to use org-index as your search-engine for email-folders.
346
347    This is especially helpful, if you have dozens or even hundreds of
348    folders, too many to spot the right one easily.
349
350    Moreover, if you later need to rename your project from "bar" to "qux",
351    the reference can be left unchanged and your mail folder appears at its
352    usual place.
353
354    Now you get an email related to project "bar" and want to put it into
355    the right folder.
356
357    So you type "C-+" to invoke org-index and then "bar" and RET.
358
359    Just as in the first example, this is what you get:
360
361 #+BEGIN_EXAMPLE
362
363    | R2 | project | bar | support, legal | 8 |   | [2012-12-07 Fr] | [2012-12-08 Sa 23:37] |
364
365 #+END_EXAMPLE
366
367    From this line you can easily spot the reference "R2" and find the
368    right folder in your email-client.
369
370 ** Fourth example: Create a new reference for a new piece of paper
371
372    In a meeting, you get handed a printout; a discussion starts and
373    you want to keep track of it. And within your org-mode notes you want to
374    refer to the printout, that is the focus of the discussion.
375
376    For this you can create a new reference: Type "C-+" to invoke
377    org-index and then "ref" and RET.
378
379    This will create a new row within your table of favorites with a new
380    reference already filled in (if you try it out yourself, it will
381    probably be "R7"). Now, you can fill out the other columns, especially
382    description and keywords. 
383
384    The new reference (e.g. "R7") should then be written onto the printout,
385    so that later (see the next example) you will be able to look it up.
386    
387    Once you are done, leave the index table by typing "C-+" and "leave" RET.
388
389    Remark: The closely related example below assumes reference "R3"; it is
390    just as good as "R7".
391
392 ** Fifth example: Looking up a reference you find on a piece of paper
393
394    Lets assume, that in one of your drawers you find a lengthy printout. On
395    its cover page you spot the handwritten reference "R3".
396    
397    Remark: If you worked throught the example above, you have created a new
398    reference "R7"; it is just as good as "R3".
399
400    First you would like to know the date, when you received this
401    document. For this, simply type "C-+", then "3" and RET.
402
403    As a result you will see something similar to the lines below: 
404
405    continue here 
406
407 #+BEGIN_EXAMPLE
408
409 9 matches total for "\bR-3\b":
410 9 matches in buffer: org-index.org
411     160:   | R-3  | paper   | printed report |                |       3 |      | [2012-12-04 Di] | [2013-03-15 Fr 22:07] |
412     399:   Remark: The closely related example below assumes reference "R-3"; it is
413     405:   its cover page you spot the handwritten reference "R-3".
414     408:   reference "R7"; it is just as good as "R-3".
415     428:   Which is a multi-occur for reference "R-3". 
416     430:   Please note, that in the cited example output above, the reference "R-3"
417     435:   reference "R-3"; that way it should be easy, to find your org-mode notes
418     446:    - [ ] Read paper R-3
419     474:   | R-3  | paper   | printed report |                |5|      | [2012-12-04 Di] | [2013-07-27 Sa 21:51]                      |
420
421 #+END_EXAMPLE
422
423    Which is a multi-occur for reference "R3". 
424
425    Please note, that in the cited example output above, the reference "R3"
426    has been replaced with "R-3". This avoids, that this citation itself
427    appears in your output again, if you try the example yourself.
428
429    The output tells you, where in all your org-mode files, you have used
430    reference "R3"; that way it should be easy, to find your org-mode notes
431    about this paper. The list also includes the matching line from your
432    index table, which tells you, when this reference has once been created.
433
434 ** Example nodes 
435
436    The subnodes below are made up to be used within the examples
437    above. Their contents is therefore fictous.
438   
439 *** TODO R1 Project foo
440
441     - [ ] Read paper R3
442
443 *** TODO R2 Project bar
444
445     - [ ] Talk to Jim
446
447 *** DONE R5 Project baz
448     CLOSED: [2012-12-08 Sa 23:01]
449
450      - [X] Clean up directory R4
451
452 *** TODO R6 Project qux
453
454     - [ ] Clean running shoes
455
456 ** A sample for an index table
457    :PROPERTIES:
458    :ID:       848c6d2a-6e8b-4c93-8481-19e6db7e6ca8
459    :END:
460
461 #+BEGIN_EXAMPLE
462
463    |     | Type    | description    | Keywords       |         |      |                 |                       |
464    | Ref |         | ;c             |                | count;s | link | created         | last-accessed         |
465    |     |         |                |                |         | <4>  |                 |                       |
466    |-----+---------+----------------+----------------+---------+------+-----------------+-----------------------|
467    | R2  | project | bar            | support, legal |       8 |      | [2012-12-07 Fr] | [2013-03-16 Sa 10:24] |
468    | R3  | paper   | printed report |                |       3 |      | [2012-12-04 Di] | [2013-03-15 Fr 22:07] |
469    | R5  | project | baz            | financial      |       5 |      | [2012-12-05 Mi] | [2012-12-08 Sa 23:03] |
470    | R6  | project | qux            | sport          |       3 |      | [2012-12-08 Sa] | [2012-12-08 Sa 23:01] |
471    | R1  | project | foo            | support        |       3 |      | [2012-12-03 Mo] | [2013-03-15 Fr 19:26] |
472    | R4  | folder  | directory      |                |       2 |      | [2012-12-08 Sa] | [2012-12-08 Sa 23:04] |
473
474 #+END_EXAMPLE
475
476 * The commands of org-index
477   :PROPERTIES:
478   :ID:       940a8103-55a1-4d72-9d56-6ee6851c46ec
479   :END:
480
481   When you invoke org-index, it prompts you to choose one from a
482   set of commands:
483   
484 #+BEGIN_EXAMPLE
485
486   occur: Incremental search, that after each keystroke shows
487     matching lines from index table. You may enter a list of words
488     seperated by comma (\",\"), to select lines that contain all
489     of the given words.
490
491     If you supply a number (e.g. \"237\"): Apply emacs standard
492     multi-occur operation on all org-mode buffers to search for
493     this specific reference.
494
495     You may also read the note at the end of this help on saving
496     the keystroke RET with this frequent default command.
497
498   head: If invoked outside the index table, ask for a
499     reference number and search for a heading containing it. If
500     invoked within index table dont ask; rather use the reference or
501     link from the current line.
502
503   ref: Create a new reference, copy any previously selected text.
504     If already within index table, fill in ref-column.
505
506   link: Create a new line in index table with a link to the
507     current node.  Do not populate the ref column; this can later
508     be populated by calling the \"fill\" command from within the
509     index table.
510
511   leave: Leave the index table. If the last command has
512     been \"ref\", the new reference is copied and ready to yank.
513     This \"org-mark-ring-goto\" and can be called several times
514     in succession. If you invoke org-index with a prefix argument,
515     this command \"leave\" is executed without further questions.
516
517   enter: Just enter the node with the index table.
518
519   goto: Search for a specific reference within the index table.
520
521   help: Show this text.
522
523   +: Show all commands including the less frequently used ones
524     given below. If \"+\" is followd by enough letters of such a
525     command (e.g. \"+fi\"), then this command is invoked
526     directly.
527
528   reorder: Temporarily reorder the index table, e.g. by
529     count, reference or last access.
530
531   fill: If either ref or link is missing, fill it.
532
533   sort: Sort a set of lines (either the active region or the
534     whole buffer) by the references found in each line.
535
536   update: For the given reference, update the line in the
537     index table.
538
539   highlight: Highlight references in region or buffer.
540
541   unhighlight: Remove highlights.
542
543   missing : Search for missing reference numbers (which do not
544     appear in the reference table). If requested, add additional
545     lines for them, so that the command \"ref\" is able to reuse
546     them.
547
548   statistics : Show some statistics (e.g. minimum and maximum
549     reference) about index table.
550
551 #+END_EXAMPLE
552
553   Please note, that you are not required to explicitly choose one. Simply
554   typing something else (e.g. "237") accepts the default-command and
555   supplies your input as an argument.
556   
557 * Further Reading, Version, Contact
558
559   org-index.el itself contains embedded documentation, which can be
560   easily accessed through the command "help".  Most, but not all of it has
561   already been cited within this document.
562
563
564   As of [2013-11-08 Fri] this document describes version 2.3.2 of org-index.
565
566
567   Remaining questions can be sent to: 
568
569     org-index@2484.de
570
571   Feedback is welcome too.
572