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