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