org-tutorials/orgtutorial_dto.org

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