c84764babfe6fdd9c19090ffdba11d719dcafecc
[worg.git] / org-tutorials / org4beginners.org
1 #+TITLE: Org-mode beginning at the basics
2 #+AUTHOR: Alexander Poslavsky
3 #+EMAIL: alexander.poslavsky AT gmail DOT com
4 #+LANGUAGE:  en
5 #+OPTIONS:    H:2 num:nil toc:t \n:nil ::t |:t ^:nil -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
6
7 [[file:../index.org][{Back to Worg's index}]]
8
9 Org-mode, as it says on the [[http://orgmode.org/ ][official web page]] is for keeping notes,
10 maintaining ToDo lists, doing project planning, and authoring with a
11 fast and effective plain-text system. Beginning with Emacs 22.2 and
12 XEmacs 22.1 it has been part of Emacs. The following is a simple
13 tutorial to help you get started using Emacs and org-mode.
14
15 * The absolute minimum you need to know about Emacs 
16   The absolute minimum you need to know about Emacs, to be able to do
17   /anything/, is more then you need to know about many other
18   applications. But, you might compare it to a regular toy and
19   lego. Lego is harder to begin with (you start with a box with little
20   plastic pieces), but in the long run, you can do more with it.
21
22   Emacs is heavy on shortcuts. starting out, that is rather
23   annoying, but in time you'll notice you start to use the mouse less
24   and less, and you actually start to work quicker.
25
26   All the basic things can be done, with the mouse, from the menu,
27   open file, save file , etc. You will notice, however, that in time it
28   is faster to use shortcuts, and leave your hands on the keyboard.
29
30   Emacs uses a lot of double shortcuts, so instead of Alt-F and
31   Alt-S, like most applications, it uses *Control-X Control-F* and
32   *Control-X Control-S*, this seems rather counter-productive in the
33   beginning, but you'll get used to it.
34
35   *Note:* Key abbreviations:
36   - *M* -- Alt (used to be called Meta on ancient keyboards, that's why)
37   - *C* -- Control
38   - *S* -- Shift
39   - *C-x f* -- means holding both Control /and/ x, release both, and
40     press f
41
42 **  What version of Emacs should you choose?
43     If it is all the same to you, then choose Emacs over XEmacs (if
44     you disagree then you know already enough to skip this
45     paragraph). Here are some links to help:
46     - [[http://aquamacs.org/][Aquamacs: Emacs for Mac OS X]] (my favourite)
47     - [[http://homepage.mac.com/zenitani/emacs-e.html][Carbon Emacs for OSX]]
48     - [[http://emacsformacosx.com/][Regular Emacs for OS X]]
49     - [[http://ftp.gnu.org/gnu/emacs/windows/][Emacs for MS Windows]]
50     On Linux, just use your package manager to install Emacs. On Debian:
51 #+BEGIN_SRC bash
52 sudo apt-get install emacs
53 #+END_SRC
54
55 ** Configuration
56
57    The biggest pain, when you just begin with Emacs, is the
58    configuration. There is not really a menu for it (you might later
59    hear there is, but they are lying, that menu is really there to
60    trap innocent people), you need to edit a text-file. The location
61    of that config-file (and even the name) is different on different
62    OSes, but the text in it is mostly the same, across platforms. Many
63    people actually use the same config-file on different OSes and even
64    over many years, so in the long run, it is for the best!
65
66    Location of the configuration file:
67    - Aquamacs: ~/Library/Preferences/Aquamacs Emacs/Preferences.el
68    - Regular emacs on Linux or OS X: ~/.emacs
69    - On Windows: c:\emacs\.emacs.d\init.txt
70      ([[http://www.claremontmckenna.edu/math/alee/emacs/emacs.html][according to this example installation]])
71 * Starting org-mode
72   New shortcuts in this chapter:
73   - *C-x s* -- save document
74   - *C-x f* -- open document
75 ** Our first org-mode document
76    By now, we know enough to start our first org-mode document. Start
77    up Emacs. If you have a completely new Emacs install, then you
78    should see the Emacs splash-screen. It has a couple of shortcuts,
79    to the Emacs tutorial and some other documents, but for now, we
80    don't need those.
81
82    To start a new document, use the following short-cut: *C-x f*,
83    which will offer you to open a document (or buffer as it is
84    called in Emacs), call it *1.org*. This will give you a brand-new,
85    empty document.
86   
87    To save the document, either press the save icon, or press *C-x s*,
88    call it 1.org.
89
90    Emacs does not actually understand you are editing an org-mode
91    document, yet. To enable org-mode on your current document, type  
92    : M-x org-mode
93    Which will enable the org-mode on the current document.
94
95    To make Emacs understand that this is an org-mode document, add the
96    following to the *top* of your document:
97 #+BEGIN_SRC org
98 MY PROJECT -*- mode: org -*- 
99 #+END_SRC
100    Those are minuses, /not/ underscores. MY PROJECT is the title of
101    the document, this can be anything.
102
103    This will enable org-mode for this document, no matter what the
104    file-ending is.
105
106    To enable org-mode to always work on all your org-files, you have
107    to edit your Emacs configuration, we do that in the following paragraph.
108 ** Our first edit to our Emacs configuration
109
110    Open your Emacs configuration file (see [[Configuration]]), to open it
111    in Emacs, use *C-x f* (open file), and put the following in it:
112
113 #+BEGIN_SRC elisp
114 ;; -*- mode: elisp -*-
115
116 ;; Disable the splash screen (to enable it agin, replace the t with 0)
117 (setq inhibit-splash-screen t)
118
119 ;; Enable transient mark mode
120 (transient-mark-mode 1)
121
122 ;;;;org-mode configuration
123 ;; Enable org-mode
124 (require 'org)
125 ;; Make org-mode work with files ending in .org
126 ;; (add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
127 ;; The above is the default in recent emacsen
128 #+END_SRC
129
130   Restart Emacs.
131
132   *Note:* The mode-line, mentioned in the previous paragraph is only
133   needed if you 1) have files with a different file-ending then
134   configured in your Emacs config (for example myfile.txt). 2) Don't
135   have the auto-mode-alist line in your configuration.
136 * Keep track of lists and notes
137   New shortcuts in this chapter:
138   - *TAB* / *S-TAB* -- (un)fold
139   - *M-up/down* -- move a headline up or down
140   - *M-left/right* -- promote or demote a headline
141   - *M-RET* -- insert a new headline
142   - *C-x s* -- save file
143   - *C-h t* -- Emacs tutorial
144
145   Now that we have configured Emacs to work with org-mode document, we
146   can actually start using it. Let's begin with an outline that will
147   help us get to know org-mode. Start a new document (*C-x b), call it
148   2.org, and copy and paste the following in it:
149 #+BEGIN_SRC org
150  #-*- mode: org -*-
151  #+STARTUP: showall
152
153  * Welcome to org-mode
154
155    Welcome, and thanks for trying out Org-mode. Making outlines in
156    org is very simple. It is just text! Just start typing.
157  * This is a headline, it starts with one or more stars
158    A heading has one star, a sub-heading two, etc.
159  * Working with lists
160  ** Moving around in our outline
161  ** Moving around headlines
162 #+END_SRC
163    Save the file (*C-x s*) as 2.org, and you will notice that the
164    colors change, syntax highlighting is turned on, and Emacs
165    understands you are working in org-mode.
166
167    Now we are ready to really start working with org-mode!
168 ** Working with lists
169    List are great for brainstorming and to keep track of things. Also
170    it helps keeping the big picture in mind when taking notes.
171
172    The first thing we will do is folding. Especially when you have a
173    long document, this is very useful. In our example document, go to
174    the first headline (just use the arrow keys), *Welcome to
175    org-mode*, end press *TAB*, and now press *S-TAB*. *Tab* will fold
176    and unfold parts or, using shift and tab, the whole document. 
177
178    The basic idea of brainstorming is to write a list of items. Then,
179    later, you might want to change the order of your items, for
180    example in order of importance. To move a headline up or down, use
181    *M-up/down*, try it on any of the headlines. Notice that your list
182    folds in, showing only headings, to give a general overview of
183    the document, and you don't get lost in the details.
184
185    Next we will promote and demote headings. For example you might
186    make *This is a headline, it starts with one or more stars*, a
187    sub-heading of *Working with lists*, moving it down, and then using
188    *M-right* to demote it.
189
190    Finally, to add a new headline, press *M-RET*.
191
192    Besides headlines there are still other kind of lists, ordered and
193    unordered lists. They look like this:
194
195 #+BEGIN_SRC org
196      ** Lord of the Rings
197         My favorite scenes are (in this order)
198         1. The attack of the Rohirrim
199         2. Eowyn's fight with the witch king
200            + this was already my favorite scene in the book
201            + I really like Miranda Otto.
202         3. Peter Jackson being shot by Legolas
203             - on DVD only
204            He makes a really funny face when it happens.
205         But in the end, no individual scenes matter but the film as a whole.
206         Important actors in this film are:
207         - Elijah Wood :: He plays Frodo
208         - Sean Austin :: He plays Sam, Frodo's friend.  I still remember
209           him very well from his role as Mikey Walsh in The Goonies.
210 #+END_SRC
211
212    Unordered lists start with -,+,or \*. Ordered lists start with a
213    number and a dot. Descriptions use ::. 
214
215    Further information: a short [[http://lumiere.ens.fr/~guerry/org-playing-with-lists-screencast.php][screencast]] presenting a few features
216    of plain lists, also look at the [[http://orgmode.org/manual/Plain-lists.html#Plain-lists][manual]].
217 ** Working with notes
218    To keep notes, there is some markup to make things stand out a bit
219    more. You can use the following markup:
220
221    : You can make words *bold*, /italic/, _underlined_, =code= and ~verbatim~, and, if you must, +strike-through+.
222
223    It will look like this:
224
225   You can make words *bold*, /italic/, _underlined_, =code= and
226   ~verbatim~, and, if you must, +strike-through+.
227    
228    If you like what you see so far, the it might be a good idea to do
229    the Emacs tutorial, that comes with Emacs itself (*C-h t*). The
230    tutorial will teach you some more Emacs shortcuts, used to move around
231    in your documents.
232 * Working with todo items
233   New shortcuts in this chapter:
234   - *S-left/right* -- cycle workflow
235   - *C-c C-v* -- show todos in current document
236 ** Basic todo functionality
237    The biggest use-case of org-mode is using it to keep track of
238    todos. To start working with todos you don't have to do anything,
239    just add the TODO keyword in a headline:
240 #+BEGIN_SRC org
241  ** TODO buy airplane
242 #+END_SRC
243   To speed up working with todo-list there is the following shortcut,
244   - *S-left/right*
245   which will cycle through: *TODO* - *DONE* and empty.
246
247   Imagine that you have a large document, with scattered all over the
248   document todo entries, *C-c C-v* will show only your current todos,
249   and folding the rest away.
250 ** Configuring todos
251 *** In the file itself
252     Org-mode files can be configured by adding workflow states to the
253     beginning of the file, like so:
254 #+BEGIN_SRC org
255 #+TODO: TODO IN-PROGRESS WAITING DONE
256 #+END_SRC
257     The line shoud be at the top of file, there should /not/ be any
258     empty lines between the top and the #+TODO line.
259
260     To activate the new workflow, either reopen the file, or go to the
261     top of the file (any line starting with #) and press *C-c C-c*.
262
263     Try copying the workflow to your test-file 1.org, seeing it helps
264     understanding what you can do with it.
265 *** In the Emacs-config file
266     Adding the workflow states to every org-file you create gets
267     boring soon, so it also possible to do this in your config
268     file. Add the following /after/ the (require 'org) line:
269 #+BEGIN_SRC lisp
270      (setq org-todo-keywords
271        '((sequence "TODO" "IN-PROGRESS" "WAITING" "DONE")))
272 #+END_SRC
273     To activate the workflow states, restart Emacs.
274 * Agendas
275   New shortcuts in this chapter:
276   - *C-c a* -- agenda
277   - *C-c [* -- add document to the list of agenda files
278   - *C-c ]* -- remove document from the list of agenda files
279   - C-c .* -- add date
280   - *C-u C-c .* -- add time and date
281   - *C-g* -- stop doing what you are trying to do, escape
282
283   The basic meaning of the word agenda is /things to be done/, coming
284   from the latin /agendum/. Org-mode is very good in making different
285   kind of agendas, or task-lists, collecting all the tasks from one or
286   more org-documents.
287 ** Creating lists of all active todos
288    We will start with using 1.org as our basic agenda-file, later we
289    will see how this works in the Emacs-config file.
290
291    So, again, visit 1.org. Next press *C-c a*, which calls the
292    agenda. It looks like this:
293 #+BEGIN_EXAMPLE
294 Press key for an agenda command
295 -------------------------------
296 a Agenda for the current week or day
297 t List of all TODO entries
298 #+END_EXAMPLE
299    and then some more.
300
301    Unfortunately, both will show just empty lists (you can try if you
302    want). So just press *C-g* (the Emacs version of escape). Next we
303    will add 1.org as agenda file, using *C-c [*. Now if you go to the
304    agenda menu (*C-c a*), and press *t* you get a list off all your todo items. 
305    
306    You will also notice that, if you have added a more comprehensive
307    workflow, as explained in [[working with todo items]], all items are
308    listed, except DONE.
309
310    This can be repeated for as many documents as you want, and agenda
311    will give you a complete list of todos. If you want to remove a
312    documents from the list of agenda files, press *C-c ]*.
313 ** Appointments and deadlines
314    When a task is time related, then we usually put it in our
315    calendar. This can also be done in org-mode. And agenda can then
316    show us a time-based list of all our todos. This is done in the
317    following way.
318
319    In 1.org, add a new (sub-)heading called: /Call fred/ (*M-RET*Call
320    fred), but at the end press *C-c .*. This will give you, at the
321    bottom of the screen, the date chooser. You can either type
322    something by hand, or use *S-left/right* to change the date. If you
323    want to add a time as well, use *C-u C-c .* instead of *C-c .*.
324
325    Now, if you go to the agenda (*C-c a*) and press *a*, you get an
326    agenda entry!
327
328    Further reading:
329    - [[http://doc.norang.ca/org-mode.html#Clocking][Bernt Hansens extensive description Time Clocking: Usage, Customization,
330    Workflow description]]
331    - [[http://sachachua.com/wp/2007/12/30/clocking-time-with-emacs-org/][Clocking time with Emacs Org]]
332    - And off course [[http://orgmode.org/manual/Dates-and-Times.html#Dates-and-Times][the manual]].
333 ** Configuring the agenda in the Emacs configuration file
334    If you open up your emacs configuration file, after you have used
335    *C-c [*, you will see the following:
336 #+BEGIN_SRC emacs-lisp -n -r
337 (custom-set-variables
338   ;; custom-set-variables was added by Custom.
339   ;; If you edit it by hand, you could mess it up, so be careful.
340   ;; Your init file should contain only one such instance.
341   ;; If there is more than one, they won't work right.
342  '(org-agenda-files (quote ("~/Documents/Projects/org4beginners/2.org"
343  "~/Documents/Projects/org4beginners/1.org"))))
344 (custom-set-faces
345   ;; custom-set-faces was added by Custom.
346   ;; If you edit it by hand, you could mess it up, so be careful.
347   ;; Your init file should contain only one such instance.
348   ;; If there is more than one, they won't work right.
349  )
350 #+END_SRC
351    Welcome to the world of Emacs lisp. This is what it looks like if
352    Emacs changes your config file. (*Note:* on Aquamacs, this is in a
353    seperate file called customizations.el)
354
355    For us, the important part is in the middle (lines 5 and 6), the line with
356    /org-agenda-files/. There we see the list of files agenda uses to
357    create its lists. For now we can just leave it there, but at least
358    you know what it is, when you later look at your config-file.
359    Further reading: [[http://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.html][Custom agenda commands]]
360 * GTD
361   New shortcuts in this chapter:
362   - *C-c C-c* -- add tag
363
364   /Getting things done/, is one of the most popular ways to organize
365   oneself, with 4.3 miljon hits on Google. It is quite possible to use
366   the same kind of setup in org mode, using tags.
367
368   Tags are used to organize different kind of todo-entries, for
369   example all tasks on the phone, reading, shopping, etc.
370
371   To add tags, add the following to the top your document:
372
373 #+BEGIN_SRC org
374  #+TAGS: { @OFFICE(o) @HOME(h) } COMPUTER(c) PHONE(p) READING(r) 
375 #+END_SRC
376
377   Reload the document, or press *C-c C-c* on a line starting with #.
378
379   Now it is possible to add one or more tags, to any line in your
380   document. If we press *C-c C-c*, the following will pop up:
381 #+BEGIN_EXAMPLE
382 Inherited:
383 Current:
384 { [o] @OFFICE     [h] @HOME    }
385   [C] COMPUTER   [p] PHONE   [r] READING
386 #+END_EXAMPLE
387   These are the shortcuts we defined at the beginning of our
388   document. The first two tags (OFFICE and HOME) are mutually
389   exclusive, the rest can just be added.
390
391   A very good example of a GTD setup is: [[http://members.optusnet.com.au/~charles57/GTD/gtd_workflow.html][How I use Emacs and Org-mode to implement GTD]]
392 ** Adding tags to the Emacs config-file
393    To add tags to the Emacs config-file, so it is available to al your
394    documents, add the following.
395 #+BEGIN_SRC emacs-lisp
396       (setq org-tag-alist '(("@work" . ?w) ("@home" . ?h) ("laptop" . ?l)))
397 #+END_SRC
398    To set mutually exclusive groups, like the previous example, see
399    [[http://orgmode.org/org.html#Setting-tags][here]] in the manual.
400
401    It is always possible to override your settings by adding something
402    else to the top of the document. This way every document can have
403    its own workflow and/or tags.
404
405    An extensive example of working with tags can be found [[http://sachachua.com/wp/2008/01/04/tagging-in-org-plus-bonus-code-for-timeclocks-and-tags/][here]] as well.
406 * Export
407   New shortcuts in this chapter:
408   - *C-c C-e* -- export menu
409
410   Working with org-mode documents is usually fine, but sometimes you
411   might want to export your documents to another format.
412
413   To export the current document to, for example, html, press *C-c C-e*,
414   and then *b*. This will export the document and open the new
415   document in your browser.
416
417   Further reading: [[http://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.html][html publishing tutorial]] (which goes further then
418   just a document, you can use it to publish a complete website). And
419   [[http://orgmode.org/manual/Exporting.html#Exporting][the manual]] which explains exporting to html, latex, pdf and others.
420 * Becoming proficient with org-mode
421
422   To really save time with any efficiency tool, you have to know it
423   well. To get to know org-mode, reading and using the manual is
424   important.  Org-mode is well documented. The fastest way to read the
425   org-mode documentation right in Emacs, in the so-called
426   info-browser.
427   
428   to call the info browser, use *C-h i*, and use *TAB* to jump from
429   hyperlink, to hyperlink.
430
431   To move around in the info-browser use:
432   - u -- up
433   - n -- next
434   - p -- previous
435
436   Besides the org-mode manual, the is the [[http://orgmode.org/worg/][worg website]], which has
437   many cool ideas and [[http://orgmode.org/worg/org-tutorials/index.html][tutorials]].
438
439   For quick reminders there are the [[http://orgmode.org/index.html#sec-4.2][org-mode cheat-sheet]] and the
440   emacs cheat-sheet, both will help you to remember those pesky
441   short-cuts. 
442 * Beyond the basics
443   
444   As is often said in geek humor: "here be dragons!" From here on you
445   are going into the die-hard section of using org-mode. Most of the
446   following material is not really hard, but make sure to have backups
447   of your important data. If you have questions about the following,
448   look it up in the manual and the faq. Also irc (#orgmode on
449   freenode) is a good place to ask questions.
450
451 ** TODO Quickly adding tasks with remember
452 ** Running the latest version of org-mode
453
454    New commands in this section:
455    - *M-x reload* -- reload org-mode after an update
456    - *M-x org-version* -- show org-mode version
457
458    Pretty soon you will notice that the development of org-mode goes a
459    lot faster the speed Emacs get's updated with. It is quite possible
460    to run the development version of org-mode daily.
461
462    How do you go about that?
463    
464    1. Install git
465       Not really part of an org-mode tutorial, but here are some
466       places to start:
467       - [[http://code.google.com/p/git-osx-installer/][Git OS X installer]]
468       - [[http://code.google.com/p/msysgit/][Myssysgit]] git on Windows
469       - On Linux, use your package manager:
470       #+BEGIN_SRC bash
471         sudo apt-get install git
472       #+END_SRC
473
474    2. Decide where you will keep the org-mode code, I use
475       *~/Build/Emacs/org-mode*, but for Emacs it is really all the
476       same, just choose something convenient, and stick with it.
477
478    3. Download the latest version of org-mode:
479       #+BEGIN_SRC bash
480        mkdir ~/Build/Emacs
481        cd ~/Build/Emacs
482        git clone git://orgmode.org/org-mode.git
483        cd org-mode && make && make doc
484       #+END_SRC
485
486    4. Add to your Emacs-init file:
487      #+BEGIN_SRC Emacs-lisp
488        (setq load-path (cons "~/Build/Emacs/org-mode/lisp" load-path))
489        (setq load-path (cons "~/Build/Emacs/org-mode/contrib/lisp"
490        load-path))
491
492        (require 'org-install)
493     #+END_SRC
494     *Important!* If you run the regular version of org-mode, you have
495     :(require 'org) 
496     in your config-file. This line *must* be removed, if you use
497     :(require 'org-install)
498
499    5. To keep up-to-date with org-mode in the future do:
500       #+BEGIN_SRC bash
501        cd ~/Build/Emacs/org-mode
502        git pull && make clean && make && make doc
503       #+END_SRC
504
505    6. Reload org mode, using: *M-x org-reload*, or restart Emacs.
506    
507    To see what version of org-mode you are running: *M-x org-version*