ORGWEBPAGE/faq.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   2                "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml"
   4 lang="en" xml:lang="en">
   5 <head>
   6 <title>Org-mode Frequently Asked Questions</title>
   7 <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"/>
   8 <meta name="generator" content="Org-mode"/>
   9 <meta name="generated" content="2007/09/10 07:06:01"/>
  10 <meta name="author" content="Carsten Dominik"/>
  11 <link rel=stylesheet href="freeshell2.css" type="text/css"> <style type="text/css"> .tag { color: red; font-weight:bold}</style>
  12 </head><body>
  13 <h1 class="title">Org-mode Frequently Asked Questions</h1>
  14 <h2>Table of Contents</h2>
  15 <ul>
  16 <li><a href="#sec-1">1 General</a>
  17 <ul>
  18 <li><a href="#sec-2">1.1 Use features in other modes</a></li>
  19 <li><a href="#sec-3">1.2 Visibility cycling in Outline-mode and Outline-minor-mode</a></li>
  20 </ul>
  21 </li>
  22 <li><a href="#sec-4">2 Errors</a>
  23 <ul>
  24 <li><a href="#sec-5">2.1 <code>(wrong-type-argument keymapp nil)</code></a></li>
  25 <li><a href="#sec-6">2.2 CUA mode does not work with Org-mode</a></li>
  26 <li><a href="#sec-7">2.3 <code>winddmove.el</code> does not work with Org-mode.</a></li>
  27 </ul>
  28 </li>
  29 <li><a href="#sec-8">3 Setup and Structure</a>
  30 <ul>
  31 <li><a href="#sec-9">3.1 Org-mode as default mode</a></li>
  32 <li><a href="#sec-10">3.2 Get rid of extra stars in outline</a></li>
  33 <li><a href="#sec-11">3.3 Two windows on same Org-mode file</a></li>
  34 <li><a href="#sec-12">3.4 Insert empty lines before new headings and plain list items</a></li>
  35 <li><a href="#sec-13">3.5 Amount of context in sparse trees</a></li>
  36 <li><a href="#sec-14">3.6 Stacking calls to org-occur</a></li>
  37 </ul>
  38 </li>
  39 <li><a href="#sec-15">4 Hyperlinks</a>
  40 <ul>
  41 <li><a href="#sec-16">4.1 Confirmation for shell and elisp links</a></li>
  42 <li><a href="#sec-17">4.2 Use RET or TAB to follow a link</a></li>
  43 <li><a href="#sec-18">4.3 Clicking on a link without activating it</a></li>
  44 </ul>
  45 </li>
  46 <li><a href="#sec-19">5 Export</a>
  47 <ul>
  48 <li><a href="#sec-20">5.1 Make TODO entries items, not headlines in HTML export</a></li>
  49 <li><a href="#sec-21">5.2 Export only a subtree</a></li>
  50 <li><a href="#sec-22">5.3 How to import org-mode calendar data into Mac OSX ical</a></li>
  51 </ul>
  52 </li>
  53 <li><a href="#sec-23">6 Tables</a>
  54 <ul>
  55 <li><a href="#sec-24">6.1 #ERROR fields in tables</a></li>
  56 <li><a href="#sec-25">6.2 Unwanted new lines in table</a></li>
  57 <li><a href="#sec-26">6.3 Automatic detection of formulas</a></li>
  58 <li><a href="#sec-27">6.4 Change indentation of a table</a></li>
  59 <li><a href="#sec-28">6.5 Performance issues with table alignment</a></li>
  60 <li><a href="#sec-29">6.6 Performance issues with table calculation</a></li>
  61 <li><a href="#sec-30">6.7 Incrementing numbers</a></li>
  62 </ul>
  63 </li>
  64 <li><a href="#sec-31">7 Agenda</a>
  65 <ul>
  66 <li><a href="#sec-32">7.1 Include Org-mode agenda into Emacs diary</a></li>
  67 </ul>
  68 </li>
  69 </ul>
  70
  71 <h2 id="sec-1">1 General</h2>
  72
  73
  74 <h3 id="sec-2">1.1 Use features in other modes</h3>
  75
  76 <p><b>I would like to use editing features of org-mode in other modes, is  this possible?</b>
  77 </p>
  78 <p>
  79 Not really.  For tables there is <code>orgtbl-mode</code> which implements the
  80 table editor as a minor mode.  For other features you need to switch to
  81 Org-mode temporarily, or prepare text in a different buffer.
  82 </p>
  83
  84
  85 <h3 id="sec-3">1.2 Visibility cycling in Outline-mode and Outline-minor-mode</h3>
  86
  87
  88 <p>
  89 <b>Can I get the visibility-cycling features in outline-mode and outline-minor-mode?</b>
  90 </p>
  91 <p>
  92 Yes, these functions are written in a way that they are independent of
  93 the outline setup.  The following setup provides standard Org-mode
  94 functionality in outline-mode on <code>TAB</code> and <code>S-TAB</code>.  For
  95 outline-minor-mode, we use <code>C-TAB</code> instead of <code>TAB</code>,
  96 because <code>TAB</code> usually has mode-specific tasks.
  97 </p>
  98 <p>
  99 <pre>
 100 (add-hook 'outline-minor-mode-hook
 101   (lambda ()
 102     (define-key outline-minor-mode-map [(control tab)] 'org-cycle)
 103     (define-key outline-minor-mode-map [(shift tab)] 'org-global-cycle)))
 104 (add-hook 'outline-mode-hook
 105   (lambda ()
 106     (define-key outline-mode-map [(tab)] 'org-cycle)
 107     (define-key outline-mode-map [(shift tab)] 'org-global-cycle)))
 108 </pre>
 109 </p>
 110 <p>
 111 Or check out <i>outline-magic.el</i>, which does this and also provides
 112 promotion and demotion functionality.  <i>outline-magic.el</i> is
 113 available at <a href="http://www.astro.uva.nl/~dominik/Tools/OutlineMagic">Outline Magic</a>.
 114 </p>
 115
 116 <h2 id="sec-4">2 Errors</h2>
 117
 118
 119 <h3 id="sec-5">2.1 <code>(wrong-type-argument keymapp nil)</code></h3>
 120
 121 <p><b>When I try to use Org-mode, I always get the error message @code{(wrong-type-argument keymapp nil)}</b>
 122 </p>
 123 <p>
 124 This is a conflict with an outdated version of the <i>allout.el</i>, see
 125 the <a href="http://staff.science.uva.nl/~dominik/Tools/org/org.html#Conflicts">Conflicts</a> section in the manual
 126 </p>
 127
 128 <h3 id="sec-6">2.2 CUA mode does not work with Org-mode</h3>
 129
 130
 131 <p>
 132 <b>Org-mode takes over the S-cursor keys.  I also want to use CUA-mode, is there a way to fix this conflict?</b>
 133 </p>
 134 <p>
 135 Yes, see the  <a href="http://staff.science.uva.nl/~dominik/Tools/org/org.html#Conflicts">Conflicts</a> section of the manual.
 136 </p>
 137
 138 <h3 id="sec-7">2.3 <code>winddmove.el</code> does not work with Org-mode.</h3>
 139
 140
 141 <p>
 142 <b>Org-mode takes over the S-cursor keys.  I also want to use windmove.el, is there a way to fix this conflict?</b>
 143 </p>
 144 <p>
 145 Yes, see the <a href="http://staff.science.uva.nl/~dominik/Tools/org/org.html#Conflicts">Conflicts</a> section of the manual.
 146 </p>
 147
 148 <h2 id="sec-8">3 Setup and Structure</h2>
 149
 150
 151 <h3 id="sec-9">3.1 Org-mode as default mode</h3>
 152
 153
 154 <p>
 155 <b>Org-mode seems to be a useful default mode for the various README files I have scattered through my directories</b>.  <b>How do I turn it on for all README files?</b>
 156 </p>
 157 <p>
 158 Add the following to your .emacs file:
 159 </p>
 160 <p>
 161 <pre>
 162  (add-to-list 'auto-mode-alist '("README$" . org-mode))
 163 </pre>
 164 </p>
 165 <p>
 166 You can even make it the default mode for any files with unspecified
 167 mode using
 168 </p>
 169 <p>
 170 <pre>
 171  (setq default-major-mode 'org-mode)
 172 </pre>
 173 </p>
 174
 175 <h3 id="sec-10">3.2 Get rid of extra stars in outline</h3>
 176
 177
 178 <p>
 179 <b>All these stars are driving me mad, I just find the Emacs outlines unreadable.  Can't you just put white space and a single star as a starter for headlines?</b>
 180 </p>
 181 <p>
 182 See the section  <a href="http://staff.science.uva.nl/~dominik/Tools/org/org.html#Clean%20outline%20view">Clean outline view</a> in the manual.
 183 </p>
 184
 185 <h3 id="sec-11">3.3 Two windows on same Org-mode file</h3>
 186
 187 <p><b>I would like to have two windows on the same Org-mode file, but with different outline visibility.  Is that possible?</b>
 188 </p>
 189 <p>
 190 You may use <i>indirect buffers</i> which do exactly this.  See the
 191 documentation on the command <code>make-indirect-buffer</code>.
 192 </p>
 193
 194 <h3 id="sec-12">3.4 Insert empty lines before new headings and plain list items</h3>
 195
 196
 197 <p>
 198 <b>I would like to have an empty line before each newly inserted headline, but not before each newly inserted plain-list item</b>.
 199 </p>
 200 <p>
 201 <pre>
 202  (setq org-blank-before-new-entry
 203        '((heading . t) (plain-list-item . nil))
 204 </pre>
 205 </p>
 206
 207
 208 <h3 id="sec-13">3.5 Amount of context in sparse trees</h3>
 209
 210
 211 <p>
 212 *Sparse tree show the headline hierarchy above each match, and also
 213 the headline following a match.  I'd like to construct more compact
 214 trees, with less context.*
 215 </p>
 216 <p>
 217 Take a look at the variables <code>org-show-hierarchy-above</code> and
 218 <code>org-show-following-headline</code>.
 219 </p>
 220
 221 <h3 id="sec-14">3.6 Stacking calls to org-occur</h3>
 222
 223
 224 <p>
 225 <b>Each call to org-occur starts again from OVERVIEW and exposes only  the matches of the current call.  I'd like to combine the effect of  several calls</b>.
 226 </p>
 227 <p>
 228 You can construct a regular expression that matches all targets you
 229 want.  Alternatively, use a <code>C-u</code> prefix with the second and any
 230 further calls to <code>org-occur</code> to keep the current visibility and
 231 highlighting in addition to the new ones.
 232 </p>
 233
 234 <h2 id="sec-15">4 Hyperlinks</h2>
 235
 236
 237
 238 <h3 id="sec-16">4.1 Confirmation for shell and elisp links</h3>
 239
 240
 241 <p>
 242 <b>When I am executing shell/elisp links I always get a confirmation prompt and need to type "yes RET", that's 4 key presses!  Can I get rid of this?</b>
 243 </p>
 244 <p>
 245 The confirmation is there to protect you from unwantingly execute
 246 potentially dangerous commands.  For example, imagine a link
 247 <pre>
 248 [[shell:rm -rf ~/*][ Google Search]]
 249 </pre>
 250 </p>
 251 <p>
 252 In an Org-mode buffer, this command would look like <i>Google Search</i>,
 253 but really it would remove your home directory.  If you wish, you can
 254 make it easier to respond to the query by setting
 255 </p>
 256 <p>
 257 <pre>
 258  (setq org-confirm-shell-link-function 'y-or-n-p
 259        org-confirm-elisp-link-function 'y-or-n-p).
 260 </pre>
 261 </p>
 262 <p>
 263 Then a single keypress will be enough to confirm those links.  It is
 264 also possible to turn off this check entirely, but I strongly recommend
 265 against this.  Be warned.
 266 </p>
 267
 268 <h3 id="sec-17">4.2 Use RET or TAB to follow a link</h3>
 269
 270
 271 <p>
 272 <b>From other packages like Emacs-wiki, I am used to follow links with  <code>RET</code> when the cursor is on the link.  Is this also possible in org-mode?</b>
 273 </p>
 274 <p>
 275 Yes, and you may also use TAB.
 276 </p>
 277 <p>
 278 <pre>
 279  (setq org-return-follows-link t)
 280  (setq org-tab-follows-link t)
 281 </pre>
 282 </p>
 283
 284 <h3 id="sec-18">4.3 Clicking on a link without activating it</h3>
 285
 286
 287 <p>
 288 <b>Each time I click inside a link in order to set point to this  location, Org-mode actually follows the link</b>
 289 </p>
 290 <p>
 291 Activating links with <code>mouse-1</code> is a new feature in Emacs 22, to make
 292 link behavior similar to other applications like web browsers.  If you
 293 hold the mouse button down a bit longer, the cursor will be set
 294 without following the link.  If you cannot get used to this behavior,
 295 you can (as in Emacs 21) use <code>mouse-2</code> to follow links and turn off
 296 link activation for <code>mouse-1</code> with
 297 </p>
 298 <p>
 299 <pre>
 300  (setq org-mouse-1-follows-link nil)
 301 </pre>
 302 </p>
 303
 304
 305 <h2 id="sec-19">5 Export</h2>
 306
 307
 308 <h3 id="sec-20">5.1 Make TODO entries items, not headlines in HTML export</h3>
 309
 310
 311 <p>
 312 <b>When I export my TODO list, every TODO item becomes a separate section.  How do I enforce these items to be exported as an itemized list?</b>
 313 </p>
 314 <p>
 315 If you plan to use ASCII or HTML export, make sure things you want to
 316 be exported as item lists are level 4 at least, even if that does mean
 317 there is a level jump.  For example:
 318 </p>
 319 <p>
 320 <pre>
 321  * Todays top priorities
 322  **** TODO write a letter to xyz
 323  **** TODO Finish the paper
 324  **** Pick up kids at the school
 325 </pre>
 326 </p>
 327 <p>
 328 Alternatively, if you need a specific value for the heading/item
 329 transition in a particular file, use the <code>#+OPTIONS</code> line to
 330 configure the H switch.
 331 </p>
 332 <p>
 333 <pre>
 334  #+OPTIONS:   H:2; ...
 335 </pre>
 336 </p>
 337
 338 <h3 id="sec-21">5.2 Export only a subtree</h3>
 339
 340
 341 <p>
 342 <b>I would like to export only a subtree of my file to HTML. How?</b>
 343 </p>
 344 <p>
 345 If you want to export a subtree, mark the subtree as region and then
 346 export.  Marking can be done with <code>C-c @ C-x C-x</code>, for example.
 347 </p>
 348
 349 <h3 id="sec-22">5.3 How to import org-mode calendar data into Mac OSX ical</h3>
 350
 351
 352 <p>
 353 <b>I would like my iCal program on Mac OSX to import the iCalendar file   produced by Org-mode. How?</b>
 354 </p>
 355 <p>
 356 <i>This is for OSX 10.3, see below for 10.4:</i> When using iCal under
 357 Apple MacOS X, you can create a new calendar <i>OrgMode</i> (the default
 358 name for the calendar created by <code>C-c C-e c</code>, see the variables
 359 <code>org-icalendar-combined-name</code> and
 360 <code>org-combined-agenda-icalendar-file</code>).  Then set Org-mode to overwrite
 361 the corresponding file <i>~/Library/Calendars/OrgMode.ics</i>.  You may
 362 even use AppleScript to make iCal re-read the calendar files each time
 363 a new version of <i>OrgMode.ics</i> is produced.  Here is the setup needed
 364 for this:
 365 </p>
 366 <p>
 367 <pre>
 368  (setq org-combined-agenda-icalendar-file
 369      "~/Library/Calendars/OrgMode.ics")
 370  (add-hook 'org-after-save-iCalendar-file-hook
 371   (lambda ()
 372    (shell-command
 373     "osascript -e 'tell application \"iCal\" to reload calendars'")))
 374 </pre>
 375 </p>
 376
 377 <p>
 378 For Mac OS X 10.4, you need to write the ics file to
 379 <code>/Library/WebServer/Documents/</code> and then subscribe iCalendar to
 380 <code>http: //localhost/orgmode.ics</code>
 381 </p>
 382
 383 <h2 id="sec-23">6 Tables</h2>
 384
 385
 386 <h3 id="sec-24">6.1 #ERROR fields in tables</h3>
 387
 388
 389 <p>
 390 <b>One of my table columns has started to fill up with <code>#ERROR</code>.  What is going on?</b>
 391 </p>
 392 <p>
 393 Org-mode tried to compute the column from other fields using a
 394 formula stored in the <code>#+TBLFM:</code> line just below the table, and
 395 the evaluation of the formula fails.  Fix the fields used in the
 396 formula, or fix the formula, or remove it!
 397 </p>
 398
 399 <h3 id="sec-25">6.2 Unwanted new lines in table</h3>
 400
 401
 402 <p>
 403 <b>When I am in the last column of a table and just above a horizontal line in the table, pressing TAB creates a new table line before the horizontal line</b>.  <b>How can I quickly move to the line below the horizontal line instead?</b>
 404 </p>
 405 <p>
 406 Press <code>down</code> (to get on the separator line) and then <code>TAB</code>.
 407 Or configure the variable
 408 </p>
 409 <p>
 410 <pre>
 411  (setq org-table-tab-jumps-over-hlines t)
 412 </pre>
 413 </p>
 414
 415 <h3 id="sec-26">6.3 Automatic detection of formulas</h3>
 416
 417 <p><b>I need to use fields in my table that start with "=", and each time  I enter such a field, Org-mode thinks this is a formula</b>.
 418 </p>
 419 <p>
 420 With the setting
 421 </p>
 422 <p>
 423 <pre>
 424  (setq org-table-formula-evaluate-inline nil)
 425 </pre>
 426 </p>
 427 <p>
 428 this will no longer happen.  You can still use formulas using the
 429 commands <tt>C-c =</tt> and <tt>C-u C-c =</tt>
 430 </p>
 431
 432
 433 <h3 id="sec-27">6.4 Change indentation of a table</h3>
 434
 435 <p><b>How can I change the indentation of an entire table without fixing every line by hand?</b>
 436 </p>
 437 <p>
 438 The indentation of a table is set by the first line.  So just fix the
 439 indentation of the first line and realign with <code>TAB</code>.
 440 </p>
 441
 442 <h3 id="sec-28">6.5 Performance issues with table alignment</h3>
 443
 444 <p><b>I have a huge table in a file, and the automatic realign of tables  is just taking too long.  What can I do?</b>
 445 </p>
 446 <p>
 447 Either split the table into several by inserting an empty line every
 448 100 lines or so.  Or turn off the automatic re-align with
 449 </p>
 450 <p>
 451 <pre>
 452  (setq org-table-automatic-realign nil)
 453 </pre>
 454 </p>
 455 <p>
 456 After this the only way to realign a table is to press <code>C-c C-c</code>.  It
 457 will no longer happen automatically, removing the corresponding delays
 458 during editing.
 459 </p>
 460
 461 <h3 id="sec-29">6.6 Performance issues with table calculation</h3>
 462
 463 <p><b>I have a complex table with lots of formulas, and recomputing the  table takes rather long.  What can I do?</b>
 464 </p>
 465 <p>
 466 Nothing, really.  The spreadsheet in org is mostly done to make
 467 calculations possible, not so much to make them fast.  Since Org-mode
 468 is firmly committed to the ASCII format, nothing is stopping you from
 469 editing the table by hand.  Therefore, there is no internal
 470 representation of the data.  Each time Org-mode starts a computation,
 471 it must scan the table for special lines, find the fields etc.  This
 472 is slow.  Furthermore, Calc is slow compared to hardware computations.
 473 To make this work with normal editing, recalculation is not happening
 474 automatically, or only for the current line, so that the long wait for
 475 a full table iteration only happens when you ask for it.
 476 </p>
 477 <p>
 478 So for really complex tables, moving to a "real" spreadsheet may still
 479 be the best option.
 480 </p>
 481 <p>
 482 That said, there are some ways to optimize things in Org-mode, and I
 483 have been thinking about moving a bit further down this line.
 484 However, for my applications this has so far not been an issue at all.
 485 If you have a good case,you could try to convince me.
 486 </p>
 487
 488 <h3 id="sec-30">6.7 Incrementing numbers</h3>
 489
 490 <p><b>When I press <code>S-RET</code> in a table field to copy its value down, the  content is not copied as is, but it is increased by one.  Is that a bug or a feature</b>
 491 </p>
 492 <p>
 493 Well, it is <i>supposed</i> to be a feature, to make it easy to create a
 494 column with increasing numbers.  If this gets into your way, turn it
 495 off with
 496 </p>
 497 <p>
 498 <pre>
 499  (setq org-org-table-copy-increment nil)
 500 </pre>
 501 </p>
 502
 503 <h2 id="sec-31">7 Agenda</h2>
 504
 505
 506 <h3 id="sec-32">7.1 Include Org-mode agenda into Emacs diary</h3>
 507
 508 <p><b>Is it possible to include entries from org-mode files into my emacs diary?</b>
 509 </p>
 510 <p>
 511 Since the org-mode agenda is much more powerful and can contain the
 512 diary, you should think twice before deciding to do this.  If you
 513 insist, however, integrating Org-mode information into the diary is
 514 possible.  You need to turn on <i>fancy diary display</i> by setting in
 515 .emacs:
 516 </p>
 517 <p>
 518 <pre>
 519  (add-hook 'diary-display-hook 'fancy-diary-display)
 520 </pre>
 521 </p>
 522 <p>
 523 Then include the following line into your ~/diary file, in
 524 order to get the entries from all files listed in the variable
 525 <code>org-agenda-files</code>
 526 </p>
 527 <p>
 528 <pre>
 529  &amp;%%(org-diary)
 530 </pre>
 531 You may also select specific files with
 532 </p>
 533 <p>
 534 <pre>
 535  &amp;%%(org-diary) ~/path/to/some/org-file.org
 536  &amp;%%(org-diary) ~/path/to/another/org-file.org
 537 </pre>
 538 </p>
 539 <p>
 540 If you now launch the calendar and press <tt>d</tt> to display a diary, the
 541 headlines of entries containing a timestamp, date range, schedule, or
 542 deadline referring to the selected date will be listed.  Just like
 543 Org-mode's agenda view, the diary for <i>today</i> contains additional
 544 entries for overdue deadlines and scheduled items.  See also the
 545 documentation of the <code>org-diary</code> function.  Under XEmacs, it is
 546 not possible to jump back from the diary to the org, this works only in
 547 the agenda buffer.
 548 </p>
 549
 550 <p class="author"> Author: Carsten Dominik
 551 <a href="mailto:carsten.dominik@gmail.com">&lt;carsten.dominik@gmail.com&gt;</a>
 552 </p>
 553 <p class="date"> Date: 2007/09/10 07:06:01</p>
 554 </body>
 555 </html>