org-tutorials/orgtutorial_dto.org

   1 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   5 #+TITLE:      David O'Toole Org tutorial
   6 #+AUTHOR:     David O'Toole
   7 #+EMAIL:      dto AT gnu DOT org
   8 #+LANGUAGE:   en
   9 #+PRIORITIES: A C B
  10 #+CATEGORY:   worg
  11
  12 # This file is the default header for new Org files in Worg.  Feel free
  13 # to tailor it to your needs.
  14
  15 [[file:../index.org][{Back to Worg's index}]]
  16
  17 * Introduction
  18
  19 Org-mode is a personal information management and outlining tool for
  20 Emacs. This document is intended to give the reader a "feel" for
  21 org-mode and to teach basic usage with step-by-step instructions and
  22 plentiful screenshots. It is not intended to replace the [[http://orgmode.org/org.html][manual]], as
  23 only a subset of org-mode's features are covered.
  24
  25 This tutorial has been translated into [[file:orgtutorial_dto-fr.org][French]], [[http://hpcgi1.nifty.com/spen/index.cgi%3FOrgMode%2fOrgTutorial][Japanese]], [[http://hokmen.chan.googlepages.com/OrgTutorial.en-cn.html][Chinese]], and
  26 [[http://jmjeong.com/index.php?display=Emacs/OrgMode"][Korean]]. Special thanks to the translators.
  27
  28 ** Obtaining org-mode
  29
  30 Org-mode is part of Emacs 22 and 23, so if you have a modern version
  31 of Emacs, you have it already.
  32
  33 If not, you can download it [[http://orgmode.org/][org-mode home
  34 page.]], unpack it and point the Emacs load path to the lisp directory
  35 in the Org-mode distribution:
  36
  37 : (add-to-list 'load-path "PATH_TO_WHERE_YOU_UNPACKED_ORGMODE/lisp")
  38
  39 ** Activation
  40
  41 Add the following to your .emacs:
  42
  43 : (require 'org-install)
  44 : (add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
  45 : (define-key global-map "\C-cl" 'org-store-link)
  46 : (define-key global-map "\C-ca" 'org-agenda)
  47 : (setq org-log-done t)
  48
  49 This will make sure org gets loaded, and some basic global key
  50 combinations are defined.  We'll go over what "org-store-link" and
  51 "org-agenda" do later in this document.
  52
  53 One more thing---it's best to set aside a separate directory where
  54 your org files will be kept. I recommend using ~/org.
  55
  56 * The basics
  57
  58 This section illustrates basic org-mode usage by showing how I used
  59 org-mode to create this document.
  60
  61 ** Creating a new file
  62
  63 If you've configured your Emacs initialization file as suggested
  64 above, Emacs should enter org-mode whenever you visit or create a file
  65 with the extension ".org".
  66
  67 I created a new file called "OrgTutorial.org" and saw the "Org"
  68 indicator in the modeline, showing that we've entered org-mode.
  69
  70 ** Simple task list
  71
  72 First I entered a *headline* called "Tasks" to keep tasks under. This
  73 isn't necessary but is often convenient, especially when you want to
  74 keep tasks separate from the body of a document you're writing.
  75
  76 First-level headlines begin with one star; second-level headlines
  77 begin with two stars, and so on.
  78
  79 In org-mode, TODO items are always headlines. I entered a TODO item
  80 for "Start new org file for tutorial."
  81
  82 file:../images/dto/tutorial-1.png
  83
  84 This is a bit silly, because we've already started a new file. So,
  85 let's mark the TODO item DONE by moving the cursor onto that line and
  86 hitting *C-c C-t*, which runs the command *org-todo*.
  87
  88 Here is the result:
  89
  90 file:../images/dto/tutorial-2.png
  91
  92 Notice how org-mode uses a timestamp to record when a TODO item was
  93 closed.
  94
  95 Let's add some more TODO items. Position the cursor on the next line,
  96 and hit *M-shift-RET* to call *org-insert-todo-heading*. You can hit
  97 it several times to add several TODOs.
  98
  99 file:../images/dto/tutorial-3.png
 100
 101
 102 ** Using headlines to structure a document
 103
 104 Often the best way to organize your ideas is an outline. My next step
 105 is to outline the different topics of the tutorial. By doing this, you
 106 break up the intimidating blank page into a series of
 107 less-intimidating smaller chunks. Then it becomes easier to fill them
 108 in.
 109
 110 Remember that one star begins a first-level heading, and two stars
 111 begin a second-level heading. If you need deeper nesting, go ahead and
 112 use three or more stars!
 113
 114 Here is what it looked like after I finished outlining the document:
 115
 116 file:../images/dto/tutorial-4.png
 117
 118 Notice I marked "Outline document" as DONE after I finished.
 119
 120 ** Filling in the sections
 121
 122 You can easily add body text underneath any headline.
 123
 124 file:../images/dto/tutorial-5.png
 125
 126 ** Links to other places
 127
 128 In the section on "Obtaining Org-mode" I need to provide a link to the
 129 org-mode website. A special bracket syntax is used when linking:
 130
 131 : [[link][description]]
 132
 133 Watch how I first type the link and description, leaving open the last
 134 bracket:
 135
 136 file:../images/dto/tutorial-6.png
 137
 138 Then when I type the last bracket, the link "collapses" and simply
 139 shows the description.
 140
 141 file:../images/dto/tutorial-7.png
 142
 143 Try moving the cursor over the link and press *C-c C-o*
 144 for *org-open-at-point*.
 145
 146 You can also link to local files. Try visiting another file---for
 147 example, your emacs initialization file. Then hit *C-c l* to
 148 call *org-store-link*. You'll see a message that a link was stored to
 149 the current location in the file you're visiting.
 150
 151 Then switch back to your org-mode buffer and paste the link
 152 using *C-c C-l* to call *org-insert-link*. (You may need to press the
 153 arrow keys to scroll through and find the link you just recorded.)
 154
 155 ** Overviews of a document
 156
 157 By this time, my document is getting longer and I can no longer fit it
 158 all on one screen. Org-mode makes it easy to get an overview of your
 159 document by pressing *shift-TAB*.
 160
 161 file:../images/dto/tutorial-9.png
 162
 163 Notice that just the top-level headings are shown.  You can
 164 hit *shift-TAB* again to show *all* headings, including TODO items:
 165
 166 file:../images/dto/tutorial-10.png
 167
 168 Then hit it again to show a normal view of the document, with section
 169 bodies shown:
 170
 171 file:../images/dto/tutorial-11.png
 172
 173 ** Adding notes to a task
 174
 175 You can put as much text as you want under a TODO item's heading. In
 176 fact, you can even have subheadings under a TODO, and TODOs within
 177 TODOs!
 178
 179 Being able to annotate tasks makes it easy to collect related links
 180 and thoughts along with a task. Being able to nest tasks is great for
 181 modeling workflow---quite often, a larger task is broken into smaller
 182 subtasks you want to check off as you do them.
 183
 184 * A taste of advanced features
 185
 186 Before we finish, we'll touch on org-mode's global TODO list,
 187 scheduling, and agenda features. These are used to combine relevant
 188 TODO items from different org files into a prioritized, chronological
 189 display. You can also use it to see which tasks were completed, and
 190 when.
 191
 192 ** Setup
 193
 194 First you must set the variable *org-agenda-files* so that org-mode
 195 will know which files to search for TODOs and scheduled items.
 196
 197 Let's imagine you already have several org files---say, one for work,
 198 one for home, and one for school.
 199
 200 Then you'd add the following to your emacs initialization file:
 201
 202 : (setq org-agenda-files (list "~/org/work.org"
 203 :                              "~/org/school.org"
 204 :                              "~/org/home.org"))
 205
 206 ** The global TODO list
 207
 208 Press *C-c a t* to enter the global todo list. Org-mode will scan the
 209 files in *org-agenda-files* and present a listing of all the open TODO
 210 items:
 211
 212 file:../images/dto/tutorial-16.png
 213
 214 You can move the cursor around to the different todo items, and
 215 hit "t" to mark an item DONE, or hit *RET* to jump to the source file
 216 where the TODO is located.
 217
 218 ** Scheduling tasks and using the agenda
 219
 220 Let's say I want to schedule "Finish document" for today. I move the
 221 cursor to the line after the TODO item "Finish document", and hit
 222  *C-c C-s* to run *org-schedule*. The calendar pops up, and I can
 223  either enter or click the desired date:
 224
 225 file:../images/dto/tutorial-12.png
 226
 227 Once I select the date, org-mode inserts a scheduling timestamp after
 228 the TODO item:
 229
 230 file:../images/dto/tutorial-13.png
 231
 232 Now save your file, and hit *C-c a a* for *org-agenda*. A display of
 233 this week's scheduled items are displayed:
 234
 235 file:../images/dto/tutorial-14.png
 236
 237 Now press "l" (lowercase L) to turn on log display. This displays the
 238 all finished tasks and their completion times.
 239
 240 file:../images/dto/tutorial-15.png
 241
 242 * Farewell
 243
 244 This has been only a brief tour of org-mode. More excitement awaits
 245 you at the [[http://orgmode.org/org.html][online org-mode manual.]]