Release 4.62
[org-mode/org-mode-NeilSmithlineMods.git] / org.texi
blob73d5738da486fd659f127d8f9b5b6f01ca8823e7
1 \input texinfo
2 @c %**start of header
3 @setfilename ../info/org
4 @settitle Org Mode Manual
6 @set VERSION 4.62
7 @set DATE January 2007
9 @dircategory Emacs
10 @direntry
11 * Org Mode: (org).      outline-based notes management and organizer
12 @end direntry
14 @c Version and Contact Info
15 @set MAINTAINERSITE @uref{http://www.astro.uva.nl/~dominik/Tools/org/,maintainers webpage}
16 @set AUTHOR Carsten Dominik
17 @set MAINTAINER Carsten Dominik
18 @set MAINTAINEREMAIL @email{dominik at science dot uva dot nl}
19 @set MAINTAINERCONTACT @uref{mailto:dominik at science dot uva dot nl,contact the maintainer}
20 @c %**end of header
21 @finalout
23 @c Macro definitions
25 @c Subheadings inside a table.
26 @macro tsubheading{text}
27 @ifinfo
28 @subsubheading \text\
29 @end ifinfo
30 @ifnotinfo
31 @item @b{\text\}
32 @end ifnotinfo
33 @end macro
35 @copying
36 This manual is for Org-mode (version @value{VERSION}).
38 Copyright @copyright{} 2004, 2005, 2006, 2007 Free Software Foundation
40 @quotation
41 Permission is granted to copy, distribute and/or modify this document
42 under the terms of the GNU Free Documentation License, Version 1.1 or
43 any later version published by the Free Software Foundation; with no
44 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
45 and with the Back-Cover Texts as in (a) below.  A copy of the
46 license is included in the section entitled ``GNU Free Documentation
47 License.''
49 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
50 this GNU Manual, like GNU software.  Copies published by the Free
51 Software Foundation raise funds for GNU development.''
52 @end quotation
53 @end copying
55 @titlepage
56 @title Org Mode Manual
58 @subtitle Release @value{VERSION}
59 @author by Carsten Dominik
61 @c The following two commands start the copyright page.
62 @page
63 @vskip 0pt plus 1filll
64 @insertcopying
65 @end titlepage
67 @c Output the table of contents at the beginning.
68 @contents
70 @ifnottex
71 @node Top, Introduction, (dir), (dir)
72 @top Org Mode Manual
74 @insertcopying
75 @end ifnottex
77 @menu
78 * Introduction::                Getting started
79 * Document structure::          A tree works like your brain
80 * Tables::                      Pure magic for quick formatting
81 * Hyperlinks::                  Notes in context
82 * TODO items::                  Every tree branch can be a TODO item
83 * Timestamps::                  Assign date and time to items
84 * Tags::                        Tagging headlines and matching sets of tags
85 * Agenda views::                Collecting information into views
86 * Embedded LaTeX::              LaTeX fragments and formulas
87 * Exporting::                   Sharing and publishing of notes
88 * Publishing::                  Create a web site of linked Org-mode files
89 * Miscellaneous::               All the rest which did not fit elsewhere
90 * Extensions and Hacking::      It is possible to write add-on code
91 * History and Acknowledgments::  How Org-mode came into being 
92 * Index::                       The fast road to specific information
93 * Key Index::                   Key bindings and where they are described
95 @detailmenu
96  --- The Detailed Node Listing ---
98 Introduction
100 * Summary::                     Brief summary of what Org-mode does
101 * Installation::                How to install a downloaded version of Org-mode
102 * Activation::                  How to activate Org-mode for certain buffers.
103 * Feedback::                    Bug reports, ideas, patches etc.
105 Document Structure
107 * Outlines::                    Org-mode is based on outline-mode
108 * Headlines::                   How to typeset org-tree headlines
109 * Visibility cycling::          Show and hide, much simplified
110 * Motion::                      Jumping to other headlines
111 * Structure editing::           Changing sequence and level of headlines
112 * Archiving::                   Move done task trees to a different place
113 * Sparse trees::                Matches embedded in context
114 * Plain lists::                 Additional structure within an entry
116 Archiving
118 * ARCHIVE tag::                 Marking a tree as inactive
119 * Moving subtrees::             Moving a tree to an archive file
121 Tables
123 * Built-in table editor::       Simple tables
124 * Narrow columns::              Stop wasting space in tables   
125 * orgtbl-mode::                 The table editor as minor mode
126 * The spreadsheet::             The table editor has spreadsheet capabilities.
128 The spreadsheet
130 * References::                  How to refer to another field or range
131 * Formula syntax for Calc::     Using Calc to compute stuff
132 * Formula syntax for Lisp::     Writing formulas in Emacs Lisp
133 * Field formulas::              Formulas valid for a single field
134 * Column formulas::             Formulas valid for an entire column
135 * Editing and debuggung formulas::  Fixing formulas
136 * Updating the table::          Recomputing all dependent fields
137 * Advanced features::           Field names, parameters and automatic recalc
139 Hyperlinks
141 * Link format::                 How links in Org-mode are formatted
142 * Internal links::              Links to other places in the current file
143 * External links::              URL-like links to the world
144 * Handling links::              Creating, inserting and following
145 * Link abbreviations::          Shortcuts for writing complex links
146 * Search options::              Linking to a specific location
147 * Custom searches::             When the default search is not enough
148 * Remember::                    Org-trees store quick notes
150 Internal links
152 * Radio targets::               Make targets trigger links in plain text.
153 * CamelCase links::             Activating CamelCase words as links
155 TODO items
157 * TODO basics::                 Marking and displaying TODO entries
158 * TODO extensions::             Workflow and assignments
159 * Priorities::                  Some things are more important than others
160 * Breaking down tasks::         Splitting a task into managable pieces
161 * Checkboxes::                  Tick-off lists
163 Extended use of TODO keywords
165 * Workflow states::             From TODO to DONE in steps
166 * TODO types::                  I do this, Fred the rest
167 * Per file keywords::           Different files, different requirements
169 Timestamps
171 * Time stamps::                 Assigning a time to a tree entry
172 * Creating timestamps::         Commands which insert timestamps
173 * Custom time format::          If you cannot work with the ISO format
174 * Repeating items::             Deadlines that come back again and again
175 * Progress logging::            Documenting when what work was done.
177 Creating timestamps
179 * The date/time prompt::        How org-mode helps you entering date and time
181 Progress Logging
183 * Closing items::               When was this entry marked DONE?
184 * Tracking TODO state changes::  When did the status change?
185 * Clocking work time::          When exactly did you work on this item?
187 Tags
189 * Tag inheritance::             Tags use the tree structure of the outline
190 * Setting tags::                How to assign tags to a headline
191 * Tag searches::                Searching for combinations of tags
193 Agenda Views
195 * Agenda files::                Files being searched for agenda information
196 * Agenda dispatcher::           Keyboard access to agenda views
197 * Built-in agenda views::       What is available out of the box?
198 * Presentation and sorting::    How agenda items are prepared for display
199 * Agenda commands::             Remote editing of org trees
200 * Custom agenda views::         Defining special searches and views
202 The built-in agenda views
204 * Weekly/Daily agenda::         The calendar page with current tasks
205 * Global TODO list::            All unfinished action items
206 * Matching headline tags::      Structured information with fine-tuned search
207 * Timeline::                    Time-sorted view for single file
208 * Stuck projects::              Find projects you need to review
210 Presentation and sorting
212 * Categories::                  Not all tasks are equal
213 * Time-of-day specifications::  How the agenda knows the time
214 * Sorting of agenda items::     The order of things
216 Custom agenda views
218 * Storing searches::            Type once, use often
219 * Block agenda::                All the stuff you need in a single buffer
220 * Setting Options::             Changing the rules
221 * Batch processing::            Agenda views from the command line
223 Embedded LaTeX
225 * Math symbols::                TeX macros for symbols and Greek letters
226 * Subscripts and Superscripts::  Simple syntax for raising/lowering text
227 * LaTeX fragments::             Complex formulas made easy
228 * Processing LaTeX fragments::  Previewing LaTeX processing
229 * CDLaTeX mode::                Speed up entering of formulas
231 Exporting
233 * ASCII export::                Exporting to plain ASCII
234 * HTML export::                 Exporting to HTML
235 * XOXO export::                 Exporting to XOXO
236 * iCalendar export::            Exporting in iCalendar format
237 * Text interpretation::         How the exporter looks at the file
239 HTML export
241 * Export commands::             How to invode HTML export
242 * Quoting HTML tags::           Using direct HTML in Org-mode
243 * Links::                       How hyperlinks get transferred to HTML
244 * Images::                      To inline or not to inline?
245 * CSS support::                 Style specifications
247 Text interpretation by the exporter
249 * Comment lines::               Some lines will not be exported
250 * Enhancing text::              Subscripts, symbols and more
251 * Export options::              How to influence the export settings
253 Publishing
255 * Configuration::               Defining projects
256 * Sample configuration::        Example projects
257 * Triggering publication::      Publication commands
259 Configuration
261 * Project alist::               The central configuration variable
262 * Sources and destinations::    From here to there
263 * Selecting files::             What files are part of the project?
264 * Publishing action::           Setting the function doing the publishing
265 * Publishing options::          Tweaking HTML export
266 * Publishing links::            Which links keep working after publishing?
267 * Project page index::          Publishing a list of project files
269 Sample configuration
271 * Simple example::              One-component publishing
272 * Complex example::             A multi-component publishing example
274 Miscellaneous
276 * Completion::                  M-TAB knows what you need
277 * Customization::               Adapting Org-mode to your taste
278 * In-buffer settings::          Overview of the #+KEYWORDS
279 * The very busy C-c C-c key::   When in doubt, press C-c C-c
280 * Clean view::                  Getting rid of leading stars in the outline
281 * TTY keys::                    Using Org-mode on a tty
282 * Interaction::                 Other Emacs packages
283 * Bugs::                        Things which do not work perfectly
285 Interaction with other packages
287 * Cooperation::                 Packages Org-mode cooperates with
288 * Conflicts::                   Packages that lead to conflicts
290 Extensions, Hooks and Hacking
292 * Extensions::                  Existing 3rd-part extensions
293 * Dynamic blocks::              Automatically filled blocks
294 * Special agenda views::        
296 @end detailmenu
297 @end menu
299 @node Introduction, Document structure, Top, Top
300 @chapter Introduction
301 @cindex introduction
303 @menu
304 * Summary::                     Brief summary of what Org-mode does
305 * Installation::                How to install a downloaded version of Org-mode
306 * Activation::                  How to activate Org-mode for certain buffers.
307 * Feedback::                    Bug reports, ideas, patches etc.
308 @end menu
310 @node Summary, Installation, Introduction, Introduction
311 @section Summary
312 @cindex summary
314 Org-mode is a mode for keeping notes, maintaining ToDo lists, and doing
315 project planning with a fast and effective plain-text system.
317 Org-mode develops organizational tasks around NOTES files that contain
318 lists or information about projects as plain text.  Org-mode is
319 implemented on top of outline-mode, which makes it possible to keep the
320 content of large files well structured.  Visibility cycling and
321 structure editing help to work with the tree.  Tables are easily created
322 with a built-in table editor.  Org-mode supports ToDo items, deadlines,
323 time stamps, and scheduling.  It dynamically compiles entries into an
324 agenda that utilizes and smoothly integrates much of the Emacs calendar
325 and diary.  Plain text URL-like links connect to websites, emails,
326 Usenet messages, BBDB entries, and any files related to the projects.
327 For printing and sharing of notes, an Org-mode file can be exported as a
328 structured ASCII file, as HTML, or (todo and agenda items only) as an
329 iCalendar file.  It can also serve as a publishing tool for a set of
330 linked webpages.
332 An important design aspect that distinguishes Org-mode from for example
333 Planner/Muse is that it encougages to store every piece of information
334 only once.  In Planner, you have project pages, day pages and possibly
335 other files, duplicating some information such as tasks.  In Org-mode,
336 you only have notes files.  In your notes you mark entries as tasks,
337 label them with tags and timestamps.  All necessary lists like a
338 schedule for the day, the agenda for a meeting, tasks lists selected by
339 tags etc are created dynamically when you need them.
341 Org-mode keeps simple things simple.  When first fired up, it should
342 feel like a straightforward, easy to use outliner.  Complexity is not
343 imposed, but a large amount of functionality is available when you need
344 it.  Org-mode can be used on different levels and in different ways, for
345 example as:
347 @example
348 @r{@bullet{} outline extension with visibility cycling and structure editing}
349 @r{@bullet{} ASCII system and table editor for taking structured notes}
350 @r{@bullet{} ASCII table editor with spreadsheet-like capabilities}
351 @r{@bullet{} TODO list editor}
352 @r{@bullet{} full agenda and planner with deadlines and work scheduling}
353 @r{@bullet{} environment to implement David Allen's GTD system}
354 @r{@bullet{} simple hypertext system, with HTML export}
355 @r{@bullet{} publishing tool to create a set of interlinked webpages}
356 @end example
358 Org-mode's automatic, context sensitive table editor with spreadsheet
359 capabilities can be integrated into any major mode by activating the
360 minor Orgtbl-mode.
362 @cindex FAQ
363 There is a website for Org-mode which provides links to the newest
364 version of Org-mode, as well as additional information, frequently asked
365 questions (FAQ), links to tutorials etc.  This page is located at
366 @uref{http://www.astro.uva.nl/~dominik/Tools/org/}.
368 @page
370 @node Installation, Activation, Summary, Introduction
371 @section Installation
372 @cindex installation
373 @cindex XEmacs
375 @b{Important:} @i{If Org-mode is part of the Emacs distribution or an
376 XEmacs package, please skip this section and go directly to
377 @ref{Activation}.}
379 If you have downloaded Org-mode from the Web, you must take the
380 following steps to install it: Go into the Org-mode distribution
381 directory and edit the top section of the file @file{Makefile}.  You
382 must set the name of the Emacs binary (likely either @file{emacs} or
383 @file{xemacs}), and the paths to the directories where local Lisp and
384 Info files are kept.  If you don't have access to the system-wide
385 directories, create your own two directories for these files, enter them
386 into the Makefile, and make sure Emacs finds the Lisp files by adding
387 the following line to @file{.emacs}:
389 @example
390 (setq load-path (cons "~/path/to/lispdir" load-path))
391 @end example
393 @b{XEmacs users now need to install the file @file{noutline.el} from
394 the @file{xemacs} subdirectory of the Org-mode distribution.  Use the
395 command:}
397 @example
398 @b{make install-noutline}
399 @end example
401 @noindent Now byte-compile and install the Lisp files with the shell
402 commands:
404 @example
405 make
406 make install
407 @end example
409 @noindent If you want to install the info documentation, use this command:
411 @example
412 make install-info
413 @end example
415 @noindent Then add to @file{.emacs}:
417 @lisp
418 ;; This line only if org-mode is not part of the X/Emacs distribution.
419 (require 'org-install)
420 @end lisp
422 @node Activation, Feedback, Installation, Introduction
423 @section Activation
424 @cindex activation
425 @cindex autoload
426 @cindex global keybindings
427 @cindex keybindings, global
429 @iftex
430 @b{Important:} @i{If you use copy-and-paste to copy lisp code from the
431 PDF documentation to your .emacs file, the single quote character comes
432 out incorrectly and the code will not work.  You need to fix the single
433 quotes by hand, or copy from Info documentation.}
434 @end iftex
436 Add the following lines to your @file{.emacs} file.  The last two lines
437 define @emph{global} keys for the commands @command{org-store-link} and
438 @command{org-agenda} - please choose suitable keys yourself.
440 @lisp
441 ;; The following lines are always needed.  Choose your own keys.
442 (add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
443 (define-key global-map "\C-cl" 'org-store-link)
444 (define-key global-map "\C-ca" 'org-agenda)
445 @end lisp
447 Furthermore, you must activate @code{font-lock-mode} in org-mode
448 buffers, because significant functionality depends on font-locking being
449 active.  You can do this with either one of the following two lines
450 (XEmacs user must use the second option):
451 @lisp
452 (global-font-lock-mode 1)                     ; for all buffers
453 (add-hook 'org-mode-hook 'turn-on-font-lock)  ; org-mode buffers only
454 @end lisp
456 @cindex org-mode, turning on
457 With this setup, all files with extension @samp{.org} will be put
458 into Org-mode.  As an alternative, make the first line of a file look
459 like this:
461 @example
462 MY PROJECTS    -*- mode: org; -*-
463 @end example
465 @noindent which will select Org-mode for this buffer no matter what
466 the file's name is.  See also the variable
467 @code{org-insert-mode-line-in-empty-file}.
469 @node Feedback,  , Activation, Introduction
470 @section Feedback
471 @cindex feedback
472 @cindex bug reports
473 @cindex maintainer
474 @cindex author
476 If you find problems with Org-mode, or if you have questions, remarks,
477 or ideas about it, please contact the maintainer @value{MAINTAINER} at
478 @value{MAINTAINEREMAIL}.
480 For bug reports, please provide as much information as possible,
481 including the version information of Emacs (@kbd{C-h v emacs-version
482 @key{RET}}) and Org-mode (@kbd{C-h v org-version @key{RET}}), as well as
483 the Org-mode related setup in @file{.emacs}.  If an error occurs, a
484 backtrace can be very useful (see below on how to create one).  Often a
485 small example file helps, along with clear information about:
487 @enumerate
488 @item What exactly did you do?
489 @item What did you expect to happen?
490 @item What happened instead?
491 @end enumerate
492 @noindent Thank you for helping to improve this mode.
494 @subsubheading How to create a useful backtrace
496 @cindex backtrace of an error
497 If working with Org-mode produces an error with a message you don't
498 understand, you may have hit a bug.  The best way to report this is by
499 providing, in addition to what was mentioned above, a @emph{Backtrace}.
500 This is information from the built-in debugger about where and how the
501 error occurred.  Here is how to produce a useful backtrace:
503 @enumerate
504 @item
505 Start a fresh Emacs or XEmacs, and make sure that it will load the
506 original Lisp code in @file{org.el} instead of the compiled version in
507 @file{org.elc}.  The backtrace contains much more information if it is
508 produced with uncompiled code.  To do this, either rename @file{org.elc}
509 to something else before starting Emacs, or ask Emacs explicitly to load
510 @file{org.el} by using the command line
511 @example
512 emacs -l /path/to/org.el
513 @end example
514 @item
515 Go to the @code{Options} menu and select @code{Enter Debugger on Error}
516 (XEmacs has this option in the @code{Troubleshooting} sub-menu).
517 @item
518 Do whatever you have to do to hit the error.  Don't forget to
519 document the steps you take.
520 @item
521 When you hit the error, a @file{*Backtrace*} buffer will appear on the
522 screen.  Save this buffer to a file (for example using @kbd{C-x C-w}) and
523 attach it to your bug report.
524 @end enumerate
526 @node Document structure, Tables, Introduction, Top
527 @chapter Document Structure
528 @cindex document structure
529 @cindex structure of document
531 Org-mode is based on outline mode and provides flexible commands to
532 edit the structure of the document.
534 @menu
535 * Outlines::                    Org-mode is based on outline-mode
536 * Headlines::                   How to typeset org-tree headlines
537 * Visibility cycling::          Show and hide, much simplified
538 * Motion::                      Jumping to other headlines
539 * Structure editing::           Changing sequence and level of headlines
540 * Archiving::                   Move done task trees to a different place
541 * Sparse trees::                Matches embedded in context
542 * Plain lists::                 Additional structure within an entry
543 @end menu
545 @node Outlines, Headlines, Document structure, Document structure
546 @section Outlines
547 @cindex outlines
548 @cindex outline-mode
550 Org-mode is implemented on top of outline-mode.  Outlines allow to
551 organize a document in a hierarchical structure, which (at least for
552 me) is the best representation of notes and thoughts.  Overview over
553 this structure is achieved by folding (hiding) large parts of the
554 document to show only the general document structure and the parts
555 currently being worked on.  Org-mode greatly simplifies the use of
556 outlines by compressing the entire show/hide functionality into a
557 single command @command{org-cycle}, which is bound to the @key{TAB}
558 key.
560 @node Headlines, Visibility cycling, Outlines, Document structure
561 @section Headlines
562 @cindex headlines
563 @cindex outline tree
565 Headlines define the structure of an outline tree.  The headlines in
566 Org-mode start with one or more stars, on the left margin.  For
567 example:
569 @example
570 * Top level headline
571 ** Second level
572 *** 3rd level
573     some text
574 *** 3rd level
575     more text
576 * Another top level headline
577 @end example
579 @noindent Some people find the many stars too noisy and would prefer an
580 outline that has whitespace followed by a single star as headline
581 starters.  @ref{Clean view} describes a setup to realize this.
583 @node Visibility cycling, Motion, Headlines, Document structure
584 @section Visibility cycling
585 @cindex cycling, visibility
586 @cindex visibility cycling
587 @cindex trees, visibility
588 @cindex show hidden text
589 @cindex hide text
591 Outlines make it possible to hide parts of the text in the buffer.
592 Org-mode uses just two commands, bound to @key{TAB} and
593 @kbd{S-@key{TAB}} to change the visibility in the buffer.
595 @cindex subtree visibility states
596 @cindex subtree cycling
597 @cindex folded, subtree visibility state
598 @cindex children, subtree visibility state
599 @cindex subtree, subtree visibility state
600 @table @kbd
601 @kindex @key{TAB}
602 @item @key{TAB}
603 @emph{Subtree cycling}: Rotate current subtree between the states
605 @example
606 ,-> FOLDED -> CHILDREN -> SUBTREE --.
607 '-----------------------------------'
608 @end example
610 The cursor must be on a headline for this to work@footnote{see, however,
611 the option @code{org-cycle-emulate-tab}.}.  When the cursor is at the
612 beginning of the buffer and the first line is not a headline, then
613 @key{TAB} actually runs global cycling (see below)@footnote{see the
614 option @code{org-cycle-global-at-bob}.}.  Also when called with a prefix
615 argument (@kbd{C-u @key{TAB}}), global cycling is invoked.
617 @cindex global visibility states
618 @cindex global cycling
619 @cindex overview, global visibility state
620 @cindex contents, global visibility state
621 @cindex show all, global visibility state
622 @kindex S-@key{TAB}
623 @item S-@key{TAB}
624 @itemx C-u @key{TAB}
625 @emph{Global cycling}: Rotate the entire buffer between the states
627 @example
628 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
629 '--------------------------------------'
630 @end example
632 Note that inside tables, @kbd{S-@key{TAB}} jumps to the previous field.
634 @cindex show all, command
635 @kindex C-c C-a
636 @item C-c C-a
637 Show all.
638 @kindex C-c C-r
639 @item C-c C-r
640 Reveal context around point, showing the current entry, the following
641 heading and the hierarchy above.  Useful for working near a location
642 exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda
643 command (@pxref{Agenda commands}).  With prefix arg show, on each
644 level, all sibling headings.
645 @kindex C-c C-x b
646 @item C-c C-x b
647 Show the current subtree in an indirect buffer@footnote{The indirect
648 buffer (@pxref{Indirect Buffers,Indirect Buffers,Indirect
649 Buffers,emacs,GNU Emacs Manual}) will contain the entire buffer, but
650 will be narrowed to the current tree.  Editing the indirect buffer will
651 also change the original buffer, but without affecting visibility in
652 that buffer.}.  With numerical prefix ARG, go up to this level and then
653 take that tree.  If ARG is negative, go up that many levels.  With
654 @kbd{C-u} prefix, do not remove the previously used indirect buffer.
655 @end table
657 When Emacs first visits an Org-mode file, the global state is set to
658 OVERVIEW, i.e. only the top level headlines are visible.  This can be
659 configured through the variable @code{org-startup-folded}, or on a
660 per-file basis by adding one of the following lines anywhere in the
661 buffer:
663 @example
664 #+STARTUP: overview
665 #+STARTUP: content
666 #+STARTUP: showall
667 @end example
669 @node Motion, Structure editing, Visibility cycling, Document structure
670 @section Motion
671 @cindex motion, between headlines
672 @cindex jumping, to headlines
673 @cindex headline navigation
674 The following commands jump to other headlines in the buffer.
676 @table @kbd
677 @kindex C-c C-n
678 @item C-c C-n
679 Next heading.
680 @kindex C-c C-p
681 @item C-c C-p
682 Previous heading.
683 @kindex C-c C-f
684 @item C-c C-f
685 Next heading same level.
686 @kindex C-c C-b
687 @item C-c C-b
688 Previous heading same level.
689 @kindex C-c C-u
690 @item C-c C-u
691 Backward to higher level heading.
692 @kindex C-c C-j
693 @item C-c C-j
694 Jump to a different place without changing the current outline
695 visibility.  Shows the document structure in a temporary buffer, where
696 you can use visibility cycling (@key{TAB}) to find your destination.
697 After pressing @key{RET}, the cursor moves to the selected location in
698 the original buffer, and the headings hierarchy above it is made
699 visible.
700 @end table
702 @node Structure editing, Archiving, Motion, Document structure
703 @section Structure editing
704 @cindex structure editing
705 @cindex headline, promotion and demotion
706 @cindex promotion, of subtrees
707 @cindex demotion, of subtrees
708 @cindex subtree, cut and paste
709 @cindex pasting, of subtrees
710 @cindex cutting, of subtrees
711 @cindex copying, of subtrees
712 @cindex subtrees, cut and paste
714 @table @kbd
715 @kindex M-@key{RET}
716 @item M-@key{RET}
717 Insert new heading with same level as current.  If the cursor is in a
718 plain list item, a new item is created (@pxref{Plain lists}).  To force
719 creation of a new headline, use a prefix arg, or first press @key{RET}
720 to get to the beginning of the next line.  When this command is used in
721 the middle of a line, the line is split and the rest of the line becomes
722 the new headline.  If the command is used at the beginning of a
723 headline, the new headline is created before the current line.  If at
724 the beginning of any other line, the content of that line is made the
725 new heading.  If the command is used at the end of a folded subtree
726 (i.e. behind the ellipses at the end of a headline), then a headline
727 like the current one will be inserted after the end of the subtree.
728 @kindex M-S-@key{RET}
729 @item M-S-@key{RET}
730 Insert new TODO entry with same level as current heading.
731 @kindex M-@key{left}
732 @item M-@key{left}
733 Promote current heading by one level.
734 @kindex M-@key{right}
735 @item M-@key{right}
736 Demote current heading by one level.
737 @kindex M-S-@key{left}
738 @item M-S-@key{left}
739 Promote the current subtree by one level.
740 @kindex M-S-@key{right}
741 @item M-S-@key{right}
742 Demote the current subtree by one level.
743 @kindex M-S-@key{up}
744 @item M-S-@key{up}
745 Move subtree up (swap with previous subtree of same
746 level).
747 @kindex M-S-@key{down}
748 @item M-S-@key{down}
749 Move subtree down (swap with next subtree of same level).
750 @kindex C-c C-x C-w
751 @kindex C-c C-x C-k
752 @item C-c C-x C-w
753 @itemx C-c C-x C-k
754 Kill subtree, i.e. remove it from buffer but save in kill ring.
755 @kindex C-c C-x M-w
756 @item C-c C-x M-w
757 Copy subtree to kill ring.
758 @kindex C-c C-x C-y
759 @item C-c C-x C-y
760 Yank subtree from kill ring.  This does modify the level of the subtree to
761 make sure the tree fits in nicely at the yank position.  The yank
762 level can also be specified with a prefix arg, or by yanking after a
763 headline marker like @samp{****}.
764 @kindex C-c ^
765 @item C-c ^
766 Sort same-level entries.  When there is an active region, all entries in
767 the region will be sorted.  Otherwise the children of the current
768 headline are sorted.  The command prompts for the sorting method, which
769 can be alphabetically, numerically, by time (using the first time stamp
770 in each entry), and each of these in reverse order.  With a @kbd{C-u}
771 prefix, sorting will be case-sensitive.  With two @kbd{C-u C-u}
772 prefixes, duplicate entries will also be removed.
773 @end table
775 @cindex region, active
776 @cindex active region
777 @cindex transient-mark-mode
778 When there is an active region (transient-mark-mode), promotion and
779 demotion work on all headlines in the region.  To select a region of
780 headlines, it is best to place both point and mark at the beginning of a
781 line, mark at the beginning of the first headline, and point at the line
782 just after the last headline to change.  Note that when the cursor is
783 inside a table (@pxref{Tables}), the Meta-Cursor keys have different
784 functionality.
786 @node Archiving, Sparse trees, Structure editing, Document structure
787 @section Archiving
788 @cindex archiving
790 When a project represented by a (sub)tree is finished, you may want
791 to move the tree out of the way and to stop it from contributing to the
792 agenda.  Org-mode knows two ways of archiving.  You can mark a tree with
793 the ARCHIVE tag, or you can move an entire (sub)tree to a different
794 location.
796 @menu
797 * ARCHIVE tag::                 Marking a tree as inactive
798 * Moving subtrees::             Moving a tree to an archive file
799 @end menu
801 @node ARCHIVE tag, Moving subtrees, Archiving, Archiving
802 @subsection The ARCHIVE tag
803 @cindex internal archiving
805 A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at
806 its location in the outline tree, but behaves in the following way:
807 @itemize @minus
808 @item
809 It does not open when you attempt to do so with a visibility cycling
810 command (@pxref{Visibility cycling}).  You can force cycling archived
811 subtrees with @kbd{C-@key{TAB}}, or by setting the option
812 @code{org-cycle-open-archived-trees}.  Also normal outline commands like
813 @code{show-all} will open archived subtrees.
814 @item
815 During sparse tree construction (@pxref{Sparse trees}), matches in
816 archived subtrees are not exposed, unless you configure the option
817 @code{org-sparse-tree-open-archived-trees}.
818 @item
819 During agenda view construction (@pxref{Agenda views}), the content of
820 archived trees is ignored unless you configure the option
821 @code{org-agenda-skip-archived-trees}.
822 @item
823 Archived trees are not exported (@pxref{Exporting}), only the headline
824 is.  Configure the details using the variable
825 @code{org-export-with-archived-trees}.
826 @end itemize
828 The following commands help managing the ARCHIVE tag:
830 @table @kbd
831 @kindex C-c C-x C-a
832 @item C-c C-x C-a
833 Toggle the ARCHIVE tag for the current headline.  When the tag is set,
834 the headline changes to a shadowish face, and the subtree below it is
835 hidden.
836 @kindex C-u C-c C-x C-a
837 @item C-u C-c C-x C-a
838 Check if any direct children of the current headline should be archived.
839 To do this, each subtree is checked for open TODO entries.  If none are
840 found, the command offers to set the ARCHIVE tag for the child.  If the
841 cursor is @emph{not} on a headline when this command is invoked, the
842 level 1 trees will be checked.
843 @kindex C-@kbd{TAB}
844 @item C-@kbd{TAB}
845 Cycle a tree even if it is tagged with ARCHIVE.
846 @end table
848 @node Moving subtrees,  , ARCHIVE tag, Archiving
849 @subsection Moving subtrees
850 @cindex external archiving
852 Once an entire project is finished, you may want to move it to a
853 different location, either in the current file, or even in a different
854 file, the archive file.
856 @table @kbd
857 @kindex C-c C-x C-s
858 @item C-c C-x C-s
859 Archive the subtree starting at the cursor position to the location
860 given by @code{org-archive-location}.
861 @kindex C-u C-c C-x C-s
862 @item C-u C-c C-x C-s
863 Check if any direct children of the current headline could be moved to
864 the archive.  To do this, each subtree is checked for open TODO entries.
865 If none are found, the command offers to move it to the archive
866 location.  If the cursor is @emph{not} on a headline when this command
867 is invoked, the level 1 trees will be checked.
868 @end table
870 @cindex archive locations
871 The default archive location is a file in the same directory as the
872 current file, with the name derived by appending @file{_archive} to the
873 current file name.  For information and examples on how to change this,
874 see the documentation string of the variable
875 @code{org-archive-location}.  There is also an in-buffer option for
876 setting this variable, for example
878 @example
879 #+ARCHIVE: %s_done::
880 @end example
882 @noindent
883 You may have several such lines in the buffer, they will then be valid
884 for the entries following the line (the first will also apply to any
885 text before it).
887 @node Sparse trees, Plain lists, Archiving, Document structure
888 @section Sparse trees
889 @cindex sparse trees
890 @cindex trees, sparse
891 @cindex folding, sparse trees
892 @cindex occur, command
894 An important feature of Org-mode is the ability to construct
895 @emph{sparse trees} for selected information in an outline tree.  A
896 sparse tree means that the entire document is folded as much as
897 possible, but the selected information is made visible along with the
898 headline structure above it@footnote{See also the variables
899 @code{org-show-hierarchy-above}, @code{org-show-following-heading}, and
900 @code{org-show-siblings} for detailed control on how much context is
901 shown around each match.}.  Just try it out and you will see immediately
902 how it works.
904 Org-mode contains several commands creating such trees.  The most
905 basic one is @command{org-occur}:
907 @table @kbd
908 @kindex C-c /
909 @item C-c /
910 Occur.  Prompts for a regexp and shows a sparse tree with all matches.
911 If the match is in a headline, the headline is made visible.  If the
912 match is in the body of an entry, headline and body are made visible.
913 In order to provide minimal context, also the full hierarchy of
914 headlines above the match is shown, as well as the headline following
915 the match.  Each match is also highlighted; the highlights disappear
916 when the bufer is changes an editing command, or by pressing @kbd{C-c
917 C-c}.  When called with a @kbd{C-u} prefix argument, previous highlights
918 are kept, so several calls to this command can be stacked.
919 @end table
920 @noindent
921 For frequently used sparse trees of specific search strings, you can
922 use the variable @code{org-agenda-custom-commands} to define fast
923 keyboard access to specific sparse trees.  These commands will then be
924 accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
925 For example:
927 @lisp
928 (setq org-agenda-custom-commands
929       '(("f" occur-tree "FIXME")))
930 @end lisp
932 @noindent will define the key @kbd{C-c a f} as a shortcut for creating
933 a sparse tree matching the string @samp{FIXME}.
935 Other commands use sparse trees as well.  For example @kbd{C-c
936 C-v} creates a sparse TODO tree (@pxref{TODO basics}).
938 @kindex C-c C-e v
939 @cindex printing sparse trees
940 @cindex visible text, printing
941 To print a sparse tree, you can use the Emacs command
942 @code{ps-print-buffer-with-faces} which does not print invisible parts
943 of the document @footnote{This does not work under XEmacs, because
944 XEmacs uses selective display for outlining, not text properties.}.
945 Or you can use the command @kbd{C-c C-e v} to export only the visible
946 part of the document and print the resulting file.
948 @node Plain lists,  , Sparse trees, Document structure
949 @section Plain lists
950 @cindex plain lists
951 @cindex lists, plain
952 @cindex lists, ordered
953 @cindex ordered lists
955 Within an entry of the outline tree, hand-formatted lists can provide
956 additional structure.  They also provide a way to create lists of
957 checkboxes (@pxref{Checkboxes}).  Org-mode supports editing such lists,
958 and the HTML exporter (@pxref{Exporting}) does parse and format them.
960 Org-mode knows ordered and unordered lists.  Unordered list items start
961 with @samp{-}, @samp{+}, or @samp{*}@footnote{When using @samp{*} as a
962 bullet, lines must be indented or they will be seen as top-level
963 headlines.  Also, when you are hiding leading stars to get a clean
964 outline view, plain list items starting with a star are visually
965 indistinguishable from true headlines.  In short: even though @samp{*}
966 is supported, it may be better not to use it for plain list items} as
967 bullets.  Ordered list items start with @samp{1.} or @samp{1)}.  Items
968 belonging to the same list must have the same indentation on the first
969 line.  In particular, if an ordered list reaches number @samp{10.}, then
970 the 2--digit numbers must be written left-aligned with the other numbers
971 in the list.  Indentation also determines the end of a list item.  It
972 ends before the next line that is indented like the bullet/number, or
973 less.  For example:
975 @example
976 @group
977 ** Lord of the Rings
978    My favorite scenes are (in this order)
979    1. The attack of the Rohirrim
980    2. Eowyns fight with the witch king
981       + this was already my favorite scene in the book
982       + I really like Miranda Otto.
983    3. Peter Jackson being shot by Legolas
984        - on DVD only
985       He makes a really funny face when it happens.
986    But in the end, not individual scenes matter but the film as a whole.
987 @end group
988 @end example
990 Org-mode supports these lists by tuning filling and wrapping commands to
991 deal with them correctly@footnote{Org-mode only changes the filling
992 settings for Emacs.  For XEmacs, you should use Kyle E. Jones'
993 @file{filladapt.el}.  To turn this on,  put into @file{.emacs}:
994 @example
995 (require 'filladapt)
996 @end example
999 The following commands act on items when the cursor is in the first line
1000 of an item (the line with the bullet or number).
1002 @table @kbd
1003 @kindex @key{TAB}
1004 @item @key{TAB}
1005 Items can be folded just like headline levels if you set the variable
1006 @code{org-cycle-include-plain-lists}.  The level of an item is then
1007 given by the indentation of the bullet/number.  Items are always
1008 subordinate to real headlines, however; the hierarchies remain
1009 completely separated.
1010 @kindex M-@key{RET}
1011 @item M-@key{RET}
1012 Insert new item at current level.  With prefix arg, force a new heading
1013 (@pxref{Structure editing}).  If this command is used in the middle of a
1014 line, the line is @emph{split} and the rest of the line becomes the new
1015 item.  If this command is executed in the @emph{whitespace before a bullet or
1016 number}, the new item is created @emph{before} the current item.  If the
1017 command is executed in the white space before the text that is part of
1018 an item but does not contain the bullet, a bullet is added to the
1019 current line.
1020 @kindex M-S-@key{RET}
1021 @item M-S-@key{RET}
1022 Insert a new item with a checkbox (@pxref{Checkboxes}).
1023 @kindex S-@key{up}
1024 @kindex S-@key{down}
1025 @item S-@key{up}
1026 @itemx S-@key{down}
1027 Jump to the previous/next item in the current list.
1028 @kindex M-S-@key{up}
1029 @kindex M-S-@key{down}
1030 @item M-S-@key{up}
1031 @itemx M-S-@key{down}
1032 Move the item including subitems up/down (swap with previous/next item
1033 of same indentation).  If the list is ordered, renumbering is
1034 automatic.
1035 @kindex M-S-@key{left}
1036 @kindex M-S-@key{right}
1037 @item M-S-@key{left}
1038 @itemx M-S-@key{right}
1039 Decrease/increase the indentation of the item, including subitems.
1040 Initially, the item tree is selected based on current indentation.
1041 When these commands are executed several times in direct succession,
1042 the initially selected region is used, even if the new indentation
1043 would imply a different hierarchy.  To use the new hierarchy, break
1044 the command chain with a cursor motion or so.
1045 @kindex C-c C-c
1046 @item C-c C-c
1047 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
1048 state of the checkbox.  Otherwise, if this is an ordered list, renumber
1049 the ordered list at the cursor.
1050 @end table
1052 @node Tables, Hyperlinks, Document structure, Top
1053 @chapter Tables
1054 @cindex tables
1055 @cindex editing tables
1057 Org-mode has a very fast and intuitive table editor built-in.
1058 Spreadsheet-like calculations are supported in connection with the
1059 Emacs @file{calc} package.
1061 @menu
1062 * Built-in table editor::       Simple tables
1063 * Narrow columns::              Stop wasting space in tables   
1064 * orgtbl-mode::                 The table editor as minor mode
1065 * The spreadsheet::             The table editor has spreadsheet capabilities.
1066 @end menu
1068 @node Built-in table editor, Narrow columns, Tables, Tables
1069 @section The built-in table editor
1070 @cindex table editor, builtin
1072 Org-mode makes it easy to format tables in plain ASCII.  Any line with
1073 @samp{|} as the first non-white character is considered part of a
1074 table.  @samp{|} is also the column separator.  A table might look
1075 like this:
1077 @example
1078 | Name  | Phone | Age |
1079 |-------+-------+-----|
1080 | Peter |  1234 |  17 |
1081 | Anna  |  4321 |  25 |
1082 @end example
1084 A table is re-aligned automatically each time you press @key{TAB} or
1085 @key{RET} or @kbd{C-c C-c} inside the table.  @key{TAB} also moves to
1086 the next field (@key{RET} to the next row) and creates new table rows
1087 at the end of the table or before horizontal lines.  The indentation
1088 of the table is set by the first line.  Any line starting with
1089 @samp{|-} is considered as a horizontal separator line and will be
1090 expanded on the next re-align to span the whole table width.  So, to
1091 create the above table, you would only type
1093 @example
1094 |Name|Phone|Age|
1096 @end example
1098 @noindent and then press @key{TAB} to align the table and start filling in
1099 fields.
1101 When typing text into a field, Org-mode treats @key{DEL},
1102 @key{Backspace}, and all character keys in a special way, so that
1103 inserting and deleting avoids shifting other fields.  Also, when
1104 typing @emph{immediately after the cursor was moved into a new field
1105 with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the
1106 field is automatically made blank.  If this behavior is too
1107 unpredictable for you, configure the variables
1108 @code{org-enable-table-editor} and @code{org-table-auto-blank-field}.
1110 @table @kbd
1111 @tsubheading{Creation and conversion}
1112 @kindex C-c |
1113 @item C-c |
1114 Convert the active region to table. If every line contains at least one
1115 TAB character, the function assumes that the material is tab separated.
1116 If not, lines are split at whitespace into fields.  You can use a prefix
1117 argument to indicate the minimum number of consecutive spaces required
1118 to identify a field separator (default: just one).@* 
1119 If there is no active region, this command creates an empty Org-mode
1120 table.  But it's easier just to start typing, like
1121 @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
1123 @tsubheading{Re-aligning and field motion}
1124 @kindex C-c C-c
1125 @item C-c C-c
1126 Re-align the table without moving the cursor.
1128 @kindex @key{TAB}
1129 @item @key{TAB}
1130 Re-align the table, move to the next field.  Creates a new row if
1131 necessary.
1133 @kindex S-@key{TAB}
1134 @item S-@key{TAB}
1135 Re-align, move to previous field.
1137 @kindex @key{RET}
1138 @item @key{RET}
1139 Re-align the table and move down to next row.  Creates a new row if
1140 necessary.  At the beginning or end of a line, @key{RET} still does
1141 NEWLINE, so it can be used to split a table.
1143 @tsubheading{Column and row editing}
1144 @kindex M-@key{left}
1145 @kindex M-@key{right}
1146 @item M-@key{left}
1147 @itemx M-@key{right}
1148 Move the current column left/right.
1150 @kindex M-S-@key{left}
1151 @item M-S-@key{left}
1152 Kill the current column.
1154 @kindex M-S-@key{right}
1155 @item M-S-@key{right}
1156 Insert a new column to the left of the cursor position.
1158 @kindex M-@key{up}
1159 @kindex M-@key{down}
1160 @item M-@key{up}
1161 @itemx M-@key{down}
1162 Move the current row up/down.
1164 @kindex M-S-@key{up}
1165 @item M-S-@key{up}
1166 Kill the current row or horizontal line.
1168 @kindex M-S-@key{down}
1169 @item M-S-@key{down}
1170 Insert a new row above (with arg: below) the current row.
1172 @kindex C-c -
1173 @item C-c -
1174 Insert a horizontal line below current row. With prefix arg, the line
1175 is created above the current line.
1177 @kindex C-c ^
1178 @item C-c ^
1179 Sort the table lines in the region.  The position of point indicates the
1180 column to be used for sorting, and the range of lines is the range
1181 between the nearest horizontal separator lines, or the entire table.  If
1182 point is before the first column, you will be prompted for the sorting
1183 column.  If there is an active region, the mark specifies the first line
1184 and the sorting column, while point should be in the last line to be
1185 included into the sorting.  The command prompts for the sorting type
1186 (alphabetically, numerically, or by time).  When called with a prefix
1187 argument, alphabetic sorting will be case-sensitive.
1189 @tsubheading{Regions}
1190 @kindex C-c C-x M-w
1191 @item C-c C-x M-w
1192 Copy a rectangular region from a table to a special clipboard.  Point
1193 and mark determine edge fields of the rectangle.  The process ignores
1194 horizontal separator lines.
1195 @kindex C-c C-x C-w
1196 @item C-c C-x C-w
1197 Copy a rectangular region from a table to a special clipboard, and
1198 blank all fields in the rectangle.  So this is the ``cut'' operation.
1199 @kindex C-c C-x C-y
1200 @item C-c C-x C-y
1201 Paste a rectangular region into a table.
1202 The upper right corner ends up in the current field.  All involved fields
1203 will be overwritten.  If the rectangle does not fit into the present table,
1204 the table is enlarged as needed.  The process ignores horizontal separator
1205 lines.
1206 @kindex C-c C-q
1207 @item C-c C-q
1208 Wrap several fields in a column like a paragraph.  If there is an active
1209 region, and both point and mark are in the same column, the text in the
1210 column is wrapped to minimum width for the given number of lines.  A
1211 prefix ARG may be used to change the number of desired lines.  If there
1212 is no region, the current field is split at the cursor position and the
1213 text fragment to the right of the cursor is prepended to the field one
1214 line down. If there is no region, but you specify a prefix ARG, the
1215 current field is made blank, and the content is appended to the field
1216 above.
1218 @tsubheading{Calculations}
1219 @cindex formula, in tables
1220 @cindex calculations, in tables
1222 @cindex region, active
1223 @cindex active region
1224 @cindex transient-mark-mode
1225 @kindex C-c +
1226 @item C-c +
1227 Sum the numbers in the current column, or in the rectangle defined by
1228 the active region.  The result is shown in the echo area and can
1229 be inserted with @kbd{C-y}.
1231 @kindex S-@key{RET}
1232 @item S-@key{RET}
1233 When current field is empty, copy from first non-empty field above.
1234 When not empty, copy current field down to next row and move cursor
1235 along with it.  Depending on the variable
1236 @code{org-table-copy-increment}, integer field values will be
1237 incremented during copy.  This key is also used by CUA-mode
1238 (@pxref{Cooperation}).
1240 @tsubheading{Miscellaneous}
1241 @kindex C-c `
1242 @item C-c `
1243 Edit the current field in a separate window.  This is useful for fields
1244 that are not fully visible (@pxref{Narrow columns}).  When called with a
1245 @kbd{C-u} prefix, just make the full field visible, so that it can be
1246 edited in place.
1248 @kindex C-c @key{TAB}
1249 @item C-c @key{TAB}
1250 This is an alias for @kbd{C-u C-c `} to make the current field fully
1251 visible.
1253 @item M-x org-table-import
1254 Import a file as a table.  The table should be TAB- or whitespace
1255 separated.  Useful, for example, to import an Excel table or data from a
1256 database, because these programs generally can write TAB-separated text
1257 files.  This command works by inserting the file into the buffer and
1258 then converting the region to a table.  Any prefix argument is passed on
1259 to the converter, which uses it to determine the separator.
1261 @item M-x org-table-export
1262 Export the table as a TAB-separated file.  Useful for data exchange with,
1263 for example, Excel or database programs.
1265 @end table
1267 If you don't like the automatic table editor because it gets in your
1268 way on lines which you would like to start with @samp{|}, you can turn
1269 it off with
1271 @lisp
1272 (setq org-enable-table-editor nil)
1273 @end lisp
1275 @noindent Then the only table command that still works is
1276 @kbd{C-c C-c} to do a manual re-align.
1278 @node Narrow columns, orgtbl-mode, Built-in table editor, Tables
1279 @section Narrow columns
1280 @cindex narrow columns in tables
1282 The width of columns is automatically determined by the table editor.
1283 Sometimes a single field or a few fields need to carry more text,
1284 leading to inconveniently wide columns.  To limit@footnote{This feature
1285 does not work on XEmacs.} the width of a column, one field anywhere in
1286 the column may contain just the string @samp{<N>} where @samp{N} is an
1287 integer specifying the width of the column in characters.  The next
1288 re-align will then set the width of this column to no more than this
1289 value.
1291 @example
1292 @group
1293 |---+------------------------------|               |---+--------|
1294 |   |                              |               |   | <6>    |
1295 | 1 | one                          |               | 1 | one    |
1296 | 2 | two                          |     ----\     | 2 | two    |
1297 | 3 | This is a long chunk of text |     ----/     | 3 | This=> |
1298 | 4 | four                         |               | 4 | four   |
1299 |---+------------------------------|               |---+--------|
1300 @end group
1301 @end example
1303 @noindent
1304 Fields that are wider become clipped and end in the string @samp{=>}.
1305 Note that the full text is still in the buffer, it is only invisible.
1306 To see the full text, hold the mouse over the field - a tooltip window
1307 will show the full content.  To edit such a field, use the command
1308 @kbd{C-c `} (that is @kbd{C-c} followed by the backquote).  This will
1309 open a new window with the full field.  Edit it and finish with @kbd{C-c
1310 C-c}.
1312 When visiting a file containing a table with narrowed columns, the
1313 necessary character hiding has not yet happened, and the table needs to
1314 be aligned before it looks nice.  Setting the option
1315 @code{org-startup-align-all-tables} will realign all tables in a file
1316 upon visiting, but also slow down startup.  You can also set this option
1317 on a per-file basis with:
1319 @example
1320 #+STARTUP: align
1321 #+STARTUP: noalign
1322 @end example
1324 @node orgtbl-mode, The spreadsheet, Narrow columns, Tables
1325 @section The Orgtbl minor mode
1326 @cindex orgtbl-mode
1327 @cindex minor mode for tables
1329 If you like the intuitive way the Org-mode table editor works, you
1330 might also want to use it in other modes like text-mode or mail-mode.
1331 The minor mode Orgtbl-mode makes this possible.  You can always toggle
1332 the mode with @kbd{M-x orgtbl-mode}.  To turn it on by default, for
1333 example in mail mode, use
1335 @lisp
1336 (add-hook 'mail-mode-hook 'turn-on-orgtbl)
1337 @end lisp
1339 @node The spreadsheet,  , orgtbl-mode, Tables
1340 @section The spreadsheet
1341 @cindex calculations, in tables
1342 @cindex spreadsheet capabilities
1343 @cindex @file{calc} package
1345 The table editor makes use of the Emacs @file{calc} package to implement
1346 spreadsheet-like capabilities.  It can also evaluate Emacs Lisp forms to
1347 derive fields from other fields.
1348 @menu
1349 * References::                  How to refer to another field or range
1350 * Formula syntax for Calc::     Using Calc to compute stuff
1351 * Formula syntax for Lisp::     Writing formulas in Emacs Lisp
1352 * Field formulas::              Formulas valid for a single field
1353 * Column formulas::             Formulas valid for an entire column
1354 * Editing and debuggung formulas::  Fixing formulas
1355 * Updating the table::          Recomputing all dependent fields
1356 * Advanced features::           Field names, parameters and automatic recalc
1357 @end menu
1359 @node References, Formula syntax for Calc, The spreadsheet, The spreadsheet
1360 @subsection References
1361 @cindex references
1363 To compute fields in the table from other fields, formulas must
1364 reference other fields or ranges.  In Org-mode, fields can be referenced
1365 by name, by absolute coordinates, and by relative coordinates.  To find
1366 out what the coordinates of a field are, press @kbd{C-c ?} in that
1367 field.
1369 @subsubheading Field references
1370 @cindex field references
1371 @cindex references, to fields
1373 Formulas can reference the value of another field with the operator
1374 @example
1375 @@row$column
1376 @end example
1378 Column references can be absolute like @samp{1}, @samp{2},...@samp{N},
1379 or relative to the current column like @samp{+1} or @samp{-2}.
1381 The row specification only counts data lines and ignores horizontal
1382 separator lines (hlines).  You can use absolute row numbers
1383 @samp{1}...@samp{N}, and row numbers relative to the current row like
1384 @samp{+3} or @samp{-1}.  Or specify the row relative to one of the
1385 hlines: @samp{I} refers to the first hline, @samp{II} to the second etc.
1386 @samp{-I} refers to the first such line above the current line,
1387 @samp{+I} to the first such line below the current line.  You can also
1388 write @samp{III+2} which is the second data line after the third hline
1389 in the table.  Relative row numbers like @samp{-3} will not cross hlines
1390 if the current line is too close to the hline.  Instead, the value
1391 directly at the hline is used.
1393 @samp{0} refers to the current row and column.  Also, if you omit
1394 either the column or the row part of the reference, the current
1395 row/column is implied.  Here are a few examples:
1397 @example
1398 @@2$3      @r{2nd row, 3rd column}
1399 $5        @r{column 5 in the current row}
1400 @@2        @r{current column, row 2}
1401 @@-1$-3    @r{the field one row up, three columns to the left}
1402 @@-I$2     @r{field just under hline above current row, column 2}
1403 @end example
1405 @subsubheading Range references
1406 @cindex range references
1407 @cindex references, to ranges
1409 You may reference a rectangular range of fields by specifying two field
1410 references connected by two dots @samp{..}.  If both fields are in the
1411 current row, you may simply use @samp{$2..$7}, but if at least one field
1412 is in a different row, you need to use the general @code{@@row$column}
1413 format at least for the first field (i.e the reference must start with
1414 @samp{@@} in order to be interpreted correctly).  Examples:
1416 @example
1417 $1..$3        @r{First three fields in the current row.}
1418 $P..$Q        @r{Range, using column names (see under Advanced)}
1419 @@2$1..@@4$3    @r{6 fields between these two fields.}
1420 @@-1$-2..@@-1   @r{3 numbers from the column to the left, 2 up to current row}
1421 @end example
1423 @noindent Range references return a vector of values that can be fed
1424 into Calc vector functions.  Empty fields in ranges are normally
1425 suppressed, so that the vector contains only the non-empty fields (but
1426 see the @samp{E} mode switch below).  If there are no non-empty fields,
1427 @samp{[0]} is returned to avoid syntax errors in formulas.
1429 @subsubheading Named references
1430 @cindex named references
1431 @cindex references, named
1432 @cindex name, of column or field
1433 @cindex constants, in calculations
1435 @samp{$name} is interpreted as the name of a column, parameter or
1436 constant.  Constants are defined globally through the variable
1437 @code{org-table-formula-constants}.  If you have the
1438 @file{constants.el} package, it will also be used to resolve
1439 constants, including natural constants like @samp{$h} for Planck's
1440 constant, and units like @samp{$km} for kilometers.  Column names and
1441 parameters can be specified in special table lines.  These are
1442 described below, see @ref{Advanced features}.
1444 @node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet
1445 @subsection Formula syntax for Calc
1446 @cindex formula syntax, Calc
1447 @cindex syntax, of formulas
1449 A formula can be any algebraic expression understood by the Emacs
1450 @file{Calc} package.  Note that @file{calc} has the slightly
1451 non-standard convention that @samp{/} has lower precedence than
1452 @samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.  Before
1453 evaluation by @code{calc-eval} (@pxref{Calling Calc from
1454 Your Programs,calc-eval,Calling calc from Your Lisp Programs,calc,GNU
1455 Emacs Calc Manual}),
1456 variable substitution takes place according to the rules described above.
1457 @cindex vectors, in table calculations
1458 The range vectors can be directly fed into the calc vector functions
1459 like @samp{vmean} and @samp{vsum}.
1461 @cindex format specifier
1462 @cindex mode, for @file{calc}
1463 A formula can contain an optional mode string after a semicolon.  This
1464 string consists of flags to influence Calc and other modes during
1465 execution.  By default, Org-mode uses the standard calc modes (precision
1466 12, angular units degrees, fraction and symbolic modes off.  The display
1467 format, however, has been changed to @code{(float 5)} to keep tables
1468 compact.  The default settings can be configured using the variable
1469 @code{org-calc-default-modes}.
1471 @example
1472 p20           @r{switch the internal precision to 20 digits}
1473 n3 s3 e2 f4   @r{normal, scientific, engineering, or fixed display format}
1474 D R           @r{angle modes: degrees, radians}
1475 F S           @r{fraction and symbolic modes}
1476 N             @r{interpret all fields as numbers, use 0 for non-numbers}
1477 T             @r{force text interpretation}
1478 E             @r{keep empty fields in ranges}
1479 @end example
1481 @noindent
1482 In addition, you may provide a @code{printf} format specifier to
1483 reformat the final result.  A few examples:
1485 @example
1486 $1+$2                @r{Sum of first and second field}
1487 $1+$2;%.2f           @r{Same, format result to two decimals}
1488 exp($2)+exp($1)      @r{Math functions can be used}
1489 $;%.1f               @r{Reformat current cell to 1 decimal}
1490 ($3-32)*5/9          @r{Degrees F -> C conversion}
1491 $c/$1/$cm            @r{Hz -> cm conversion, using @file{constants.el}}
1492 tan($1);Dp3s1        @r{Compute in degrees, precision 3, display SCI 1}
1493 sin($1);Dp3%.1e      @r{Same, but use printf specifier for display}
1494 vmean($2..$7)        @r{Compute column range mean, using vector function}
1495 vmean($2..$7);EN     @r{Same, but treat empty fields as 0}
1496 taylor($3,x=7,2)     @r{taylor series of $3, at x=7, second degree}
1497 @end example
1499 @node Formula syntax for Lisp, Field formulas, Formula syntax for Calc, The spreadsheet
1500 @subsection Emacs Lisp forms as formulas
1501 @cindex Lisp forms, as table formulas
1503 It is also possible to write a formula in Emacs Lisp; this can be useful
1504 for string manipulation and control structures.  If a formula starts
1505 with a single quote followed by an opening parenthesis, then it is
1506 evaluated as a lisp form.  The evaluation should return either a string
1507 or a number.  Just as with @file{calc} formulas, you can specify modes
1508 and a printf format after a semicolon.  A reference will be replaced
1509 with a string (in double quotes) containing the field.  If you provide
1510 the @samp{N} mode switch, all referenced elements will be numbers.
1511 Ranges are inserted as space-separated fields, so you can embed them in
1512 list or vector syntax.  A few examples, note how the @samp{N} mode is
1513 used when we do computations in lisp.
1515 @example
1516 @r{Swap the first two characters of the content of column 1}
1517   '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
1518 @r{Add columns 1 and 2, equivalent to the Calc's @code{$1+$2}}
1519   '(+ $1 $2);N
1520 @r{Compute the sum of columns 1-4, like Calc's @code{vsum($1..$4)}}
1521   '(apply '+ '($1..$4));N
1522 @end example
1524 @node Field formulas, Column formulas, Formula syntax for Lisp, The spreadsheet
1525 @subsection Field formulas
1526 @cindex field formula
1527 @cindex formula, for individual table field
1529 To assign a formula to a particular field, type it directly into the
1530 field, preceded by @samp{=:}, for example @samp{=:$1+$2}.  When you
1531 press @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in
1532 the field, the formula will be stored as the formula for this field,
1533 evaluated, and the current field replaced with the result.
1535 Formulas are stored in a special line starting with @samp{#+TBLFM:}
1536 directly below the table.  If you typed the equation in the 4th field of
1537 the 3rd data line in the table, the formula will look like
1538 @samp{@@3$2=$1+$2}.  When inserting/deleting/swapping column and rows
1539 with the appropriate commands, @i{absolute references} (but not relative
1540 ones) in stored formulas are modified in order to
1541 still reference the same field.  Of cause this is not true if you edit
1542 the table structure with normal editing commands - then you must go and
1543 fix equations yourself.
1545 Instead of typing an equation into the field, you may also use the
1546 following command
1548 @table @kbd
1549 @kindex C-u C-c =
1550 @item C-u C-c =
1551 Install a new formula for the current field.  The command prompts for a
1552 formula, with default taken from the @samp{#+TBLFM:} line, applies
1553 it to the current field and stores it.
1554 @end table
1556 @node Column formulas, Editing and debuggung formulas, Field formulas, The spreadsheet
1557 @subsection Column formulas
1558 @cindex column formula
1559 @cindex formula, for table column
1561 Often in a table, the same formula should be used for all fields in a
1562 particular column.  Instead of having to copy the formula to all fields
1563 in that column, org-mode allows to assign a single formula to an entire
1564 column.
1566 To assign a formula to a column, type it directly into any field in the
1567 column, preceded by an equal sign, like @samp{=$1+$2}.  When you press
1568 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the
1569 field, the formula will be stored as the formula for the current column,
1570 evaluated and the current field replaced with the result.  If the field
1571 contains only @samp{=}, the previously stored formula for this column is
1572 used.  For each column, Org-mode will only remember the most recently
1573 used formula.  In the @samp{TBLFM:} line, column formulas will look like
1574 @samp{$4=$1+$2}.
1576 Instead of typing an equation into the field, you may also use the
1577 following command:
1579 @table @kbd
1580 @kindex C-c =
1581 @item C-c =
1582 Install a new formula for the current column and replace current field
1583 with the result of the formula.  The command prompts for a formula, with
1584 default taken from the @samp{#+TBLFM} line, applies it to the current
1585 field and stores it.  With a numerical prefix (e.g. @kbd{C-5 C-c =})
1586 will apply it to that many consecutive fields in the current column.
1587 @end table
1590 @node Editing and debuggung formulas, Updating the table, Column formulas, The spreadsheet
1591 @subsection Editing and Debugging formulas
1592 @cindex formula editing
1593 @cindex editing, of table formulas
1595 You can edit individual formulas in the minibuffer or directly in the
1596 field.  Org-mode can also prepare a special buffer with all active
1597 formulas of a table.
1599 @table @kbd
1600 @kindex C-c =
1601 @kindex C-u C-c =
1602 @item C-c =
1603 @itemx C-u C-c =
1604 Edit the formula associated with the current column/field in the
1605 minibuffer.  See @ref{Column formulas} and @ref{Field formulas}.
1606 @kindex C-u C-u C-c =
1607 @item C-u C-u C-c =
1608 Re-insert the active formula (either a
1609 field formula, or a column formula) into the current field, so that you
1610 can edit it directly in the field.  The advantage over editing in the
1611 minibuffer is that you can use the command @kbd{C-c ?}.
1612 @kindex C-c ?
1613 @item C-c ?
1614 While editing a formula in a table field, highlight the field(s)
1615 referenced by the reference at the cursor position in the formula.
1616 @kindex C-c '
1617 @item C-c '
1618 Edit all formulas for the current table in a special buffer, where the
1619 formulas will be displayed one per line. 
1620 While inside the special buffer, Org-mode will automatically highlight
1621 any field or range reference at the cursor position.  You may edit,
1622 remove and add formulas, and use the following commands:
1623 @table @kbd
1624 @kindex C-c C-c
1625 @item C-c C-c
1626 Exit the buffer and store the modified formulas.  With @kbd{C-u} prefix,
1627 also apply the new formulas to the entire table.
1628 @kindex C-c C-q
1629 @item C-c C-q
1630 Exit the buffer without installing changes.
1631 @kindex S-@key{up}
1632 @kindex S-@key{down}
1633 @item S-@key{up}/@key{down}
1634 Move the reference line in the Org-mode buffer up and down.  This is
1635 important for highlighting the references of column formulas for
1636 different rows.
1637 @kindex M-@key{up}
1638 @kindex M-@key{down}
1639 @item M-@key{up}/@key{down}
1640 Scroll the window displaying the table.
1641 @end table
1642 @end table
1644 Making a table field blank does not remove the formula associated with
1645 the field, because that is stored in a different line (the @samp{TBLFM}
1646 line) - during the next recalculation the field will be filled again.
1647 To remove a formula from a field, you have to give an empty reply when
1648 prompted for the formula, or to edit the @samp{#+TBLFM} line.
1650 @kindex C-c C-c
1651 You may edit the @samp{#+TBLFM} directly and re-apply the changed
1652 equations with @kbd{C-c C-c} in that line, or with the normal
1653 recalculation commands in the table.
1655 @subsubheading Debugging formulas
1656 @cindex formula debugging
1657 @cindex debugging, of table formulas
1658 When the evaluation of a formula leads to an error, the field content
1659 becomes the string @samp{#ERROR}.  If you would like see what is going
1660 on during variable substitution and calculation in order to find a bug,
1661 turn on formula debugging in the @code{Tbl} menu and repeat the
1662 calculation, for example by pressing @kbd{C-c = @key{RET}} in a field.
1663 Detailed information will be displayed.
1665 @node Updating the table, Advanced features, Editing and debuggung formulas, The spreadsheet
1666 @subsection Updating the Table
1667 @cindex recomputing table fields
1668 @cindex updating, table
1670 Recalculation of a table is normally not automatic, but needs to be
1671 triggered by a command.  See @ref{Advanced features} for a way to make
1672 recalculation at least semi-automatically.
1674 In order to recalculate a line of a table or the entire table, use the
1675 following commands:
1677 @table @kbd
1678 @kindex C-c *
1679 @item C-c *
1680 Recalculate the current row by first applying the stored column formulas
1681 from left to right, and all field formulas in the current row.
1683 @kindex C-u C-c *
1684 @item C-u C-c *
1685 @kindex C-u C-c C-c
1686 @itemx C-u C-c C-c
1687 Recompute the entire table, line by line.  Any lines before the first
1688 hline are left alone, assuming that these are part of the table header.
1690 @kindex C-u C-u C-c *
1691 @item C-u C-u C-c *
1692 Iterate the table by recomputing it until no further changes occur.
1693 This may be necessary if some computed fields use the value of other
1694 fields that are computed @i{later} in the calculation sequence.
1695 @end table
1698 @node Advanced features,  , Updating the table, The spreadsheet
1699 @subsection Advanced features
1701 If you want the recalculation of fields to happen automatically, or if
1702 you want to be able to assign @i{names} to fields and columns, you need
1703 to reserve the first column of the table for special marking characters.
1704 @table @kbd
1705 @kindex C-#
1706 @item C-#
1707 Rotate the calculation mark in first column through the states @samp{},
1708 @samp{#}, @samp{*}, @samp{!}, @samp{$}.  The meaning of these characters
1709 is discussed below.  When there is an active region, change all marks in
1710 the region.
1711 @end table
1713 Here is an example of a table that collects exam results of students and
1714 makes use of these features:
1716 @example
1717 @group
1718 |---+---------+--------+--------+--------+-------+------|
1719 |   | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
1720 |---+---------+--------+--------+--------+-------+------|
1721 | ! |         |     P1 |     P2 |     P3 |   Tot |      |
1722 | # | Maximum |     10 |     15 |     25 |    50 | 10.0 |
1723 | ^ |         |     m1 |     m2 |     m3 |    mt |      |
1724 |---+---------+--------+--------+--------+-------+------|
1725 | # | Peter   |     10 |      8 |     23 |    41 |  8.2 |
1726 | # | Sara    |      6 |     14 |     19 |    39 |  7.8 |
1727 | # | Sam     |      2 |      4 |      3 |     9 |  1.8 |
1728 |---+---------+--------+--------+--------+-------+------|
1729 |   | Average |        |        |        |  29.7 |      |
1730 | ^ |         |        |        |        |    at |      |
1731 | $ | max=50  |        |        |        |       |      |
1732 |---+---------+--------+--------+--------+-------+------|
1733 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f
1734 @end group
1735 @end example
1737 @noindent @b{Important}: Please note that for these special tables,
1738 recalculating the table with @kbd{C-u C-c *} will only affect rows that
1739 are marked @samp{#} or @samp{*}, and fields that have a formula assigned
1740 to the field itself.  The column formulas are not applied in rows with
1741 empty first field.
1743 @cindex marking characters, tables
1744 The marking characters have the following meaning:
1745 @table @samp
1746 @item !
1747 The fields in this line define names for the columns, so that you may
1748 refer to a column as @samp{$Tot} instead of @samp{$6}.
1749 @item ^
1750 This row defines names for the fields @emph{above} the row.  With such
1751 a definition, any formula in the table may use @samp{$m1} to refer to
1752 the value @samp{10}.  Also, if you assign a formula to a names field, it
1753 will be stored as @samp{$name=...}.
1754 @item _
1755 Similar to @samp{^}, but defines names for the fields in the row
1756 @emph{below}.
1757 @item $
1758 Fields in this row can define @emph{parameters} for formulas.  For
1759 example, if a field in a @samp{$} row contains @samp{max=50}, then
1760 formulas in this table can refer to the value 50 using @samp{$max}.
1761 Parameters work exactly like constants, only that they can be defined on
1762 a per-table basis.
1763 @item #
1764 Fields in this row are automatically recalculated when pressing
1765 @key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row.  Also, this row
1766 is selected for a global recalculation with @kbd{C-u C-c *}.  Unmarked
1767 lines will be left alone by this command.
1768 @item *
1769 Selects this line for global recalculation with @kbd{C-u C-c *}, but
1770 not for automatic recalculation.  Use this when automatic
1771 recalculation slows down editing too much.
1772 @item
1773 Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
1774 All lines that should be recalculated should be marked with @samp{#}
1775 or @samp{*}.
1776 @end table
1778 Finally, just to whet your appetite on what can be done with the
1779 fantastic @file{calc} package, here is a table that computes the Taylor
1780 series of degree @code{n} at location @code{x} for a couple of functions
1781 (homework: try that with Excel :-)
1783 @example
1784 @group
1785 |---+-------------+---+-----+--------------------------------------|
1786 |   | Func        | n | x   | Result                               |
1787 |---+-------------+---+-----+--------------------------------------|
1788 | # | exp(x)      | 1 | x   | 1 + x                                |
1789 | # | exp(x)      | 2 | x   | 1 + x + x^2 / 2                      |
1790 | # | exp(x)      | 3 | x   | 1 + x + x^2 / 2 + x^3 / 6            |
1791 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
1792 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2    |
1793 | * | tan(x)      | 3 | x   | 0.0175 x + 1.77e-6 x^3               |
1794 |---+-------------+---+-----+--------------------------------------|
1795 #+TBLFM: $5=taylor($2,$4,$3);n3
1796 @end group
1797 @end example
1799 @node Hyperlinks, TODO items, Tables, Top
1800 @chapter Hyperlinks
1801 @cindex hyperlinks
1803 Just like HTML, Org-mode provides links inside a file, and external
1804 links to other files, Usenet articles, emails, and much more.
1806 @menu
1807 * Link format::                 How links in Org-mode are formatted
1808 * Internal links::              Links to other places in the current file
1809 * External links::              URL-like links to the world
1810 * Handling links::              Creating, inserting and following
1811 * Link abbreviations::          Shortcuts for writing complex links
1812 * Search options::              Linking to a specific location
1813 * Custom searches::             When the default search is not enough
1814 * Remember::                    Org-trees store quick notes
1815 @end menu
1817 @node Link format, Internal links, Hyperlinks, Hyperlinks
1818 @section Link format
1819 @cindex link format
1820 @cindex format, of links
1822 Org-mode will recognize plain URL-like links and activate them as
1823 clickable links.  The general link format, however, looks like this:
1825 @example
1826 [[link][description]]       @r{or alternatively}           [[link]]  
1827 @end example
1829 Once a link in the buffer is complete (all brackets present), Org-mode
1830 will change the display so that @samp{description} is displayed instead
1831 of @samp{[[link][description]]} and @samp{link} is displayed instead of
1832 @samp{[[link]]}.  Links will be highlighted in the face @code{org-link},
1833 which by default is an underlined face.  You can directly edit the
1834 visible part of a link.  Note that this can be either the @samp{link}
1835 part (if there is no description) or the @samp{description} part.  To
1836 edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
1837 cursor on the link.
1839 If you place the cursor at the beginning or just behind the end of the
1840 displayed text and press @key{BACKSPACE}, you will remove the
1841 (invisible) bracket at that location.  This makes the link incomplete
1842 and the internals are again displayed as plain text.  Inserting the
1843 missing bracket hides the link internals again.  To show the
1844 internal structure of all links, use the menu entry
1845 @code{Org->Hyperlinks->Literal links}.
1847 @node Internal links, External links, Link format, Hyperlinks
1848 @section Internal links
1849 @cindex internal links
1850 @cindex links, internal
1851 @cindex CamelCase links
1852 @cindex targets, for links
1854 If the link does not look like a URL, it is considered to be internal in
1855 the current file.  Links such as @samp{[[My Target]]} or @samp{[[My
1856 Target][Find my target]]} lead to a text search in the current file.
1857 The link can be followed with @kbd{C-c C-o} when the cursor is on the
1858 link, or with a mouse click (@pxref{Handling links}).  The preferred
1859 match for such a link is a dedicated target: the same string in double
1860 angular brackets.  Targets may be located anywhere; often it is
1861 convenient to put them into a comment line. For example
1863 @example
1864 # <<My Target>>
1865 @end example
1867 @noindent In HTML export (@pxref{HTML export}), such targets will become
1868 named anchors for direct access through @samp{http} links@footnote{Note
1869 that text before the first headline will never be exported, so the first
1870 such target must be after the first headline.}.
1872 If no dedicated target exists, Org-mode will search for the words in the
1873 link.  In the above example the search would be for @samp{my target}.
1874 Links starting with a star like @samp{*My Target} restrict the search to
1875 headlines.  When searching, Org-mode will first try an exact match, but
1876 then move on to more and more lenient searches.  For example, the link
1877 @samp{[[*My Targets]]} will find any of the following:
1879 @example
1880 ** My targets
1881 ** TODO my targets are bright
1882 ** my 20 targets are
1883 @end example
1885 To insert a link targeting a headline, in-buffer completion can be used.
1886 Just type a star followed by a few optional letters into the buffer and
1887 press @kbd{M-@key{TAB}}.  All headlines in the current buffer will be
1888 offered as completions.  @xref{Handling links}, for more commands
1889 creating links.
1891 Following a link pushes a mark onto Org-mode's own mark ring.  You can
1892 return to the previous position with @kbd{C-c &}.  Using this command
1893 several times in direct succession goes back to positions recorded
1894 earlier.
1896 @menu
1897 * Radio targets::               Make targets trigger links in plain text.
1898 * CamelCase links::             Activating CamelCase words as links
1899 @end menu
1901 @node Radio targets, CamelCase links, Internal links, Internal links
1902 @subsection Radio targets
1903 @cindex radio targets
1904 @cindex targets, radio
1905 @cindex links, radio targets
1907 You can configure Org-mode to link any occurrences of certain target
1908 names in normal text.  So without explicitly creating a link, the text
1909 connects to the target radioing its position.  Radio targets are
1910 enclosed by triple angular brackets.  For example, a target
1911 @samp{<<<My Target>>>} causes each occurrence of @samp{my target} in
1912 normal text to become activated as a link.  The Org-mode file is
1913 scanned automatically for radio targets only when the file is first
1914 loaded into Emacs.  To update the target list during editing, press
1915 @kbd{C-c C-c} with the cursor on or at a target.
1917 @node CamelCase links,  , Radio targets, Internal links
1918 @subsection CamelCase words as links
1919 @cindex completion, of CamelCase links
1920 @cindex CamelCase links, completion of
1922 Org-mode also supports CamelCase words as links.  This feature is not
1923 turned on by default because of the inconsistencies this system suffers
1924 from.  It is also possible that this feature will disappear entirely in
1925 a future version of Org-mode.  To activate CamelCase words as links, you
1926 need to customize the option @code{org-activate-links}.  A CamelCase
1927 word then leads to a text search such that @samp{CamelCaseLink} is
1928 equivalent to @samp{[[camel case link]]}.
1930 @node External links, Handling links, Internal links, Hyperlinks
1931 @section External links
1932 @cindex links, external
1933 @cindex external links
1934 @cindex links, external
1935 @cindex GNUS links
1936 @cindex BBDB links
1937 @cindex URL links
1938 @cindex file links
1939 @cindex VM links
1940 @cindex RMAIL links
1941 @cindex WANDERLUST links
1942 @cindex MH-E links
1943 @cindex USENET links
1944 @cindex SHELL links
1945 @cindex Info links
1946 @cindex elisp links
1948 Org-mode supports links to files, websites, Usenet and email messages,
1949 and BBDB database entries.  External links are URL-like locators.  They
1950 start with a short identifying string followed by a colon.  There can be
1951 no space after the colon.  The following list shows examples for each
1952 link type.
1954 @example
1955 http://www.astro.uva.nl/~dominik          @r{on the web}
1956 file:/home/dominik/images/jupiter.jpg     @r{file, absolute path}
1957 file:papers/last.pdf                      @r{file, relative path}
1958 news:comp.emacs                           @r{Usenet link}
1959 mailto:adent@@galaxy.net                   @r{Mail link}
1960 vm:folder                                 @r{VM folder link}
1961 vm:folder#id                              @r{VM message link}
1962 vm://myself@@some.where.org/folder#id      @r{VM on remote machine}
1963 wl:folder                                 @r{WANDERLUST folder link}
1964 wl:folder#id                              @r{WANDERLUST message link}
1965 mhe:folder                                @r{MH-E folder link}
1966 mhe:folder#id                             @r{MH-E message link}
1967 rmail:folder                              @r{RMAIL folder link}
1968 rmail:folder#id                           @r{RMAIL message link}
1969 gnus:group                                @r{GNUS group link}
1970 gnus:group#id                             @r{GNUS article link}
1971 bbdb:Richard Stallman                     @r{BBDB link}
1972 shell:ls *.org                            @r{A shell command}
1973 elisp:(find-file-other-frame "Elisp.org") @r{An elisp form to evaluate}
1974 @end example
1976 A link should be enclosed in double brackets and may contain a
1977 descriptive text to be displayed instead of the url (@pxref{Link
1978 format}), for example:
1980 @example
1981 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
1982 @end example
1984 @noindent
1985 If the description is a file name or URL that points to an image, HTML
1986 export (@pxref{HTML export}) will inline the image as a clickable
1987 button.  If there is no description at all and the link points to an
1988 image,
1989 that image will be inlined into the exported HTML file.
1991 @cindex angular brackets, around links
1992 @cindex plain text external links
1993 Org-mode also finds external links in the normal text and activates them
1994 as links.  If spaces must be part of the link (for example in
1995 @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
1996 about the end of the link, enclose them in angular brackets.
1998 @node Handling links, Link abbreviations, External links, Hyperlinks
1999 @section Handling links
2000 @cindex links, handling
2002 Org-mode provides methods to create a link in the correct syntax, to
2003 insert it into an org-mode file, and to follow the link.
2005 @table @kbd
2006 @kindex C-c l
2007 @cindex storing links
2008 @item C-c l
2009 Store a link to the current location.  This is a @emph{global} command
2010 which can be used in any buffer to create a link.  The link will be
2011 stored for later insertion into an Org-mode buffer (see below).  For
2012 Org-mode files, if there is a @samp{<<target>>} at the cursor, the link
2013 points to the target.  Otherwise it points to the current headline.  For
2014 VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers, the link will
2015 indicate the current article/entry.  For W3 and W3M buffers, the link
2016 goes to the current URL.  For any other files, the link will point to
2017 the file, with a search string (@pxref{Search options}) pointing to the
2018 contents of the current line.  If there is an active region, the
2019 selected words will form the basis of the search string.  If the
2020 automatically created link is not working correctly or accurately
2021 enough, you can write custom functions to select the search string and
2022 to do the search for particular file types - see @ref{Custom searches}.
2023 The key binding @kbd{C-c l} is only a suggestion - see @ref{Installation}.
2025 @kindex C-c C-l
2026 @cindex link completion
2027 @cindex completion, of links
2028 @cindex inserting links
2029 @item C-c C-l
2030 Insert a link.  This prompts for a link to be inserted into the buffer.
2031 You can just type a link, using text for an internal link, or one of the
2032 link type prefixes mentioned in the examples above.  Through completion,
2033 all links stored during the current session can be
2034 accessed@footnote{After insertion of a stored link, the link will be
2035 removed from the list of stored links.  To keep it in the list later
2036 use, use a triple @kbd{C-u} prefix to @kbd{C-c C-l}, or configure the
2037 option @code{org-keep-stored-link-after-insertion}.}.  The link will be
2038 inserted into the buffer, along with a descriptive text.  If some text
2039 was selecten when this command is called, the selected text becomes the
2040 default description.@* Note that you don't have to use this command to
2041 insert a link.  Links in Org-mode are plain text, and you can type or
2042 paste them straight into the buffer.  By using this command, the links
2043 are automatically enclosed in double brackets, and you will be asked for
2044 the optional descriptive text.  If the link is a @samp{file:} link and
2045 the linked file is located in the same directory as the current file or
2046 a subdirectory of it, the path of the file will be inserted relative to
2047 the current directory.
2049 @kindex C-u C-c C-l
2050 @cindex file name completion
2051 @cindex completion, of file names
2052 @item C-u C-c C-l
2053 When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
2054 a file will be inserted and you may use file name completion to select
2055 the name of the file.  The path to the file is inserted relative to the
2056 directory of the current org file, if the linked file is in the current
2057 directory or in a subdirectory of it, or if the path is written relative
2058 to the current directory using @samp{../}.  Otherwise an absolute path
2059 is used, if possible with @samp{~/} for your home directory.  You can
2060 force an absolute path with two @kbd{C-u} prefixes.
2062 @item C-c C-l @r{with cursor on existing link}
2063 When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
2064 link and description parts of the link.
2066 @cindex following links
2067 @kindex C-c C-o
2068 @item C-c C-o
2069 Open link at point.  This will launch a web browser for URLs (using
2070 @command{browse-url-at-point}), run vm/mh-e/wanderlust/rmail/gnus/bbdb
2071 for the corresponding links, and execute the command in a shell link.
2072 When the cursor is on an internal link, this commands runs the
2073 corresponding search.  When the cursor is on a TAG list in a headline,
2074 it creates the corresponding TAGS view.  If the cursor is on a time
2075 stamp, it compiles the agenda for that date.  Furthermore, it will visit
2076 text and remote files in @samp{file:} links with Emacs and select a
2077 suitable application for local non-text files.  Classification of files
2078 is based on file extension only.  See option @code{org-file-apps}.  If
2079 you want to override the default application and visit the file with
2080 Emacs, use a @kbd{C-u} prefix.
2082 @kindex mouse-2
2083 @kindex mouse-1
2084 @item mouse-2
2085 @itemx mouse-1
2086 On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o}
2087 would.  Under Emacs 22, also @kbd{mouse-1} will follow a link.
2089 @kindex mouse-3
2090 @item mouse-3
2091 Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
2092 internal links to be displayed in another window@footnote{See the
2093 variable @code{org-display-internal-link-with-indirect-buffer}}.
2095 @cindex mark ring
2096 @kindex C-c %
2097 @item C-c %
2098 Push the current position onto the mark ring, to be able to return
2099 easily. Commands following an internal link do this automatically.
2101 @cindex links, returning to
2102 @kindex C-c &
2103 @item C-c &
2104 Jump back to a recorded position.  A position is recorded by the
2105 commands following internal links, and by @kbd{C-c %}.  Using this
2106 command several times in direct succession moves through a ring of
2107 previously recorded positions.
2108 @end table
2110 @node Link abbreviations, Search options, Handling links, Hyperlinks
2111 @section Link abbreviatons
2112 @cindex link abbreviations
2113 @cindex abbreviation, links
2115 Long URLs can be cumbersome to type, and often many similar links are
2116 needed in a document.  For this you can use link abbreviations.  An
2117 abbreviated link looks like this
2119 @example
2120 [[linkword::tag][description]]
2121 @end example
2123 @noindent
2124 where the tag is optional.  Such abbreviations are resolved according to
2125 the information in the variable @code{org-link-abbrev-alist} that
2126 relates the linkwords to replacement text.  Here is an example:
2128 @lisp
2129 @group
2130 (setq org-link-abbrev-alist
2131   '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
2132     ("google"   . "http://www.google.com/search?q=")
2133     ("ads"      . "http://adsabs.harvard.edu/cgi-bin/
2134                    nph-abs_connect?author=%s&db_key=AST")))
2135 @end group
2136 @end lisp
2138 If the replacement text contains the string @samp{%s}, it will be
2139 replaced with the tag.  Otherwise the tag will be appended to the string
2140 in order to create the link.  You may also specify a function that will
2141 be called with the tag as the only argument to create the link.
2143 With the above setting, you could link to a specific bug with
2144 @code{[[bugzilla::129]]}, search the web for OrgMode with
2145 @code{[[google::OrgMode]]} and find out what the Org-mode author is
2146 doing besides Emacs hacking with @code{[[ads::Dominik,C]]}.
2148 If you need special abbreviations just for a single Org-mode buffer, you
2149 can define them in the file with
2151 @example
2152 #+LINK: bugzilla  http://10.1.2.9/bugzilla/show_bug.cgi?id=
2153 #+LINK: google    http://www.google.com/search?q=%s
2154 @end example
2156 @noindent
2157 In-buffer completion @pxref{Completion} can be used after @samp{[} to
2158 complete link abbreviations.
2160 @node Search options, Custom searches, Link abbreviations, Hyperlinks
2161 @section Search options in file links
2162 @cindex search option in file links
2163 @cindex file links, searching
2165 File links can contain additional information to make Emacs jump to a
2166 particular location in the file when following a link.  This can be a
2167 line number or a search option after a double@footnote{For backward
2168 compatibility, line numbers can also follow a single colon.} colon. For
2169 example, when the command @kbd{C-c l} creates a link (@pxref{Handling
2170 links}) to a file, it encodes the words in the current line as a search
2171 string that can be used to find this line back later when following the
2172 link with @kbd{C-c C-o}. 
2174 Here is the syntax of the different ways to attach a search to a file
2175 link, together with an explanation:
2177 @example
2178 [[file:~/code/main.c::255]]
2179 [[file:~/xx.org::My Target]]
2180 [[file:~/xx.org::*My Target]]
2181 [[file:~/xx.org::/regexp/]]
2182 @end example
2184 @table @code
2185 @item 255
2186 Jump to line 255.
2187 @item My Target
2188 Search for a link target @samp{<<My Target>>}, or do a text search for
2189 @samp{my target}, similar to the search in internal links, see
2190 @ref{Internal links}.  In HTML export (@pxref{HTML export}), such a file
2191 link will become an HTML reference to the corresponding named anchor in
2192 the linked file.
2193 @item *My Target
2194 In an Org-mode file, restrict search to headlines.
2195 @item /regexp/
2196 Do a regular expression search for @code{regexp}.  This uses the Emacs
2197 command @code{occur} to list all matches in a separate window.  If the
2198 target file is in Org-mode, @code{org-occur} is used to create a
2199 sparse tree with the matches.
2200 @c If the target file is a directory,
2201 @c @code{grep} will be used to search all files in the directory.
2202 @end table
2204 As a degenerate case, a file link with an empty file name can be used
2205 to search the current file.  For example, @code{[[file:::find me]]} does
2206 a search for @samp{find me} in the current file, just as
2207 @samp{[[find me]]} would.
2209 @node Custom searches, Remember, Search options, Hyperlinks
2210 @section Custom Searches
2211 @cindex custom search strings
2212 @cindex search strings, custom
2214 The default mechanism for creating search strings and for doing the
2215 actual search related to a file link may not work correctly in all
2216 cases.  For example, BibTeX database files have many entries like
2217 @samp{year="1993"} which would not result in good search strings,
2218 because the only unique identification for a BibTeX entry is the
2219 citation key.
2221 If you come across such a problem, you can write custom functions to set
2222 the right search string for a particular file type, and to do the search
2223 for the string in the file.  Using @code{add-hook}, these functions need
2224 to be added to the hook variables
2225 @code{org-create-file-search-functions} and
2226 @code{org-execute-file-search-functions}.  See the docstring for these
2227 variables for more information.  Org-mode actually uses this mechanism
2228 for Bib@TeX{} database files, and you can use the corresponding code as
2229 an implementation example.  Search for @samp{BibTeX links} in the source
2230 file.
2233 @node Remember,  , Custom searches, Hyperlinks
2234 @section Remember
2235 @cindex @file{remember.el}
2237 Another way to create org entries with links to other files is through
2238 the @emph{Remember} package by John Wiegley.  @emph{Remember} lets you
2239 store quick notes with little interruption of your work flow.  See
2240 @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for more
2241 information.  The notes produced by @emph{Remember} can be stored in
2242 different ways, and Org-mode files are a good target.  Org-mode allows
2243 you to file away notes either to a default file, or directly to the correct
2244 location in your Org-mode outline tree.  The following customization
2245 will tell @emph{Remember} to use org files as target, and to create
2246 annotations compatible with Org-mode links.
2248 @example
2249 (setq org-directory "~/path/to/my/orgfiles/")
2250 (setq org-default-notes-file "~/.notes")
2251 (setq remember-annotation-functions '(org-remember-annotation))
2252 (setq remember-handler-functions '(org-remember-handler))
2253 (add-hook 'remember-mode-hook 'org-remember-apply-template)
2254 @end example
2256 @cindex templates, for remember
2257 In combination with Org-mode, you can use templates to generate
2258 different types of remember notes.  For example, if you would like to
2259 use one template to create general TODO entries, and another one for
2260 journal entries, you could use:
2262 @example
2263 (setq org-remember-templates
2264       '((?t "* TODO %?\n  %i\n  %a" "~/org/TODO.org")
2265         (?j "* %U %?\n\n  %i\n  %a" "~/org/JOURNAL.org")))
2266 @end example
2268 @noindent In these entries, the character specifies how to select the
2269 template, the first string specifies the template, and the (optional)
2270 second string specifies a default file (overruling
2271 @code{org-default-notes-file}) as a target for this note.
2273 When you call @kbd{M-x remember} to remember something, org will prompt
2274 for a key to select the template and then prepare the buffer like
2275 @example
2276 * TODO
2277   [[file:link to where you called remember]]
2278 @end example
2280 @noindent or
2282 @example
2283 * [2006-03-21 Tue 15:37]
2285   [[file:link to where you called remember]]
2286 @end example
2288 @noindent See the variable @code{org-remember-templates} for more details.
2290 When you are finished composing a note with remember, you have to press
2291 @kbd{C-c C-c} to file the note away.  The handler first prompts for a
2292 target file - if you press @key{RET}, the value of
2293 @code{org-default-notes-file} is used.  Then the command offers the
2294 headings tree of the selected file.  You can either immediately press
2295 @key{RET} to get the note appended to the file.  Or you can use vertical
2296 cursor motion (@key{up} and @key{down}) and visibility cycling
2297 (@key{TAB}) to find a better place.  Pressing @key{RET} or @key{left} or
2298 @key{right} leads to the following result.
2300 @multitable @columnfractions 0.2 0.1 0.7
2301 @item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted}
2302 @item buffer-start @tab @key{RET} @tab as level 2 heading at end of file
2303 @item on headline @tab @key{RET} @tab as sublevel of the heading at cursor
2304 @item             @tab @key{left}  @tab as same level, before current heading
2305 @item             @tab @key{right} @tab as same level, after current heading
2306 @item not on headline @tab @key{RET}
2307       @tab at cursor position, level taken from context.
2308            Or use prefix arg to specify level manually.
2309 @end multitable
2311 So a fast way to store the note is to press @kbd{C-c C-c @key{RET}
2312 @key{RET}} to append it to the default file.  Even shorter would be
2313 @kbd{C-u C-c C-c}, which does the same without even showing the tree.
2314 But with little extra effort, you can push it directly to the correct
2315 location.
2317 Before inserting the text into a tree, the function ensures that the
2318 text has a headline, i.e. a first line that starts with a @samp{*}.
2319 If not, a headline is constructed from the current date and some
2320 additional data.  If the variable @code{org-adapt-indentation} is
2321 non-nil, the entire text is also indented so that it starts in the
2322 same column as the headline (after the asterisks).
2325 @node TODO items, Timestamps, Hyperlinks, Top
2326 @chapter TODO items
2327 @cindex TODO items
2329 Org-mode does not maintain TODO lists as a separate document.  TODO
2330 items are an integral part of the notes file, because TODO items
2331 usually come up while taking notes!  With Org-mode, you simply mark
2332 any entry in a tree as being a TODO item.  In this way, the
2333 information is not duplicated, and the entire context from which the
2334 item emerged is always present when you check.
2336 Of course, this technique causes TODO items to be scattered throughout
2337 your file.  Org-mode provides methods to give you an overview over all
2338 things you have to do.
2340 @menu
2341 * TODO basics::                 Marking and displaying TODO entries
2342 * TODO extensions::             Workflow and assignments
2343 * Priorities::                  Some things are more important than others
2344 * Breaking down tasks::         Splitting a task into managable pieces
2345 * Checkboxes::                  Tick-off lists
2346 @end menu
2348 @node TODO basics, TODO extensions, TODO items, TODO items
2349 @section Basic TODO functionality
2351 Any headline can become a TODO item by starting it with the word TODO,
2352 for example:
2354 @example
2355 *** TODO Write letter to Sam Fortune
2356 @end example
2358 @noindent
2359 The most important commands to work with TODO entries are:
2361 @table @kbd
2362 @kindex C-c C-t
2363 @cindex cycling, of TODO states
2364 @item C-c C-t
2365 Rotate the TODO state of the current item between
2367 @example
2368 ,-> (unmarked) -> TODO -> DONE --.
2369 '--------------------------------'
2370 @end example
2372 The same rotation can also be done ``remotely'' from the timeline and
2373 agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).
2374 @kindex S-@key{right}
2375 @kindex S-@key{left}
2376 @item S-@key{right}
2377 @itemx S-@key{left}
2378 Select the following/preceding TODO state, similar to cycling.  Mostly
2379 useful if more than two TODO states are possible (@pxref{TODO extensions}).
2380 @kindex C-c C-v
2381 @cindex sparse tree, for TODO
2382 @item C-c C-v
2383 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}).  Folds
2384 the entire buffer, but shows all TODO items and the headings hierarchy
2385 above them.  With prefix arg, show also the DONE entries.  With
2386 numerical prefix N, show the tree for the Nth keyword in the variable
2387 @code{org-todo-keywords}.
2388 @kindex C-c a t
2389 @item C-c a t
2390 Show the global TODO list.  This collects the TODO items from all
2391 agenda files (@pxref{Agenda views}) into a single buffer.  The buffer is in
2392 @code{agenda-mode}, so there are commands to examine and manipulate
2393 the TODO entries directly from that buffer (@pxref{Agenda commands}).
2394 @xref{Global TODO list}, for more information.
2395 @c @item @code{org-agenda-include-all-todo}
2396 @c If you would like to have all your TODO items listed as part of your
2397 @c agenda, customize the variable @code{org-agenda-include-all-todo}.
2398 @end table
2401 @node TODO extensions, Priorities, TODO basics, TODO items
2402 @section Extended use of TODO keywords
2403 @cindex extended TODO keywords
2405 The default implementation of TODO entries is just two states: TODO and
2406 DONE.  You can, however, use the TODO feature for more complicated
2407 things by configuring the variables @code{org-todo-keywords} and
2408 @code{org-todo-interpretation}.  Using special setup, you can even use
2409 TODO keywords in different ways in different org files.
2411 Note that @i{tags} are another way to classify headlines in general and
2412 TODO items in particular (@pxref{Tags}).
2414 @menu
2415 * Workflow states::             From TODO to DONE in steps
2416 * TODO types::                  I do this, Fred the rest
2417 * Per file keywords::           Different files, different requirements
2418 @end menu
2420 @node Workflow states, TODO types, TODO extensions, TODO extensions
2421 @subsection TODO keywords as workflow states
2422 @cindex TODO workflow
2423 @cindex workflow states as TODO keywords
2425 You can use TODO keywords to indicate different states in the process
2426 of working on an item, for example:
2428 @lisp
2429 (setq org-todo-keywords '("TODO" "FEEDBACK" "VERIFY" "DONE")
2430       org-todo-interpretation 'sequence)
2431 @end lisp
2433 @cindex completion, of TODO keywords
2434 Changing these variables only becomes effective in a new Emacs session.
2435 With this setup, the command @kbd{C-c C-t} will cycle an entry from
2436 TODO to FEEDBACK, then to VERIFY, and finally to DONE.  You may also
2437 use a prefix argument to quickly select a specific state.  For example
2438 @kbd{C-3 C-c C-t} will change the state immediately to VERIFY.
2439 If you define many keywords, you can use in-buffer completion (see
2440 @ref{Completion}) to insert these words into the buffer.  Changing a todo
2441 state can be logged with a timestamp, see @ref{Tracking TODO state
2442 changes} for more information.
2444 @node TODO types, Per file keywords, Workflow states, TODO extensions
2445 @subsection TODO keywords as types
2446 @cindex TODO types
2447 @cindex names as TODO keywords
2448 @cindex types as TODO keywords
2450 The second possibility is to use TODO keywords to indicate different
2451 types of action items.  For example, you might want to indicate that
2452 items are for ``work'' or ``home''.  If you are into David Allen's
2453 @emph{Getting Things DONE}, you might want to use todo types
2454 @samp{NEXTACTION}, @samp{WAITING}, @samp{MAYBE}.  Or, when you work
2455 with several people on a single project, you might want to assign
2456 action items directly to persons, by using their names as TODO
2457 keywords.  This would be set up like this:
2459 @lisp
2460 (setq org-todo-keywords '("Fred" "Sara" "Lucy" "Mike" "DONE")
2461       org-todo-interpretation 'type)
2462 @end lisp
2464 In this case, different keywords do not indicate a sequence, but
2465 rather different types.  So it is normally not useful to change from
2466 one type to another.  Therefore, in this case the behavior of the
2467 command @kbd{C-c C-t} is changed slightly@footnote{This is also true
2468 for the @kbd{t} command in the timeline and agenda buffers.}.  When
2469 used several times in succession, it will still cycle through all
2470 names.  But when you return to the item after some time and execute
2471 @kbd{C-c C-t} again, it will switch from each name directly to DONE.
2472 Use prefix arguments or completion to quickly select a specific name.
2473 You can also review the items of a specific TODO type in a sparse tree
2474 by using a numeric prefix to @kbd{C-c C-v}.  For example, to see all
2475 things Lucy has to do, you would use @kbd{C-3 C-c C-v}.  To collect
2476 Lucy's items from all agenda files into a single buffer, you
2477 would use the prefix arg as well when creating the global todo list:
2478 @kbd{C-3 C-c t}.
2480 @node Per file keywords,  , TODO types, TODO extensions
2481 @subsection Setting up TODO keywords for individual files
2482 @cindex keyword options
2483 @cindex per file keywords
2485 It can be very useful to use different aspects of the TODO mechanism
2486 in different files, which is not possible with the global settings
2487 described above.  For file-local settings, you need to add special
2488 lines to the file which set the keywords and interpretation for that
2489 file only.  For example, to set one of the two examples discussed
2490 above, you need one of the following lines, starting in column zero
2491 anywhere in the file:
2493 @example
2494 #+SEQ_TODO: TODO FEEDBACK VERIFY DONE
2495 #+TYP_TODO: Fred Sara Lucy Mike DONE
2496 @end example
2498 @cindex Completion, of option keywords
2499 @kindex M-@key{TAB}
2500 @noindent To make sure you are using the correct keyword, type
2501 @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
2503 @cindex DONE, final TODO keyword
2504 Remember that the last keyword must always mean that the item is DONE
2505 (although you may use a different word).  Also note that in each file,
2506 only one of the two aspects of TODO keywords can be used.  After
2507 changing one of these lines, use @kbd{C-c C-c} with the cursor still
2508 in the line to make the changes known to Org-mode@footnote{Org-mode
2509 parses these lines only when Org-mode is activated after visiting a
2510 file.  @kbd{C-c C-c} with the cursor in a line starting with @samp{#+}
2511 is simply restarting Org-mode for the current buffer.}.
2513 If you want to use very many keywords, for example when working with a
2514 large group of people, you may split the names over several lines:
2516 @example
2517 #+TYP_TODO: Fred Sara Lucy Mike
2518 #+TYP_TODO: Luis George Jules Jessica
2519 #+TYP_TODO: Kim Arnold Peter
2520 #+TYP_TODO: DONE
2521 @end example
2523 @node Priorities, Breaking down tasks, TODO extensions, TODO items
2524 @section Priorities
2525 @cindex priorities
2527 If you use Org-mode extensively to organize your work, you may end up
2528 with a number of TODO entries so large that you'd like to prioritize
2529 them.  This can be done by placing a @emph{priority cookie} into the
2530 headline, like this
2532 @example
2533 *** TODO [#A] Write letter to Sam Fortune
2534 @end example
2536 @noindent
2537 With its standard setup, Org-mode supports priorities @samp{A},
2538 @samp{B}, and @samp{C}.  @samp{A} is the highest priority.  An entry
2539 without a cookie is treated as priority @samp{B}.  Priorities make a
2540 difference only in the agenda (@pxref{Weekly/Daily agenda}).
2542 @table @kbd
2543 @kindex @kbd{C-c ,}
2544 @item @kbd{C-c ,}
2545 Set the priority of the current headline.  The command prompts for a
2546 priority character @samp{A}, @samp{B} or @samp{C}.  When you press
2547 @key{SPC} instead, the priority cookie is removed from the headline.
2548 The priorities can also be changed ``remotely'' from the timeline and
2549 agenda buffer with the @kbd{,} command (@pxref{Agenda commands}).
2551 @kindex S-@key{up}
2552 @kindex S-@key{down}
2553 @item S-@key{up}
2554 @itemx S-@key{down}
2555 Increase/decrease priority of current headline.  Note that these keys
2556 are also used to modify time stamps (@pxref{Creating timestamps}).
2557 Furthermore, these keys are also used by CUA-mode (@pxref{Conflicts}).
2558 @end table
2560 @node Breaking down tasks, Checkboxes, Priorities, TODO items
2561 @section Breaking tasks down into subtasks
2562 @cindex tasks, breaking down
2564 It is often advisable to break down large tasks into smaller, managable
2565 subtasks.  You can do this by creating an outline tree below a TODO
2566 item, with detailed subtasks on the tree@footnote{To keep subtasks out
2567 of the global TODO list, see the
2568 @code{org-agenda-todo-list-sublevels}.}.  Another possibility is the use
2569 of checkboxes to identify (a hierarchy of) a large number of subtasks
2570 (@pxref{Checkboxes}).
2573 @node Checkboxes,  , Breaking down tasks, TODO items
2574 @section Checkboxes
2575 @cindex checkboxes
2577 Every item in a plain list (@pxref{Plain lists}) can be made a checkbox
2578 by starting it with the string @samp{[ ]}.  This feature is similar to
2579 TODO items (@pxref{TODO items}), but more lightweight.  Checkboxes are
2580 not included into the global TODO list, so they are often great to split
2581 a task into a number of simple steps.  Or you can use them in a shopping
2582 list.  To toggle a checkbox, use @kbd{C-c C-c}, or try Piotr Zielinski's
2583 @file{org-mouse.el}.  Here is an example of a checkbox list.
2585 @example
2586 * TODO Organize party [3/6]
2587   - call people [1/3]
2588     - [ ] Peter
2589     - [X] Sarah
2590     - [ ] Sam
2591   - [X] order food
2592   - [ ] think about what music to play
2593   - [X] talk to the neighbors
2594 @end example
2596 @cindex statistics, for checkboxes
2597 @cindex checkbox statistics
2598 The @samp{[3/6]} and @samp{[1/3]} in the first and second line are
2599 cookies indicating how many checkboxes are present in this entry, and
2600 how many of them have been checked off.  This can give you an idea on
2601 how many checkboxes remain, even without opening a folded entry.  The
2602 cookies can be placed into a headline or into (the first line of) a
2603 plain list item. Each cookie covers all checkboxes structurally below
2604 that headline/item.  You have to insert the cookie yourself by typing
2605 either @samp{[/]} or @samp{[%]}.  In the first case you get an @samp{n
2606 out of m} result, in the second case you get information about the
2607 percentage of checkboxes checked (in the above example, this would be
2608 @samp{[50%]} and @samp{[33%], respectively}).
2610 @noindent The following commands work with checkboxes:
2612 @table @kbd
2613 @kindex C-c C-c
2614 @item C-c C-c
2615 Toggle checkbox at point.
2616 @kindex C-c C-x C-b
2617 @item C-c C-x C-b
2618 Toggle checkbox at point.
2619 @itemize @minus
2620 @item
2621 If there is an active region, toggle the first checkbox in the region
2622 and set all remaining boxes to the same status as the first.  If you
2623 want to toggle all boxes in the region independently, use a prefix
2624 argument.
2625 @item
2626 If the cursor is in a headline, toggle checkboxes in the region between
2627 this headline and the next (so @emph{not} the entire subtree).
2628 @item
2629 If there is no active region, just toggle the checkbox at point.
2630 @end itemize
2631 @kindex M-S-@key{RET}
2632 @item M-S-@key{RET}
2633 Insert a new item with a checkbox.
2634 This works only if the cursor is already in a plain list item
2635 (@pxref{Plain lists}).
2636 @kindex C-c #
2637 @item C-c #
2638 Update the checkbox statistics in the current outline entry.  When
2639 called with a @kbd{C-u} prefix, update the entire file.  Checkbox
2640 statistic cookies are updated automatically if you toggle checkboxes
2641 with @kbd{C-c C-c} and make new ones with @kbd{M-S-@key{RET}}.  If you
2642 delete boxes or add/change them by hand, use this command to get things
2643 back into synch.  Or simply toggle any checkbox twice with @kbd{C-c C-c}.
2644 @end table
2646 @node Timestamps, Tags, TODO items, Top
2647 @chapter Timestamps
2648 @cindex time stamps
2649 @cindex date stamps
2651 Items can be labeled with timestamps to make them useful for project
2652 planning.
2654 @menu
2655 * Time stamps::                 Assigning a time to a tree entry
2656 * Creating timestamps::         Commands which insert timestamps
2657 * Custom time format::          If you cannot work with the ISO format
2658 * Repeating items::             Deadlines that come back again and again
2659 * Progress logging::            Documenting when what work was done.
2660 @end menu
2663 @node Time stamps, Creating timestamps, Timestamps, Timestamps
2664 @section Time stamps, deadlines and scheduling
2665 @cindex time stamps
2666 @cindex ranges, time
2667 @cindex date stamps
2668 @cindex deadlines
2669 @cindex scheduling
2671 A time stamp is a specification of a date (possibly with time) in a
2672 special format, either @samp{<2003-09-16 Tue>} or @samp{<2003-09-16 Tue
2673 09:39>}@footnote{This is the standard ISO date/time format.  If you
2674 cannot get used to these, see @ref{Custom time format}}.  A time stamp
2675 can appear anywhere in the headline or body of an org-tree entry.  Its
2676 presence allows entries to be shown on specific dates in the agenda
2677 (@pxref{Weekly/Daily agenda}).  We distinguish:
2679 @table @var
2680 @item Plain time stamp
2681 @cindex timestamp
2682 A simple time stamp just assigns a date/time to an item.  This is just
2683 like writing down an appointment in a paper agenda, or like writing down
2684 an event in a diary, when you want to take note of when something
2685 happened.  In the timeline and agenda displays, the headline of an entry
2686 associated with a plain time stamp will be shown exactly on that date.
2688 @example
2689 * Meet Peter at the movies <2006-11-01 Wed 19:15>
2690 @end example
2692 @item Inactive time stamp
2693 @cindex timestamp, inactive
2694 @cindex inactive timestamp
2695 Just like a plain time stamp, but with square brackets instead of
2696 angular ones.  These time stamps are inactive in the sense that they do
2697 @emph{not} trigger an entry to show up in the agenda.
2699 @example
2700 * Gillian comes late for the fifth time [2006-11-01 Wed]
2701 @end example
2703 @item Time stamp range
2704 @cindex timerange
2705 Two time stamps connected by @samp{--} denote a time range.  The
2706 headline will be shown on the first and last day of the range, and on
2707 any dates that are displayed and fall in the range.  Here is an
2708 example:
2710 @example
2711 ** Meeting in Amsterdam
2712    <2004-08-23 Mon>--<2004-08-26 Thu>
2713 @end example
2715 @item Time stamp with SCHEDULED keyword
2716 @cindex SCHEDULED keyword
2717 If a time stamp is preceded by the word @samp{SCHEDULED:}, it means you
2718 are planning to start working on that task on the given date. So this is
2719 not about recording an event, but about planning your work.  The
2720 headline will be listed under the given date@footnote{It will still be
2721 listed on that date after it has been marked DONE.  If you don't like
2722 this, set the variable @code{org-agenda-skip-scheduled-if-done}.}.  In
2723 addition, a reminder that the scheduled date has passed will be present
2724 in the compilation for @emph{today}, until the entry is marked DONE.
2725 I.e., the task will automatically be forwarded until completed.
2727 @example
2728 *** TODO Call Trillian for a date on New Years Eve.
2729     SCHEDULED: <2004-12-25 Sat>
2730 @end example
2732 @item Time stamp with DEADLINE keyword
2733 @cindex DEADLINE keyword
2734 If a time stamp is preceded by the word @samp{DEADLINE:}, the task
2735 (most likely a TODO item) is supposed to be finished on that date, and
2736 it will be listed then.  In addition, the compilation for @emph{today}
2737 will carry a warning about the approaching or missed deadline,
2738 starting @code{org-deadline-warning-days} before the due date, and
2739 continuing until the entry is marked DONE.  An example:
2741 @example
2742 *** TODO write article about the Earth for the Guide
2743     The editor in charge is [[bbdb:Ford Prefect]]
2744     DEADLINE: <2004-02-29 Sun>
2745 @end example
2746 @item Time stamp with CLOSED keyword
2747 @cindex CLOSED keyword
2748 When @code{org-log-done} is non-nil, Org-mode will automatically insert
2749 a special time stamp each time a TODO entry is marked done
2750 (@pxref{Progress logging}).  This time stamp is enclosed in square
2751 brackets instead of angular brackets.
2753 @item Time range with CLOCK keyword
2754 @cindex CLOCK keyword
2755 When using the clock to time the work that is being done on specific
2756 items, time ranges preceded by the CLOCK keyword are inserted
2757 automatically into the file.  The time stamps are enclosed in square
2758 brackets instead of angular brackets.  @xref{Clocking work time}.
2759 @end table
2761 @node Creating timestamps, Custom time format, Time stamps, Timestamps
2762 @section Creating timestamps
2763 @cindex creating timestamps
2764 @cindex timestamps, creating
2766 For Org-mode to recognize time stamps, they need to be in the specific
2767 format.  All commands listed below produce time stamps in the correct
2768 format.
2770 @table @kbd
2771 @kindex C-c .
2772 @item C-c .
2773 Prompt for a date and insert a corresponding time stamp.  When the
2774 cursor is at a previously used time stamp, it is updated to NOW.  When
2775 this command is used twice in succession, a time range is inserted.
2777 @kindex C-u C-c .
2778 @item C-u C-c .
2779 Like @kbd{C-c .}, but use the alternative format which contains date
2780 and time.  The default time can be rounded to multiples of 5 minutes,
2781 see the option @code{org-time-stamp-rounding-minutes}.
2783 @kindex C-c !
2784 @item C-c !
2785 Like @kbd{C-c .}, but insert an inactive time stamp not triggering the
2786 agenda.
2788 @kindex C-c <
2789 @item C-c <
2790 Insert a time stamp corresponding to the cursor date in the Calendar.
2792 @kindex C-c >
2793 @item C-c >
2794 Access the Emacs calendar for the current date.  If there is a
2795 timestamp in the current line, goto the corresponding date
2796 instead.
2798 @kindex C-c C-o
2799 @item C-c C-o
2800 Access the agenda for the date given by the time stamp or -range at
2801 point (@pxref{Weekly/Daily agenda}).
2803 @kindex C-c C-d
2804 @item C-c C-d
2805 Insert @samp{DEADLINE} keyword along with a stamp.  The insertion will
2806 happen in the line directly following the headline.  
2807 @c FIXME Any CLOSED timestamp will be removed.????????
2809 @kindex C-c C-w
2810 @cindex sparse tree, for deadlines
2811 @item C-c C-w
2812 Create a sparse tree with all deadlines that are either past-due, or
2813 which will become due within @code{org-deadline-warning-days}.
2814 With @kbd{C-u} prefix, show all deadlines in the file.  With a numeric
2815 prefix, check that many days.  For example, @kbd{C-1 C-c C-w} shows
2816 all deadlines due tomorrow.
2818 @kindex C-c C-s
2819 @item C-c C-s
2820 Insert @samp{SCHEDULED} keyword along with a stamp.  The insertion will
2821 happen in the line directly following the headline.  Any CLOSED
2822 timestamp will be removed.
2824 @kindex S-@key{left}
2825 @kindex S-@key{right}
2826 @item S-@key{left}
2827 @itemx S-@key{right}
2828 Change date at cursor by one day.  These key bindings conflict with
2829 CUA-mode (@pxref{Conflicts}).
2831 @kindex S-@key{up}
2832 @kindex S-@key{down}
2833 @item S-@key{up}
2834 @itemx S-@key{down}
2835 Change the item under the cursor in a timestamp.  The cursor can be on a
2836 year, month, day, hour or minute.  Note that if the cursor is in a
2837 headline and not at a time stamp, these same keys modify the priority of
2838 an item.  (@pxref{Priorities}). The key bindings also conflict with
2839 CUA-mode (@pxref{Conflicts}).
2842 @kindex C-c C-y
2843 @cindex evaluate time range
2844 @item C-c C-y
2845 Evaluate a time range by computing the difference between start and
2846 end.  With prefix arg, insert result after the time range (in a table:
2847 into the following column).
2848 @end table
2851 @menu
2852 * The date/time prompt::        How org-mode helps you entering date and time
2853 @end menu
2855 @node The date/time prompt,  , Creating timestamps, Creating timestamps
2856 @subsection The date/time prompt
2857 @cindex date, reading in minibuffer
2858 @cindex time, reading in minibuffer
2860 When Org-mode prompts for a date/time, the prompt suggests to enter an
2861 ISO date.  But it will in fact accept any string containing some date
2862 and/or time information.  You can, for example, use @kbd{C-y} to paste a
2863 (possibly multi-line) string copied from an email message.  Org-mode
2864 will find whatever information is in there and will replace anything not
2865 specified with the current date and time.  For example:
2867 @example
2868   3-2-5         --> 2003-02-05
2869   feb 15        --> currentyear-02-15
2870   sep 12 9      --> 2009-09-12
2871   12:45         --> today 12:45
2872   22 sept 0:34  --> currentyear-09-22 0:34
2873   12            --> currentyear-currentmonth-12
2874   Fri           --> nearest Friday (today or later)
2875   +4            --> 4 days from now (if +N is the only thing given)
2876 @end example
2878 The function understands English month and weekday abbreviations.  If
2879 you want to use unabbreviated names and/or other languages, configure
2880 the variables @code{parse-time-months} and @code{parse-time-weekdays}.
2882 @cindex calendar, for selecting date
2883 Parallel to the minibuffer prompt, a calendar is popped up@footnote{If
2884 you don't need/want the calendar, configure the variable
2885 @code{org-popup-calendar-for-date-prompt}.}.  You can control the
2886 calendar fully from the minibuffer:
2888 @table @kbd
2889 @kindex <
2890 @item <
2891 Scroll calendar backwards by one month.
2892 @kindex >
2893 @item >
2894 Scroll calendar forwards by one month.
2895 @kindex mouse-1
2896 @item mouse-1
2897 Select date by clicking on it.
2898 @kindex S-@key{right}
2899 @item S-@key{right}
2900 One day forward.
2901 @kindex S-@key{left}
2902 @item S-@key{left}
2903 One day back.
2904 @kindex S-@key{down}
2905 @item S-@key{down}
2906 One week forward.
2907 @kindex S-@key{up}
2908 @item S-@key{up}
2909 One week back.
2910 @kindex M-S-@key{right}
2911 @item M-S-@key{right}
2912 One month forward.
2913 @kindex M-S-@key{left}
2914 @item M-S-@key{left}
2915 One month back.
2916 @kindex @key{RET}
2917 @item @key{RET}
2918 Choose date in calendar (only if nothing was typed into minibuffer).
2919 @end table
2921 @node Custom time format, Repeating items, Creating timestamps, Timestamps
2922 @section Custom time format
2923 @cindex custom date/time format
2924 @cindex time format, custom
2925 @cindex date format, custom
2927 Org-mode uses the standard ISO notation for dates and times as it is
2928 defined in ISO 8601.  If you cannot get used to this and require another
2929 representation of date and time to keep you happy, you can get it by
2930 customizing the variables @code{org-display-custom-times} and
2931 @code{org-time-stamp-custom-formats}.
2933 @table @kbd
2934 @kindex C-c C-x C-t
2935 @item C-c C-x C-t
2936 Toggle the display of custom formats for dates and times.
2937 @end table
2939 @noindent
2940 Org-mode needs the default format for scanning, so the custom date/time
2941 format does not @emph{replace} the default format - instead it is put
2942 @emph{over} the default format using text properties.  This has the
2943 following consequences:
2944 @itemize @bullet
2945 @item 
2946 You cannot place the cursor onto a time stamp anymore, only before or
2947 after.
2948 @item
2949 The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust
2950 each component of a time stamp.  If the cursor is at the beginning of
2951 the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day,
2952 just like @kbd{S-@key{left}/@key{right}}.  At the end of the stamp, the
2953 time will be changed by one minute.
2954 @item
2955 When you delete a time stamp character-by-character, it will only
2956 disappear from the buffer after @emph{all} (invisible) characters
2957 belonging to the ISO timestamp have been removed.
2958 @item
2959 If the custom time stamp format is longer than the default and you are
2960 using dates in tables, table alignment will be messed up.  If the custom
2961 format is shorter, things do work as expected.
2962 @end itemize
2964 @node Repeating items, Progress logging, Custom time format, Timestamps
2965 @section Repeating items
2966 @cindex TODO items, repeating
2967 @cindex Deadlines, repeating
2968 @cindex Scheduling, repeating
2970 Org-mode integrates with the Emacs calendar and diary to display cyclic
2971 appointments, anniversaries and other special entries in the agenda
2972 (@pxref{Weekly/Daily agenda}).  However, it can be useful to have
2973 certain deadlines and scheduling items to auto-repeat.  The advantage of
2974 a deadline or scheduled item is that the they produce warnings ahead of
2975 time and automatically forward themselves in the agenda until they are
2976 done.  The abstract difference is therefore between cyclic
2977 @i{appointments} and cyclic @i{action items}.  For appointments you
2978 should use the diary, for actions you can uses an org-mode deadline or
2979 scheduling time stamp together with a REPEAT cookie.  For example:
2981 @example
2982 * TODO Replace batteries in smoke detector REPEAT(+18m)
2983   SCHEDULED: <2007-01-01 Mon>
2985 * TODO Get dentist appointment REPEAT(+6m)
2986   SCHEDULED: <2006-12-19 Tue>
2988 * TODO Tax report to IRS REPEAT(+1y)
2989   DEADLINE: <2007-04-01 Sun>
2990 @end example
2992 Each time you try to mark one of these entries DONE using @kbd{C-c C-t},
2993 they will automatically switch back to the state TODO, and the
2994 deadline/scheduling will be shifted accordingly.  The time units
2995 recognized by org-mode are year (y), month (m), week (w), and day (d).
2996 Org-mode will also prompt you for a note and record the fact that you
2997 have closed this item in a note under the headline.
2999 One unusual property of these repeating items is that only one instance
3000 of each exist at any given time.  So if you look back or ahead in the
3001 agenda, you will not find past and future instances, only the current
3002 one will show up.  Use a cyclic diary entry if you need all past and
3003 future instances to be visible in the agenda.
3005 @node Progress logging,  , Repeating items, Timestamps
3006 @section Progress Logging
3007 @cindex progress logging
3008 @cindex logging, of progress
3010 Org-mode can automatically record a time stamp when you mark a TODO item
3011 as DONE, or even each time when you change the state of a TODO item.
3012 You can also measure precisely the time you spent on specific items in a
3013 project by starting and stopping a clock when you start and stop working
3014 on an aspect of a project.
3016 @menu
3017 * Closing items::               When was this entry marked DONE?
3018 * Tracking TODO state changes::  When did the status change?
3019 * Clocking work time::          When exactly did you work on this item?
3020 @end menu
3022 @node Closing items, Tracking TODO state changes, Progress logging, Progress logging
3023 @subsection Closing items
3025 If you want to keep track of @emph{when} a certain TODO item was
3026 finished, turn on logging with@footnote{The corresponding in-buffer
3027 setting is: @code{#+STARTUP: logdone}}
3029 @lisp
3030 (setq org-log-done t)
3031 @end lisp
3033 @noindent
3034 Then each time you turn a TODO entry into DONE using either @kbd{C-c
3035 C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line
3036 @samp{CLOSED: [timestamp]} will be inserted just after the headline.  If
3037 you turn the entry back into a TODO item through further state cycling,
3038 that line will be removed again.  In the timeline (@pxref{Timeline}) and
3039 in the agenda (@pxref{Weekly/Daily agenda}), you can then use the
3040 @kbd{l} key to display the TODO items closed on each day, giving you an
3041 overview of what has been done on a day.  If you want to record a note
3042 along with the timestamp, use@footnote{The corresponding in-buffer
3043 setting is: @code{#+STARTUP: lognotedone}}
3045 @lisp
3046 (setq org-log-done '(done))
3047 @end lisp
3049 @node Tracking TODO state changes, Clocking work time, Closing items, Progress logging
3050 @subsection Tracking TODO state changes
3052 When TODO keywords are used as workflow states (@pxref{Workflow
3053 states}), you might want to keep track of when a state change occurred,
3054 and you may even want to attach notes to that state change.  With the
3055 setting
3057 @lisp
3058 (setq org-log-done '(state))
3059 @end lisp
3061 @noindent
3062 each state change will prompt you for a note that will be attached to
3063 the current headline.  Very likely you do not want this verbose tracking
3064 all the time, so it is probably better to configure this behavior with
3065 in-buffer options.  For example, if you are tracking purchases, put
3066 these into a separate file that starts with:
3068 @example
3069 #+SEQ_TODO: TODO ORDERED INVOICE PAYED RECEIVED SENT
3070 #+STARTUP: lognotestate
3071 @end example
3073 @node Clocking work time,  , Tracking TODO state changes, Progress logging
3074 @subsection Clocking work time
3076 Org-mode allows you to clock the time you spent on specific tasks in a
3077 project.  When you start working on an item, you can start the clock.
3078 When you stop working on that task, or when you mark the task done, the
3079 clock is stopped and the corresponding time interval is recorded.  It
3080 also computes the total time spent on each subtree of a project.
3082 @table @kbd
3083 @kindex C-c C-x C-i
3084 @item C-c C-x C-i
3085 Start the clock on the current item (clock-in).  This inserts the CLOCK
3086 keyword together with a timestamp.
3087 @kindex C-c C-x C-o
3088 @item C-c C-x C-o
3089 Stop the clock (clock-out).  The inserts another timestamp at the same
3090 location where the clock was last started.  It also directly computes
3091 the resulting time in inserts it after the time range as @samp{=>
3092 HH:MM}.  See the variable @code{org-log-done} for the possibility to
3093 record an additional note together with the clock-out time
3094 stamp@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
3095 lognoteclock-out}}.
3096 @kindex C-c C-y
3097 @item C-c C-y
3098 Recompute the time interval after changing one of the time stamps.  This
3099 is only necessary if you edit the time stamps directly.  If you change
3100 them with @kbd{S-@key{cursor}} keys, the update is automatic.
3101 @kindex C-c C-t
3102 @item C-c C-t
3103 Changing the TODO state of an item to DONE automatically stops the clock
3104 if it is running in this same item.
3105 @kindex C-c C-x C-x
3106 @item C-c C-x C-x
3107 Cancel the current clock.  This is useful if a clock was started by
3108 mistake, or if you ended up working on something else.
3109 @kindex C-c C-x C-d
3110 @item C-c C-x C-d
3111 Display time summaries for each subtree in the current buffer.  This
3112 puts overlays at the end of each headline, showing the total time
3113 recorded under that heading, including the time of any subheadings. You
3114 can use visibility cycling to study the tree, but the overlays disappear
3115 when you change the buffer (see variable
3116 @code{org-remove-highlights-with-change}) or press @kbd{C-c C-c}.
3117 @kindex C-c C-x C-r
3118 @item C-c C-x C-r
3119 Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock
3120 report as an org-mode table into the current file.
3121 @example
3122 #+BEGIN: clocktable :maxlevel 2 :emphasize nil
3124 #+END: clocktable
3125 @end example
3126 @noindent
3127 If such a block already exists, its content is replaced by the new
3128 table.  The @samp{BEGIN} line can specify options:
3129 @example
3130 :maxlevels   @r{Maximum level depth to which times are listed in the table.}
3131 :emphasize   @r{When @code{t}, emphasize level one and level two items}
3132 :block       @r{The time block to consider.  This block is specified relative}
3133              @r{to the current time and may be any of these keywords:}
3134              @r{@code{today}, @code{yesterday}, @code{thisweek}, @code{lastweek},}
3135              @r{@code{thismonth}, @code{lastmonth}, @code{thisyear}, or @code{lastyear}}.
3136 :tstart      @r{A time string specifying when to start considering times}
3137 :tend        @r{A time string specifying when to stop considering times}
3138 @end example
3139 So to get a clock summary for the current day, you could write
3140 @example
3141 #+BEGIN: clocktable :maxlevel 2 :block today
3143 #+END: clocktable
3144 @end example
3145 and to use a specific time range you could write@footnote{Note that all
3146 parameters must be specified in a single line - the line is broken here
3147 only to fit it onto the manual.}
3148 @example
3149 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>" 
3150                     :tend "<2006-08-10 Thu 12:00>"
3152 #+END: clocktable
3153 @end example
3154 @kindex C-u C-c C-x C-u
3155 @item C-u C-c C-x C-u
3156 Update all dynamic blocks (@pxref{Dynamic blocks}).  This is useful if
3157 you have several clocktable blocks in a buffer.
3158 @end table
3160 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
3161 the agenda (@pxref{Weekly/Daily agenda}) to show which tasks have been
3162 worked on or closed during a day.
3164 @node Tags, Agenda views, Timestamps, Top
3165 @chapter Tags
3166 @cindex tags
3167 @cindex headline tagging
3168 @cindex matching, tags
3169 @cindex sparse tree, tag based
3171 If you wish to implement a system of labels and contexts for
3172 cross-correlating information, an excellent way is to assign @i{tags} to
3173 headlines.  Org-mode has extensive support for using tags.
3175 Every headline can contain a list of tags, at the end of the headline.
3176 Tags are normal words containing letters, numbers, @samp{_}, and
3177 @samp{@@}.  Tags must be preceded and followed by a single colon; like
3178 @samp{:WORK:}.  Several tags can be specified like @samp{:WORK:URGENT:}.
3180 @menu
3181 * Tag inheritance::             Tags use the tree structure of the outline
3182 * Setting tags::                How to assign tags to a headline
3183 * Tag searches::                Searching for combinations of tags
3184 @end menu
3186 @node Tag inheritance, Setting tags, Tags, Tags
3187 @section Tag inheritance
3188 @cindex inheritance, of tags
3189 @cindex sublevels, inclusion into tags match
3191 @i{Tags} make use of the hierarchical structure of outline trees.  If a
3192 heading has a certain tag, all subheadings will inherit the tag as
3193 well.  For example, in the list
3195 @example
3196 * Meeting with the French group      :WORK:
3197 ** Summary by Frank                  :BOSS:NOTES:
3198 *** TODO Prepare slides for him      :ACTION:
3199 @end example
3201 @noindent
3202 the final heading will have the tags @samp{:WORK:}, @samp{:BOSS:},
3203 @samp{:NOTES:}, and @samp{:ACTION:}.  When executing tag searches and
3204 Org-mode finds that a certain headline matches the search criterion, it
3205 will not check any sublevel headline, assuming that these likely also
3206 match, and that the list of matches can become very long.  This may
3207 not be what you want, however, and you can influence inheritance and
3208 searching using the variables @code{org-use-tag-inheritance} and
3209 @code{org-tags-match-list-sublevels}.
3211 @node Setting tags, Tag searches, Tag inheritance, Tags
3212 @section Setting tags
3213 @cindex setting tags
3214 @cindex tags, setting
3216 @kindex M-@key{TAB}
3217 Tags can simply be typed into the buffer at the end of a headline.
3218 After a colon, @kbd{M-@key{TAB}} offers completion on tags.  There is
3219 also a special command for inserting tags:
3221 @table @kbd
3222 @kindex C-c C-c
3223 @item C-c C-c
3224 @cindex completion, of tags
3225 Enter new tags for the current headline.  Org-mode will either offer
3226 completion or a special single-key interface for setting tags, see
3227 below.  After pressing @key{RET}, the tags will be inserted and aligned
3228 to @code{org-tags-column}.  When called with a @kbd{C-u} prefix, all
3229 tags in the current buffer will be aligned to that column, just to make
3230 things look nice.  TAGS are automatically realigned after promotion,
3231 demotion, and TODO state changes (@pxref{TODO basics}).
3232 @end table
3234 Org will support tag insertion based on a @emph{list of tags}.  By
3235 default this list is constructed dynamically, containing all tags
3236 currently used in the buffer.  You may also globally specify a hard list
3237 of tags with the variable @code{org-tag-alist}.  Finally you can set
3238 the default tags for a given file with lines like
3240 @example
3241 #+TAGS: @@WORK @@HOME @@TENNISCLUB
3242 #+TAGS: Laptop Car PC Sailboat
3243 @end example
3245 If you have globally defined your preferred set of tags using the
3246 variable @code{org-tag-alist}, but would like to use a dynamic tag list
3247 in a specific file: Just add an empty TAGS option line to that file:
3249 @example
3250 #+TAGS:
3251 @end example
3253 The default support method for entering tags is minibuffer completion.
3254 However, Org-mode also implements a much better method: @emph{fast tag
3255 selection}.  This method allows to select and deselect tags with a
3256 single key per tag.  To function efficiently, you should assign unique
3257 keys to most tags.  This can be done globally with
3259 @lisp
3260 (setq org-tag-alist '(("@@WORK" . ?w) ("@@HOME" . ?h) ("Laptop" . ?l)))
3261 @end lisp
3263 @noindent or on a per-file basis with
3265 @example
3266 #+TAGS: @@WORK(w)  @@HOME(h)  @@TENNISCLUB(t)  Laptop(l)  PC(p)
3267 @end example
3269 @noindent
3270 You can also group together tags that are mutually exclusive.  With
3271 curly braces@footnote{In @code{org-mode-alist} use
3272 @code{'(:startgroup)} and @code{'(:endgroup)}, respectively.  Several
3273 groups are allowed.}
3275 @example
3276 #+TAGS: @{ @@WORK(w)  @@HOME(h)  @@TENNISCLUB(t) @}  Laptop(l)  PC(p)
3277 @end example
3279 @noindent you indicate that at most one of @samp{@@WORK}, @samp{@@HOME},
3280 and @samp{@@TENNISCLUB} should be selected.
3282 @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
3283 these lines to activate any changes.
3285 If at least one tag has a selection key, pressing @kbd{C-c C-c} will
3286 automatically present you with a special interface, listing inherited
3287 tags, the tags of the current headline, and a list of all legal tags
3288 with corresponding keys@footnote{Keys will automatically be assigned to
3289 tags which have no configured keys.}.  In this interface, you can use
3290 the following keys:
3292 @table @kbd
3293 @item a-z...
3294 Pressing keys assigned to tags will add or remove them from the list of
3295 tags in the current line.  Selecting a tag in a group of mutually
3296 exclusive tags will turn off any other tags from that group.
3297 @kindex @key{TAB}
3298 @item @key{TAB}
3299 Enter a tag in the minibuffer, even if the tag is not in the predefined
3300 list.  You will be able to complete on all tags present in the buffer.
3301 @kindex @key{SPC}
3302 @item @key{SPC}
3303 Clear all tags for this line.
3304 @kindex @key{RET}
3305 @item @key{RET}
3306 Accept the modified set.
3307 @item C-g
3308 Abort without installing changes.
3309 @item q
3310 If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
3311 @item !
3312 Turn off groups of mutually exclusive tags.  Use this to (as an
3313 exception) assign several tags from such a group.
3314 @item C-c
3315 Toggle auto-exit after the next change (see below).
3316 @end table
3318 @noindent
3319 This method lets you assign tags to a headline with very few keys.  With
3320 the above setup, you could clear the current tags and set @samp{@@HOME},
3321 @samp{Laptop} and @samp{PC} tags with just the following keys: @kbd{C-c
3322 C-c @key{SPC} h l p @key{RET}}.  Switching from @samp{@@HOME} to
3323 @samp{@@WORK} would be done with @kbd{C-c C-c w @key{RET}} or
3324 alternatively with @kbd{C-c C-c C-c w}.  Adding the non-predefined tag
3325 @samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h
3326 @key{RET} @key{RET}}.
3328 If you find that most of the time, you need only a single keypress to
3329 modify your list of tags, set the variable
3330 @code{org-fast-tag-selection-single-key}.  Then you no longer have to
3331 press @key{RET} to exit fast tag selection - it will immediately exit
3332 after the first change.  If you then occasionally need more keys, press
3333 @kbd{C-c} to turn off auto-exit for the current tag selection process.
3335 @node Tag searches,  , Setting tags, Tags
3336 @section Tag searches
3337 @cindex tag searches
3338 @cindex searching for tags
3340 Once a tags system has been set up, it can be used to collect related
3341 information into special lists.
3343 @table @kbd
3344 @kindex C-c \
3345 @item C-c \
3346 Create a sparse tree with all headlines matching a tags search.  With a
3347 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
3348 @kindex C-c a m
3349 @item C-c a m
3350 Create a global list of tag matches from all agenda files.
3351 @xref{Matching headline tags}.
3352 @kindex C-c a M
3353 @item C-c a M
3354 Create a global list of tag matches from all agenda files, but check
3355 only TODO items and force checking subitems (see variable
3356 @code{org-tags-match-list-sublevels}).
3357 @end table
3359 @cindex Boolean logic, for tag searches
3360 A @i{tags} search string can use Boolean operators @samp{&} for AND and
3361 @samp{|} for OR.  @samp{&} binds more strongly than @samp{|}.
3362 Parenthesis are currently not implemented.  A tag may also be preceded
3363 by @samp{-}, to select against it, and @samp{+} is syntactic sugar for
3364 positive selection.  The AND operator @samp{&} is optional when @samp{+}
3365 or @samp{-} is present.  Examples:
3367 @table @samp
3368 @item +WORK-BOSS
3369 Select headlines tagged @samp{:WORK:}, but discard those also tagged
3370 @samp{:BOSS:}.
3371 @item WORK|LAPTOP
3372 Selects lines tagged @samp{:WORK:} or @samp{:LAPTOP:}.
3373 @item WORK|LAPTOP&NIGHT
3374 Like before, but require the @samp{:LAPTOP:} lines to be tagged also
3375 @samp{NIGHT}.
3376 @end table
3378 @cindex TODO keyword matching, with tags search
3379 If you are using multi-state TODO keywords (@pxref{TODO extensions}), it
3380 can be useful to also match on the TODO keyword.  This can be done by
3381 adding a condition after a slash to a tags match.  The syntax is similar
3382 to the tag matches, but should be applied with consideration: For
3383 example, a positive selection on several TODO keywords can not
3384 meaningfully be combined with boolean AND.  However, @emph{negative
3385 selection} combined with AND can be meaningful.  To make sure that only
3386 lines are checked that actually have any TODO keyword, use @kbd{C-c a
3387 M}, or equivalently start the todo part after the slash with @samp{!}.
3388 Examples:
3390 @table @samp
3391 @item WORK/WAITING
3392 Select @samp{:WORK:}-tagged TODO lines with the specific TODO
3393 keyword @samp{WAITING}.
3394 @item WORK/!-WAITING-NEXT
3395 Select @samp{:WORK:}-tagged TODO lines that are neither @samp{WAITING}
3396 nor @samp{NEXT}
3397 @item WORK/+WAITING|+NEXT
3398 Select @samp{:WORK:}-tagged TODO lines that are either @samp{WAITING} or
3399 @samp{NEXT}.
3400 @end table
3402 @cindex regular expressions, with tags search
3403 Any element of the tag/todo match can be a regular expression - in this
3404 case it must be enclosed in curly braces.  For example,
3405 @samp{WORK+@{^BOSS.*@}} matches headlines that contain the tag
3406 @samp{WORK} and any tag @i{starting} with @samp{BOSS}.
3408 @cindex level, require for tags match
3409 You can also require a headline to be of a certain level, by writing
3410 instead of any TAG an expression like @samp{LEVEL=3}.  For example, a
3411 search @samp{+LEVEL=3+BOSS/-DONE} lists all level three headlines that
3412 have the tag BOSS and are @emph{not} marked with the todo keyword DONE.
3414 @node Agenda views, Embedded LaTeX, Tags, Top
3415 @chapter Agenda Views
3416 @cindex agenda views
3418 Due to the way Org-mode works, TODO items, time-stamped items, and
3419 tagged headlines can be scattered throughout a file or even a number of
3420 files.  To get an overview over open action items, or over events that
3421 are important for a particular date, this information must be collected,
3422 sorted and displayed in an organized way.
3424 Org-mode can select items based on various criteria, and display them
3425 in a separate buffer.  Six different view types are provided:
3427 @itemize @bullet
3428 @item
3429 an @emph{agenda} that is like a calendar and shows information
3430 for specific dates,
3431 @item
3432 a @emph{TODO list} that covers all unfinished
3433 action items,
3434 @item
3435 a @emph{tags view}, showings headlines based on
3436 the tags associated with them,
3437 @item
3438 a @emph{timeline view} that shows all events in a single Org-mode file,
3439 in time-sorted view,
3440 @item
3441 a @emph{stuck projects view} showing projects that currently don't move
3442 along, and
3443 @item
3444 @emph{custom views} that are special tag/keyword searches and
3445 combinations of different views.
3446 @end itemize
3448 @noindent
3449 The extracted information is displayed in a special @emph{agenda
3450 buffer}.  This buffer is read-only, but provides commands to visit the
3451 corresponding locations in the original Org-mode files, and even to
3452 edit these files remotely.  
3454 Two variables control how the agenda buffer is displayed and whether the
3455 window configuration is restored when the agenda exits:
3456 @code{org-agenda-window-setup} and
3457 @code{org-agenda-restore-windows-after-quit}.
3459 @menu
3460 * Agenda files::                Files being searched for agenda information
3461 * Agenda dispatcher::           Keyboard access to agenda views
3462 * Built-in agenda views::       What is available out of the box?
3463 * Presentation and sorting::    How agenda items are prepared for display
3464 * Agenda commands::             Remote editing of org trees
3465 * Custom agenda views::         Defining special searches and views
3466 @end menu
3468 @node Agenda files, Agenda dispatcher, Agenda views, Agenda views
3469 @section Agenda files
3470 @cindex agenda files
3471 @cindex files for agenda
3473 The information to be shown is collected from all @emph{agenda files},
3474 the files listed in the variable @code{org-agenda-files}@footnote{If the
3475 value of that variable is not a list, but a single file name, then the
3476 list of agenda files will be maintained in that external file.}.  Thus even
3477 if you only work with a single Org-mode file, this file should be put
3478 into that list@footnote{When using the dispatcher, pressing @kbd{1}
3479 before selecting a command will actually limit the command to the
3480 current file, and ignore @code{org-agenda-files} until the next
3481 dispatcher command.}.  You can customize @code{org-agenda-files}, but
3482 the easiest way to maintain it is through the following commands
3484 @cindex files, adding to agenda list
3485 @table @kbd
3486 @kindex C-c [
3487 @item C-c [
3488 Add current file to the list of agenda files.  The file is added to
3489 the front of the list.  If it was already in the list, it is moved to
3490 the front.  With prefix arg, file is added/moved to the end.
3491 @kindex C-c ]
3492 @item C-c ]
3493 Remove current file from the list of agenda files.
3494 @kindex C-,
3495 @kindex C-'
3496 @item C-,
3497 @itemx C-'
3498 Cycle through agenda file list, visiting one file after the other.
3499 @end table
3501 @noindent
3502 The Org menu contains the current list of files and can be used
3503 to visit any of them.
3505 @node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda views
3506 @section The agenda dispatcher
3507 @cindex agenda dispatcher
3508 @cindex dispatching agenda commands
3509 The views are created through a dispatcher that should be bound to a
3510 global key, for example @kbd{C-c a} (@pxref{Installation}).  In the
3511 following we will assume that @kbd{C-c a} is indeed how the dispatcher
3512 is accessed and list keyboard access to commands accordingly.  After
3513 pressing @kbd{C-c a}, an additional letter is required to execute a
3514 command.  The dispatcher offers the following default commands:
3515 @table @kbd
3516 @item a
3517 Create the calendar-like agenda (@pxref{Weekly/Daily agenda}).
3518 @item t @r{/} T
3519 Create a list of all TODO items (@pxref{Global TODO list}).
3520 @item m @r{/} M
3521 Create a list of headlines matching a TAGS expression (@pxref{Matching
3522 headline tags}).
3523 @item L
3524 Create the timeline view for the current buffer (@pxref{Timeline}).
3525 @item # @r{/} !
3526 Create a list of stuck projects (@pxref{Stuck projects}).
3527 @item 1
3528 Restrict an agenda command to the current buffer.  After pressing
3529 @kbd{1}, you still need to press the character selecting the command.
3530 @item 0
3531 If there is an active region, restrict the following agenda command to
3532 the region.  Otherwise, restrict it to the current subtree.  After
3533 pressing @kbd{0}, you still need to press the character selecting the
3534 command.
3535 @end table
3537 You can also define custom commands that will be accessible through the
3538 dispatcher, just like the default commands.  This includes the
3539 possibility to create extended agenda buffers that contain several
3540 blocks together, for example the weekly agenda, the global TODO list and
3541 a number of special tags matches.  @xref{Custom agenda views}.
3543 @node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda views
3544 @section The built-in agenda views
3546 In this section we describe the built-in views.
3548 @menu
3549 * Weekly/Daily agenda::         The calendar page with current tasks
3550 * Global TODO list::            All unfinished action items
3551 * Matching headline tags::      Structured information with fine-tuned search
3552 * Timeline::                    Time-sorted view for single file
3553 * Stuck projects::              Find projects you need to review
3554 @end menu
3556 @node Weekly/Daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views
3557 @subsection The weekly/daily agenda
3558 @cindex agenda
3559 @cindex weekly agenda
3560 @cindex daily agenda
3562 The purpose of the weekly/daily @emph{agenda} is to act like a page of a
3563 paper agenda, showing all the tasks for the current week or day.
3565 @table @kbd
3566 @cindex org-agenda, command
3567 @kindex C-c a a
3568 @item C-c a a
3569 Compile an agenda for the current week from a list of org files.  The
3570 agenda shows the entries for each day.  With a @kbd{C-u} prefix (or
3571 when the variable @code{org-agenda-include-all-todo} is @code{t}), all
3572 unfinished TODO items (including those without a date) are also listed at
3573 the beginning of the buffer, before the first date.@*
3574 @end table
3576 Remote editing from the agenda buffer means, for example, that you can
3577 change the dates of deadlines and appointments from the agenda buffer.
3578 The commands available in the Agenda buffer are listed in @ref{Agenda
3579 commands}.
3581 @subsubheading Calendar/Diary integration
3582 @cindex calendar integration
3583 @cindex diary integration
3585 Emacs contains the calendar and diary by Edward M. Reingold.  The
3586 calendar displays a three-month calendar with holidays from different
3587 countries and cultures.  The diary allows you to keep track of
3588 anniversaries, lunar phases, sunrise/set, recurrent appointments
3589 (weekly, monthly) and more.  In this way, it is quite complementary to
3590 Org-mode.  It can be very useful to combine output from Org-mode with
3591 the diary.
3593 In order to include entries from the Emacs diary into Org-mode's
3594 agenda, you only need to customize the variable
3596 @lisp
3597 (setq org-agenda-include-diary t)
3598 @end lisp
3600 @noindent After that, everything will happen automatically.  All diary
3601 entries including holidays, anniversaries etc will be included in the
3602 agenda buffer created by Org-mode.  @key{SPC}, @key{TAB}, and
3603 @key{RET} can be used from the agenda buffer to jump to the diary
3604 file in order to edit existing diary entries.  The @kbd{i} command to
3605 insert new entries for the current date works in the agenda buffer, as
3606 well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
3607 Sunrise/Sunset times, show lunar phases and to convert to other
3608 calendars, respectively.  @kbd{c} can be used to switch back and forth
3609 between calendar and agenda.
3612 @node Global TODO list, Matching headline tags, Weekly/Daily agenda, Built-in agenda views
3613 @subsection The global TODO list
3614 @cindex global TODO list
3615 @cindex TODO list, global
3617 The global TODO list contains all unfinished TODO items, formatted and
3618 collected into a single place.
3620 @table @kbd
3621 @kindex C-c a t
3622 @item C-c a t
3623 Show the global TODO list.  This collects the TODO items from all
3624 agenda files (@pxref{Agenda views}) into a single buffer.  The buffer is in
3625 @code{agenda-mode}, so there are commands to examine and manipulate
3626 the TODO entries directly from that buffer (@pxref{Agenda commands}).
3627 @kindex C-c a T
3628 @item C-c a T
3629 @cindex TODO keyword matching
3630 Like the above, but allows selection of a specific TODO keyword.  You can
3631 also do this by specifying a prefix argument to @kbd{C-c a t}.  With a
3632 @kbd{C-u} prefix you are prompted for a keyword.  With a numeric
3633 prefix, the Nth keyword in @code{org-todo-keywords} is selected.
3634 @kindex r
3635 The @kbd{r} key in the agenda buffer regenerates it, and you can give
3636 a prefix argument to this command to change the selected TODO keyword,
3637 for example @kbd{3 r}.  If you often need a search for a specific
3638 keyword, define a custom command for it (@pxref{Agenda dispatcher}).@*
3639 Matching specific TODO keywords can also be done as part of a tags
3640 search (@pxref{Tag searches}).
3641 @end table
3643 Remote editing of TODO items means that you can change the state of a
3644 TODO entry with a single key press.  The commands available in the
3645 TODO list are described in @ref{Agenda commands}.
3647 @cindex sublevels, inclusion into todo list
3648 Normally the global todo list simply shows all headlines with TODO
3649 keywords.  This list can become very long.  There are two ways to keep
3650 it more compact:
3651 @itemize @minus
3652 @item
3653 Some people view a TODO item that has been @emph{scheduled} for
3654 execution (@pxref{Time stamps}) as no longer @emph{open}.  Configure the
3655 variable @code{org-agenda-todo-ignore-scheduled} to exclude scheduled
3656 items from the global TODO list.
3657 @item
3658 TODO items may have sublevels to break up the task into subtasks.  In
3659 such cases it may be enough to list only the highest level TODO headline
3660 and omit the sublevels from the global list.  Configure the variable
3661 @code{org-agenda-todo-list-sublevels} to get this behavior.
3662 @end itemize
3664 @node Matching headline tags, Timeline, Global TODO list, Built-in agenda views
3665 @subsection Matching headline tags
3666 @cindex matching, of tags
3667 @cindex tags view
3669 If headlines in the agenda files are marked with @emph{tags}
3670 (@pxref{Tags}), you can select headlines based on the tags that apply
3671 to them and collect them into an agenda buffer.
3673 @table @kbd
3674 @kindex C-c a m
3675 @item C-c a m
3676 Produce a list of all headlines that match a given set of tags.  The
3677 command prompts for a selection criterion, which is a boolean logic
3678 expression with tags, like @samp{+WORK+URGENT-WITHBOSS} or
3679 @samp{WORK|HOME} (@pxref{Tags}).  If you often need a specific search,
3680 define a custom command for it (@pxref{Agenda dispatcher}).
3681 @kindex C-c a M
3682 @item C-c a M
3683 Like @kbd{C-c a m}, but only select headlines that are also TODO items
3684 and force checking subitems (see variable
3685 @code{org-tags-match-list-sublevels}).  Matching specific todo keywords
3686 together with a tags match is also possible, see @ref{Tag searches}.
3687 @end table
3689 The commands available in the tags list are described in @ref{Agenda
3690 commands}.
3692 @node Timeline, Stuck projects, Matching headline tags, Built-in agenda views
3693 @subsection Timeline for a single file
3694 @cindex timeline, single file
3695 @cindex time-sorted view
3697 The timeline summarizes all time-stamped items from a single Org-mode
3698 file in a @emph{time-sorted view}.  The main purpose of this command is
3699 to give an overview over events in a project.
3701 @table @kbd
3702 @kindex C-a a L
3703 @item C-c a L
3704 Show a time-sorted view of the org file, with all time-stamped items.
3705 When called with a @kbd{C-u} prefix, all unfinished TODO entries
3706 (scheduled or not) are also listed under the current date.
3707 @end table
3709 @noindent
3710 The commands available in the timeline buffer are listed in
3711 @ref{Agenda commands}.
3714 @node Stuck projects,  , Timeline, Built-in agenda views
3715 @subsection Stuck projects
3717 If you are following a system like David Allen's GTD to organize your
3718 work, one of the ``duties'' you have is a regular review to make sure
3719 that all projects move along.  A @emph{stuck} project is a project that
3720 has no defined next actions, so it will never show up in the TODO lists
3721 Org-mode produces.  During the review, you need to identify such
3722 projects and define next actions for them.
3724 @table @kbd
3725 @kindex C-c a #
3726 @item C-c a #
3727 List projects that are stuck.
3728 @kindex C-c a !
3729 @item C-c a !
3730 Customize the variable @code{org-stuck-projects} to define what a stuck
3731 project is and how to find it.
3732 @end table
3734 You almost certainly will have to configure this view before it will
3735 work for you.  The built-in default assumes that all your projects are
3736 level-2 headlines, and that a project is not stuck if it has at least
3737 one entry marked with a todo keyword TODO or NEXT or NEXTACTION.
3739 Lets assume that you, in your own way of using Org-mode, identify
3740 projects with a tag PROJECT, and that you use a todo keyword MAYBE to
3741 indicate a project that should not be considered yet.  Lets further
3742 assume that the todo keyword DONE marks finished projects, and that NEXT
3743 and TODO indicate next actions.  Finally, the tag @@SHOP indicates
3744 shopping and is a next action even without the NEXT tag.  In this case
3745 you would start by identifying elegible projects with a tags/todo match
3746 @samp{+PROJECT/-MAYBE-DONE}, and then check for TODO, NEXT and @@SHOP in
3747 the subtree to identify projects that are not stuck.  The correct
3748 customization for this is
3750 @lisp
3751 (setq org-stuck-projects
3752       ("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")))
3753 @end lisp
3756 @node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda views
3757 @section Presentation and sorting
3758 @cindex presentation, of agenda items
3760 Before displaying items in an agenda view, Org-mode visually prepares
3761 the items and sorts them.  Each item occupies a single line.  The line
3762 starts with a @emph{prefix} that contains the @emph{category}
3763 (@pxref{Categories}) of the item and other important information.  You can
3764 customize the prefix using the option @code{org-agenda-prefix-format}.
3765 The prefix is followed by a cleaned-up version of the outline headline
3766 associated with the item.
3768 @menu
3769 * Categories::                  Not all tasks are equal
3770 * Time-of-day specifications::  How the agenda knows the time
3771 * Sorting of agenda items::     The order of things
3772 @end menu
3774 @node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting
3775 @subsection Categories
3777 @cindex category
3778 The category is a broad label assigned to each agenda item.  By default,
3779 the category is simply derived from the file name, but you can also
3780 specify it with a special line in the buffer, like this:
3782 @example
3783 #+CATEGORY: Thesis
3784 @end example
3786 If there are several such lines in a file, each specifies the category
3787 for the text below it (but the first category also applies to any text
3788 before the first CATEGORY line).  The display in the agenda buffer looks
3789 best if the category is not longer than 10 characters.
3791 @node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting
3792 @subsection Time-of-Day Specifications
3793 @cindex time-of-day specification
3795 Org-mode checks each agenda item for a time-of-day specification.  The
3796 time can be part of the time stamp that triggered inclusion into the
3797 agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}.  Time
3798 ranges can be specified with two time stamps, like
3800 @w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
3802 In the headline of the entry itself, a time(range) may also appear as
3803 plain text (like @samp{12:45} or a @samp{8:30-1pm}.  If the agenda
3804 integrates the Emacs diary (@pxref{Weekly/Daily agenda}), time
3805 specifications in diary entries are recognized as well.
3807 For agenda display, Org-mode extracts the time and displays it in a
3808 standard 24 hour format as part of the prefix.  The example times in
3809 the previous paragraphs would end up in the agenda like this:
3811 @example
3812     8:30-13:00 Arthur Dent lies in front of the bulldozer
3813    12:45...... Ford Prefect arrives and takes Arthur to the pub
3814    19:00...... The Vogon reads his poem
3815    20:30-22:15 Marwin escorts the Hitchhikers to the bridge
3816 @end example
3818 @cindex time grid
3819 If the agenda is in single-day mode, or for the display of today, the
3820 timed entries are embedded in a time grid, like
3822 @example
3823     8:00...... ------------------
3824     8:30-13:00 Arthur Dent lies in front of the bulldozer
3825    10:00...... ------------------
3826    12:00...... ------------------
3827    12:45...... Ford Prefect arrives and takes Arthur to the pub
3828    14:00...... ------------------
3829    16:00...... ------------------
3830    18:00...... ------------------
3831    19:00...... The Vogon reads his poem
3832    20:00...... ------------------
3833    20:30-22:15 Marwin escorts the Hitchhikers to the bridge
3834 @end example
3836 The time grid can be turned on and off with the variable
3837 @code{org-agenda-use-time-grid}, and can be configured with
3838 @code{org-agenda-time-grid}.
3840 @node Sorting of agenda items,  , Time-of-day specifications, Presentation and sorting
3841 @subsection Sorting of agenda items
3842 @cindex sorting, of agenda items
3843 @cindex priorities, of agenda items
3844 Before being inserted into a view, the items are sorted.  How this is
3845 done depends on the type of view.
3846 @itemize @bullet
3847 @item
3848 For the daily/weekly agenda, the items for each day are sorted.  The
3849 default order is to first collect all items containing an explicit
3850 time-of-day specification.  These entries will be shown at the beginning
3851 of the list, as a @emph{schedule} for the day.  After that, items remain
3852 grouped in categories, in the sequence given by @code{org-agenda-files}.
3853 Within each category, items are sorted by priority (@pxref{Priorities}),
3854 which is composed of the base priority (2000 for priority @samp{A}, 1000
3855 for @samp{B}, and 0 for @samp{C}), plus additional increments for
3856 overdue scheduled or deadline items.
3857 @item 
3858 For the TODO list, items remain in the order of categories, but within
3859 each category, sorting takes place according to priority
3860 (@pxref{Priorities}).
3861 @item
3862 For tags matches, items are not sorted at all, but just appear in the
3863 sequence in which they are found in the agenda files.
3864 @end itemize
3866 Sorting can be customized using the variable
3867 @code{org-agenda-sorting-strategy}.
3870 @node Agenda commands, Custom agenda views, Presentation and sorting, Agenda views
3871 @section Commands in the agenda buffer
3872 @cindex commands, in agenda buffer
3874 Entries in the agenda buffer are linked back to the org file or diary
3875 file where they originate.  You are not allowed to edit the agenda
3876 buffer itself, but commands are provided to show and jump to the
3877 original entry location, and to edit the org-files ``remotely'' from
3878 the agenda buffer.  In this way, all information is stored only once,
3879 removing the risk that your agenda and note files may diverge.
3881 Some commands can be executed with mouse clicks on agenda lines.  For
3882 the other commands, the cursor needs to be in the desired line.
3884 @table @kbd
3885 @tsubheading{Motion}
3886 @cindex motion commands in agenda
3887 @kindex n
3888 @item n
3889 Next line (same as @key{up}).
3890 @kindex p
3891 @item p
3892 Previous line (same as @key{down}).
3893 @tsubheading{View/GoTo org file}
3894 @kindex mouse-3
3895 @kindex @key{SPC}
3896 @item mouse-3
3897 @itemx @key{SPC}
3898 Display the original location of the item in another window.
3900 @kindex L
3901 @item L
3902 Display original location and recenter that window.
3904 @kindex mouse-2
3905 @kindex mouse-1
3906 @kindex @key{TAB}
3907 @item mouse-2
3908 @itemx mouse-1
3909 @itemx @key{TAB}
3910 Go to the original location of the item in another window.  Under Emacs
3911 22, @kbd{mouse-1} will also works for this.
3913 @kindex @key{RET}
3914 @itemx @key{RET}
3915 Go to the original location of the item and delete other windows.
3917 @kindex f
3918 @item f
3919 Toggle Follow mode.  In Follow mode, as you move the cursor through
3920 the agenda buffer, the other window always shows the corresponding
3921 location in the org file.  The initial setting for this mode in new
3922 agenda buffers can be set with the variable
3923 @code{org-agenda-start-with-follow-mode}.
3925 @kindex b
3926 @item b
3927 Display the entire subtree of the current item in an indirect buffer.
3928 With numerical prefix ARG, go up to this level and then take that tree.
3929 If ARG is negative, go up that many levels.  With @kbd{C-u} prefix, do
3930 not remove the previously used indirect buffer.
3932 @kindex l
3933 @item l
3934 Toggle Logbook mode.  In Logbook mode, entries that where marked DONE while
3935 logging was on (variable @code{org-log-done}) are shown in the agenda,
3936 as are entries that have been clocked on that day.
3938 @tsubheading{Change display}
3939 @cindex display changing, in agenda
3940 @kindex o
3941 @item o
3942 Delete other windows.
3944 @kindex w
3945 @item w
3946 Switch to weekly view (7 days displayed together).
3948 @kindex d
3949 @item d
3950 Switch to daily view (just one day displayed).
3952 @kindex D
3953 @item D
3954 Toggle the inclusion of diary entries.  See @ref{Weekly/Daily agenda}.
3956 @kindex g
3957 @item g
3958 Toggle the time grid on and off.  See also the variables
3959 @code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
3961 @kindex r
3962 @item r
3963 Recreate the agenda buffer, for example to reflect the changes
3964 after modification of the time stamps of items with S-@key{left} and
3965 S-@key{right}.  When the buffer is the global todo list, a prefix
3966 argument is interpreted to create a selective list for a specific TODO
3967 keyword.
3969 @kindex s
3970 @item s
3971 Save all Org-mode buffers in the current Emacs session.
3973 @kindex @key{right}
3974 @item @key{right}
3975 Display the following @code{org-agenda-ndays} days.  For example, if
3976 the display covers a week, switch to the following week.  With prefix
3977 arg, go forward that many times @code{org-agenda-ndays} days.
3979 @kindex @key{left}
3980 @item @key{left}
3981 Display the previous dates.
3983 @kindex .
3984 @item .
3985 Goto today.
3987 @tsubheading{Remote editing}
3988 @cindex remote editing, from agenda
3990 @item 0-9
3991 Digit argument.
3993 @cindex undoing remote-editing events
3994 @cindex remote editing, undo
3995 @kindex C-_
3996 @item C-_
3997 Undo a change due to a remote editing command.  The change is undone
3998 both in the agenda buffer and in the remote buffer.
4000 @kindex t
4001 @item t
4002 Change the TODO state of the item, both in the agenda and in the
4003 original org file.
4005 @kindex C-k
4006 @item C-k
4007 Delete the current agenda item along with the entire subtree belonging
4008 to it in the original Org-mode file.  If the text to be deleted remotely
4009 is longer than one line, the kill needs to be confirmed by the user.  See
4010 variable @code{org-agenda-confirm-kill}.
4012 @kindex $
4013 @item $
4014 Archive the subtree corresponding to the current headline.
4016 @kindex T
4017 @item T
4018 Show all tags associated with the current item.  Because of
4019 inheritance, this may be more than the tags listed in the line itself.
4021 @kindex :
4022 @item :
4023 Set tags for the current headline.
4025 @kindex a
4026 @item a
4027 Toggle the ARCHIVE tag for the current headline.
4029 @kindex ,
4030 @item ,
4031 Set the priority for the current item.  Org-mode prompts for the
4032 priority character. If you reply with @key{SPC}, the priority cookie
4033 is removed from the entry.
4035 @kindex P
4036 @item P
4037 Display weighted priority of current item.
4039 @kindex +
4040 @kindex S-@key{up}
4041 @item +
4042 @itemx S-@key{up}
4043 Increase the priority of the current item.  The priority is changed in
4044 the original buffer, but the agenda is not resorted.  Use the @kbd{r}
4045 key for this.
4047 @kindex -
4048 @kindex S-@key{down}
4049 @item -
4050 @itemx S-@key{down}
4051 Decrease the priority of the current item.
4053 @kindex C-c C-s
4054 @item C-c C-s
4055 Schedule this item
4057 @kindex C-c C-d
4058 @item C-c C-d
4059 Set a deadline for this item.
4061 @kindex S-@key{right}
4062 @item S-@key{right}
4063 Change the time stamp associated with the current line by one day into
4064 the future.  With prefix argument, change it by that many days.  For
4065 example, @kbd{3 6 5 S-@key{right}} will change it by a year.  The
4066 stamp is changed in the original org file, but the change is not
4067 directly reflected in the agenda buffer.  Use the
4068 @kbd{r} key to update the buffer.
4070 @kindex S-@key{left}
4071 @item S-@key{left}
4072 Change the time stamp associated with the current line by one day
4073 into the past.
4075 @kindex >
4076 @item >
4077 Change the time stamp associated with the current line to today.
4078 The key @kbd{>} has been chosen, because it is the same as @kbd{S-.}
4079 on my keyboard.
4081 @kindex I
4082 @item I
4083 Start the clock on the current item.  If a clock is running already, it
4084 is stopped first.
4085 @kindex O
4086 @item O
4087 Stop the previously started clock.
4088 @kindex X
4089 @item X
4090 Cancel the currently running clock.
4092 @tsubheading{Calendar commands}
4093 @cindex calendar commands, from agenda
4094 @kindex c
4095 @item c
4096 Open the Emacs calendar and move to the date at the agenda cursor.
4098 @item c
4099 When in the calendar, compute and show the Org-mode agenda for the
4100 date at the cursor.
4102 @cindex diary entries, creating from agenda
4103 @kindex i
4104 @item i
4105 Insert a new entry into the diary.  Prompts for the type of entry
4106 (day, weekly, monthly, yearly, anniversary, cyclic) and creates a new
4107 entry in the diary, just as @kbd{i d} etc. would do in the calendar.
4108 The date is taken from the cursor position.
4110 @kindex M
4111 @item M
4112 Show the phases of the moon for the three months around current date.
4114 @kindex S
4115 @item S
4116 Show sunrise and sunset times.  The geographical location must be set
4117 with calendar variables, see documentation of the Emacs calendar.
4119 @kindex C
4120 @item C
4121 Convert the date at cursor into many other cultural and historic
4122 calendars.
4124 @kindex H
4125 @item H
4126 Show holidays for three month around the cursor date.
4128 @c FIXME:  This should be a different key.
4129 @kindex C-c C-x C-c
4130 @item C-c C-x C-c
4131 Export a single iCalendar file containing entries from all agenda files.
4133 @tsubheading{Quit and Exit}
4134 @kindex q
4135 @item q
4136 Quit agenda, remove the agenda buffer.
4138 @kindex x
4139 @cindex agenda files, removing buffers
4140 @item x
4141 Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
4142 for the compilation of the agenda.  Buffers created by the user to
4143 visit org files will not be removed.
4145 @end table
4148 @node Custom agenda views,  , Agenda commands, Agenda views
4149 @section Custom agenda views
4150 @cindex custom agenda views
4151 @cindex agenda views, custom
4153 Custom agenda commands serve two purposes: to store and quickly access
4154 frequently used TODO and tags searches, and to create special composite
4155 agenda buffers.  Custom agenda commands will be accessible through the
4156 dispatcher (@pxref{Agenda dispatcher}), just like the default commands.
4158 @menu
4159 * Storing searches::            Type once, use often
4160 * Block agenda::                All the stuff you need in a single buffer
4161 * Setting Options::             Changing the rules
4162 * Batch processing::            Agenda views from the command line
4163 @end menu
4165 @node Storing searches, Block agenda, Custom agenda views, Custom agenda views
4166 @subsection Storing searches
4168 The first application of custom searches is the definition of keyboard
4169 shortcuts for frequently used searches, either creating an agenda
4170 buffer, or a sparse tree (the latter covering of course only the current
4171 buffer).
4172 @kindex C-c a C
4173 Custom commands are configured in the variable
4174 @code{org-agenda-custom-commands}.  You can customize this variable, for
4175 example by pressing @kbd{C-c a C}.  You can also directly set it with
4176 Emacs Lisp in @file{.emacs}.  The following example contains all valid
4177 search types:
4179 @lisp
4180 @group
4181 (setq org-agenda-custom-commands
4182       '(("w" todo "WAITING")
4183         ("W" todo-tree "WAITING")
4184         ("u" tags "+BOSS-URGENT")
4185         ("v" tags-todo "+BOSS-URGENT")
4186         ("U" tags-tree "+BOSS-URGENT")
4187         ("f" occur-tree "\\<FIXME\\>")))
4188 @end group
4189 @end lisp
4191 @noindent
4192 The initial single-character string in each entry defines the character
4193 you have to press after the dispatcher command @kbd{C-c a} in order to
4194 access the command.   The second parameter is the search type, followed
4195 by the string or regular expression to be used for the matching.  The
4196 example above will therefore define:
4198 @table @kbd
4199 @item C-c a w
4200 as a global search for TODO entries with @samp{WAITING} as the TODO
4201 keyword
4202 @item C-c a W
4203 as the same search, but only in the current buffer and displaying the
4204 results as a sparse tree
4205 @item C-c a u
4206 as a global tags search for headlines marked @samp{:BOSS:} but not
4207 @samp{:URGENT:}
4208 @item C-c a v
4209 as the same search as @kbd{C-c a u}, but limiting the search to
4210 headlines that are also TODO items
4211 @item C-c a U
4212 as the same search as @kbd{C-c a u}, but only in the current buffer and
4213 displaying the result as a sparse tree
4214 @item C-c a f
4215 to create a sparse tree (again: current buffer only) with all entries
4216 containing the word @samp{FIXME}.
4217 @end table
4219 @node Block agenda, Setting Options, Storing searches, Custom agenda views
4220 @subsection Block agenda
4221 @cindex block agenda
4222 @cindex agenda, with block views
4224 Another possibility is the construction of agenda views that comprise
4225 the results of @emph{several} commands, each of which creates a block in
4226 the agenda buffer.  The available commands include @code{agenda} for the
4227 daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo}
4228 for the global todo list (as constructed with @kbd{C-c a t}), and the
4229 matching commands discussed above: @code{todo}, @code{tags}, and
4230 @code{tags-todo}.  Here are two examples:
4232 @lisp
4233 @group
4234 (setq org-agenda-custom-commands
4235       '(("h" "Agenda and Home-related tasks"
4236          ((agenda)
4237           (tags-todo "HOME")
4238           (tags "GARDEN")))
4239         ("o" "Agenda and Office-related tasks"
4240          ((agenda)
4241           (tags-todo "WORK")
4242           (tags "OFFICE")))))
4243 @end group
4244 @end lisp
4246 @noindent
4247 This will define @kbd{C-c a h} to create a multi-block view for stuff
4248 you need to attend to at home.  The resulting agenda buffer will contain
4249 your agenda for the current week, all TODO items that carry the tag
4250 @samp{HOME}, and also all lines tagged with @samp{GARDEN}.  Finally the
4251 command @kbd{C-c a o} provides a similar view for office tasks.
4254 @node Setting Options, Batch processing, Block agenda, Custom agenda views
4255 @subsection Setting Options for custom commands
4256 @cindex options, for custom agenda views
4258 Org-mode contains a number of variables regulating agenda construction
4259 and display.  The global variables define the behavior for all agenda
4260 commands, including the custom commands.  However, if you want to change
4261 some settings just for a single custom view, you can do so.  Setting
4262 options requires inserting a list of variable names and values at the
4263 right spot in @code{org-agenda-custom-commands}.  For example:
4265 @lisp
4266 @group
4267 (setq org-agenda-custom-commands
4268       '(("w" todo "WAITING"
4269          ((org-agenda-sorting-strategy '(priority-down))
4270           (org-agenda-prefix-format "  Mixed: ")))
4271         ("U" tags-tree "+BOSS-URGENT"
4272          ((org-show-following-heading nil)
4273           (org-show-hierarchy-above nil)))))
4274 @end group
4275 @end lisp
4277 @noindent
4278 Now the @kbd{C-c a w} command will sort the collected entries only by
4279 priority, and the prefix format is modified to just say @samp{  Mixed:}
4280 instead of giving the category of the entry.  The sparse tags tree of
4281 @kbd{C-c a U} will now turn out ultra-compact, because neither the
4282 headline hierarchy above the match, nor the headline following the match
4283 will be shown.
4285 For command sets creating a block agenda,
4286 @code{org-agenda-custom-commands} has two separate spots for setting
4287 options.  You can add options that should be valid for just a single
4288 command in the set, and options that should be valid for all commands in
4289 the set.  The former are just added to the command entry, the latter
4290 must come after the list of command entries.  Going back to the block
4291 agenda example (@pxref{Block agenda}), let's change the sorting strategy
4292 for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort
4293 the results for GARDEN tags query in the opposite order,
4294 @code{priority-up}.  This would look like this:
4296 @lisp
4297 @group
4298 (setq org-agenda-custom-commands
4299       '(("h" "Agenda and Home-related tasks"
4300          ((agenda)
4301           (tags-todo "HOME")
4302           (tags "GARDEN" ((org-agenda-sorting-strategy '(priority-up)))))
4303          ((org-agenda-sorting-strategy '(priority-down))))
4304         ("o" "Agenda and Office-related tasks"
4305          ((agenda)
4306           (tags-todo "WORK")
4307           (tags "OFFICE")))))
4308 @end group
4309 @end lisp
4311 As you see, the values and parenthesis setting is a little complex.
4312 When in doubt, use the customize interface to set this variable - it
4313 fully supports its structure.  Just one caveat: When setting options in
4314 this interface, the @emph{values} are just lisp expressions.  So if the
4315 value is a string, you need to add the double quotes around the value
4316 yourself.
4318 @node Batch processing,  , Setting Options, Custom agenda views
4319 @subsection Creating agenda views in batch processing
4320 @cindex agenda, batch production
4322 If you want to print or otherwise reprocess agenda views, it can be
4323 useful to create an agenda from the command line.  This is the purpose
4324 of the function @code{org-batch-agenda}.  It takes as a parameter one of
4325 the strings that are the keys in @code{org-agenda-custom-commands}.  For
4326 example, to directly print the current TODO list, you could use
4328 @example
4329 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
4330 @end example
4332 @noindent
4333 You may also modify parameters on the fly like this:
4335 @example
4336 emacs -batch -l ~/.emacs                                      \
4337    -eval '(org-batch-agenda "a"                               \
4338             org-agenda-ndays 300                              \
4339             org-agenda-include-diary nil                      \
4340             org-agenda-files (quote ("~/org/project.org")))'  \
4341    | lpr
4342 @end example
4344 @noindent
4345 which will produce a 300 day agenda, fully restricted to the Org file
4346 @file{~/org/projects.org}, not even including the diary.
4348 @node Embedded LaTeX, Exporting, Agenda views, Top
4349 @chapter Embedded LaTeX
4350 @cindex @TeX{} interpretation
4351 @cindex La@TeX{} interpretation
4353 Plain ASCII is normally sufficient for almost all note taking.  One
4354 exception, however, are scientific notes which need to be able to
4355 contain mathematical symbols and the occasional formula.
4356 La@TeX{}@footnote{La@TeX{} is a macro system based on Donald E. Knuth's
4357 @TeX{} system.  Many of the features described here as ``La@TeX{}'' are
4358 really from @TeX{}, but for simplicity I am blurring this distinction.}
4359 is widely used to typeset scientific documents. Org-mode supports
4360 embedding La@TeX{} code into its files, because many academics are used
4361 to read La@TeX{} source code, and because it can be readily processed
4362 into images for HTML production.
4364 It is not necessary to mark La@TeX{} macros and code in any special way.
4365 If you observe a few conventions, Org-mode knows how to find it and what
4366 to do with it.
4368 @menu
4369 * Math symbols::                TeX macros for symbols and Greek letters
4370 * Subscripts and Superscripts::  Simple syntax for raising/lowering text
4371 * LaTeX fragments::             Complex formulas made easy
4372 * Processing LaTeX fragments::  Previewing LaTeX processing
4373 * CDLaTeX mode::                Speed up entering of formulas
4374 @end menu
4376 @node Math symbols, Subscripts and Superscripts, Embedded LaTeX, Embedded LaTeX
4377 @section Math symbols
4378 @cindex math symbols
4379 @cindex TeX macros
4381 You can use La@TeX{} macros to insert special symbols like @samp{\alpha}
4382 to indicate the Greek letter, or @samp{\to} to indicate an arrow.
4383 Completion for these macros is available, just type @samp{\} and maybe a
4384 few letters, and press @kbd{M-@key{TAB}} to see possible completions.
4385 Unlike La@TeX{} code, Org-mode allows these macros to be present
4386 without surrounding math delimiters, for example:
4388 @example
4389 Angles are written as Greek letters \alpha, \beta and \gamma.
4390 @end example
4392 During HTML export (@pxref{HTML export}), these symbols are translated
4393 into the proper syntax for HTML, for the above examples this is
4394 @samp{&alpha;} and @samp{&rarr;}, respectively.
4396 @node Subscripts and Superscripts, LaTeX fragments, Math symbols, Embedded LaTeX
4397 @section Subscripts and Superscripts
4398 @cindex subscript
4399 @cindex superscript
4401 Just like in La@TeX{}, @samp{^} and @samp{_} are used to indicate super-
4402 and subscripts.  Again, these can be used without embedding them in
4403 math-mode delimiters.  To increase the readability of ASCII text, it is
4404 not necessary (but OK) to surround multi-character sub- and superscripts
4405 with curly braces.  For example
4407 @example
4408 The mass if the sun is M_sun = 1.989 x 10^30 kg.  The radius of
4409 the sun is R_@{sun@} = 6.96 x 10^8 m.
4410 @end example
4412 To avoid interpretation as raised or lowered text, you can quote
4413 @samp{^} and @samp{_} with a backslash: @samp{\_} and @samp{\^}.
4415 During HTML export (@pxref{HTML export}), subscript and superscripts
4416 are surrounded with @code{<sub>} and @code{<sup>} tags, respectively.
4418 @node LaTeX fragments, Processing LaTeX fragments, Subscripts and Superscripts, Embedded LaTeX
4419 @section LaTeX fragments
4420 @cindex LaTeX fragments
4422 With symbols, sub- and superscripts, HTML is pretty much at its end when
4423 it comes to representing mathematical formulas@footnote{Yes, there is
4424 MathML, but that is not yet fully supported by many browsers, and there
4425 is no decent converter for turning LaTeX of ASCII representations of
4426 formulas into MathML.  So for the time being, converting formulas into
4427 images seems the way to go.}.  More complex
4428 expressions need a dedicated formula processor.  To this end, Org-mode
4429 can contain arbitrary La@TeX{} fragments.  It provides commands to
4430 preview the typeset result of these fragments, and upon export to HTML,
4431 all fragments will be converted to images and inlined into the HTML
4432 document.  For this to work you need to be on a system with a working
4433 La@TeX{} installation.  You also need the @file{dvipng} program,
4434 available at @url{http://sourceforge.net/projects/dvipng/}.
4436 La@TeX{} fragments don't need any special marking at all.  The following
4437 snippets will be identified as LaTeX source code:
4438 @itemize @bullet
4439 @item
4440 Environments of any kind.  The only requirement is that the
4441 @code{\begin} statement appears on a new line, preceded by only
4442 whitespace.
4443 @item
4444 Text within the usual La@TeX{} math delimiters.  To avoid conflicts with
4445 currency specifications, single @samp{$} characters are only recognized
4446 as math delimiters if the enclosed text contains at most two line breaks,
4447 is directly attached to the @samp{$} characters with no whitespace in
4448 between, and if the closing @samp{$} is followed by whitespace or
4449 punctuation.  For the other delimiters, there is no such restriction, so
4450 when in doubt, use @samp{\(...\)} as inline math delimiters.
4451 @end itemize
4453 @noindent For example:
4455 @example
4456 \begin@{equation@}                          % arbitrary environments,
4457 x=\sqrt@{b@}                                % even tables, figures
4458 \end@{equation@}                            % etc
4460 If $a^2=b$ and \( b=2 \), then the solution must be
4461 either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
4462 @end example
4464 @noindent
4465 If you need any of the delimiter ASCII sequences for other purposes, you
4466 can configure the option @code{org-format-latex-options} to deselect the
4467 ones you do not wish to have interpreted by the La@TeX{} converter.
4469 @node Processing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX
4470 @section Processing LaTeX fragments
4471 @cindex LaTeX fragments, preview
4473 La@TeX{} fragments can be processed to produce a preview images of the
4474 typeset expressions:
4476 @table @kbd
4477 @kindex C-c C-x C-l
4478 @item C-c C-x C-l
4479 Produce a preview image of the La@TeX{} fragment at point and overlay it
4480 over the source code.  If there is no fragment at point, process all
4481 fragments in the current entry (between two headlines).  When called
4482 with a prefix argument, process the entire subtree.  When called with
4483 two prefix arguments, or when the cursor is before the first headline,
4484 process the entire buffer.
4485 @kindex C-c C-c
4486 @item C-c C-c
4487 Remove the overlay preview images.
4488 @end table
4490 During HTML export (@pxref{HTML export}), all La@TeX{} fragments are
4491 converted into images and inlined into the document if the following
4492 setting is active:
4494 @lisp
4495 (setq org-export-with-LaTeX-fragments t)
4496 @end lisp
4498 @node CDLaTeX mode,  , Processing LaTeX fragments, Embedded LaTeX
4499 @section Using CDLaTeX to enter math
4500 @cindex CDLaTeX
4502 CDLaTeX-mode is a minor mode that is normally used in combination with a
4503 major LaTeX mode like AUCTeX in order to speed-up insertion of
4504 environments and math templates.  Inside Org-mode, you can make use of
4505 some of the features of cdlatex-mode.  You need to install
4506 @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
4507 AUCTeX) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}.
4508 Don't turn cdlatex-mode itself under Org-mode, but use the light
4509 version @code{org-cdlatex-mode} that comes as part of Org-mode.  Turn it
4510 on for the current buffer with @code{M-x org-cdlatex-mode}, or for all
4511 Org-mode files with
4513 @lisp
4514 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
4515 @end lisp
4517 When this mode is enabled, the following features are present (for more
4518 details see the documentation of cdlatex-mode):
4519 @itemize @bullet
4520 @kindex C-c @{
4521 @item
4522 Environment templates can be inserted with @kbd{C-c @{}.
4523 @item
4524 @kindex @key{TAB}
4525 The @key{TAB} key will do template expansion if the cursor is inside a
4526 LaTeX fragment@footnote{Org-mode has a method to test if the cursor is
4527 inside such a fragment, see the documentation of the function
4528 @code{org-inside-LaTeX-fragment-p}.}.  For example, @key{TAB} will
4529 expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
4530 correctly inside the first brace.  Another @key{TAB} will get you into
4531 the second brace.  Even outside fragments, @key{TAB} will expand
4532 environment abbreviations at the beginning of a line.  For example, if
4533 you write @samp{equ} at the beginning of a line and press @key{TAB},
4534 this abbreviation will be expanded to an @code{equation} environment.
4535 To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}.
4536 @item
4537 @kindex _
4538 @kindex ^
4539 Pressing @kbd{_} and @kbd{^} inside a LaTeX fragment will insert these
4540 characters together with a pair of braces.  If you use @key{TAB} to move
4541 out of the braces, and if the braces surround only a single character or
4542 macro, they are removed again (depending on the variable
4543 @code{cdlatex-simplify-sub-super-scripts}).
4544 @item
4545 @kindex `
4546 Pressing the backquote @kbd{`} followed by a character inserts math
4547 macros, also outside LaTeX fragments.  If you wait more than 1.5 seconds
4548 after the backquote, a help window will pop up.
4549 @item
4550 @kindex '
4551 Pressing the normal quote @kbd{'} followed by another character modifies
4552 the symbol before point with an accent or a font.  If you wait more than
4553 1.5 seconds after the backquote, a help window will pop up.  Character
4554 modification will work only inside La@TeX{} fragments, outside the quote
4555 is normal.
4556 @end itemize
4558 @node Exporting, Publishing, Embedded LaTeX, Top
4559 @chapter Exporting
4560 @cindex exporting
4562 Org-mode documents can be exported into a variety of other formats.  For
4563 printing and sharing of notes, ASCII export produces a readable and
4564 simple version of an Org-mode file.  HTML export allows you to publish a
4565 notes file on the web, while the XOXO format provides a solid base for
4566 exchange with a broad range of other applications.  To incorporate
4567 entries with associated times like deadlines or appointments into a
4568 desktop calendar program like iCal, Org-mode can also produce extracts
4569 in the iCalendar format.  Currently Org-mode only supports export, not
4570 import of these different formats.
4572 When exporting, Org-mode uses special conventions to enrich the output
4573 produced.  @xref{Text interpretation}, for more details.
4575 @table @kbd
4576 @kindex C-c C-e
4577 @item C-c C-e
4578 Dispatcher for export and publishing commands.  Displays a help-window
4579 listing the additional key(s) needed to launch an export or publishing
4580 command.
4581 @end table
4583 @menu
4584 * ASCII export::                Exporting to plain ASCII
4585 * HTML export::                 Exporting to HTML
4586 * XOXO export::                 Exporting to XOXO
4587 * iCalendar export::            Exporting in iCalendar format
4588 * Text interpretation::         How the exporter looks at the file
4589 @end menu
4591 @node ASCII export, HTML export, Exporting, Exporting
4592 @section ASCII export
4593 @cindex ASCII export
4595 ASCII export produces a simple and very readable version of an Org-mode
4596 file.
4598 @cindex region, active
4599 @cindex active region
4600 @cindex transient-mark-mode
4601 @table @kbd
4602 @kindex C-c C-e a
4603 @item C-c C-e a
4604 Export as ASCII file.  If there is an active region, only the region
4605 will be exported.  For an org file @file{myfile.org}, the ASCII file
4606 will be @file{myfile.txt}.  The file will be overwritten without
4607 warning.
4608 @kindex C-c C-e v a
4609 @item C-c C-e v a
4610 Export only the visible part of the document.
4611 @end table
4613 @cindex headline levels, for exporting
4614 In the exported version, the first 3 outline levels will become
4615 headlines, defining a general document structure.  Additional levels
4616 will be exported as itemized lists.  If you want that transition to occur
4617 at a different level, specify it with a prefix argument.  For example,
4619 @example
4620 @kbd{C-1 C-c C-e a}
4621 @end example
4623 @noindent
4624 creates only top level headlines and does the rest as items.  When
4625 headlines are converted to items, the indentation of the text following
4626 the headline is changed to fit nicely under the item.  This is done with
4627 the assumption that the first bodyline indicates the base indentation of
4628 the body text.  Any indentation larger than this is adjusted to preserve
4629 the layout relative to the first line.  Should there be lines with less
4630 indentation than the first, these are left alone.
4632 @node HTML export, XOXO export, ASCII export, Exporting
4633 @section HTML export
4634 @cindex HTML export
4636 Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
4637 HTML formatting, in ways similar to John Grubers @emph{markdown}
4638 language, but with additional support for tables.
4640 @menu
4641 * Export commands::             How to invode HTML export
4642 * Quoting HTML tags::           Using direct HTML in Org-mode
4643 * Links::                       How hyperlinks get transferred to HTML
4644 * Images::                      To inline or not to inline?
4645 * CSS support::                 Style specifications
4646 @end menu
4648 @node Export commands, Quoting HTML tags, HTML export, HTML export
4649 @subsection HTML export commands
4651 @cindex region, active
4652 @cindex active region
4653 @cindex transient-mark-mode
4654 @table @kbd
4655 @kindex C-c C-e h
4656 @item C-c C-e h
4657 Export as HTML file @file{myfile.html}.
4658 @kindex C-c C-e b
4659 @item C-c C-e b
4660 Export as HTML file and open it with a browser.
4661 @kindex C-c C-e v h
4662 @kindex C-c C-e v b
4663 @item C-c C-e v h
4664 @item C-c C-e v b
4665 Export only the visible part of the document.
4666 @end table
4668 @cindex headline levels, for exporting
4669 In the exported version, the first 3 outline levels will become
4670 headlines, defining a general document structure.  Additional levels
4671 will be exported as itemized lists.  If you want that transition to occur
4672 at a different level, specify it with a prefix argument.  For example,
4674 @example
4675 @kbd{C-2 C-c C-e b}
4676 @end example
4678 @noindent
4679 creates two levels of headings and does the rest as items.
4681 @node Quoting HTML tags, Links, Export commands, HTML export
4682 @subsection Quoting HTML tags
4684 If you want to include HTML tags which should be interpreted as such,
4685 mark them with @samp{@@} as in @samp{@@<b>bold text@@</b>}.
4686 Plain @samp{<} and @samp{>} are always transformed to @samp{&lt;} and
4687 @samp{&gt;} in HTML export.
4689 @node Links, Images, Quoting HTML tags, HTML export
4690 @subsection Links
4692 @cindex links, in HTML export
4693 @cindex internal links, in HTML export
4694 @cindex external links, in HTML export
4695 Internal links (@pxref{Internal links}) will continue to work in HTML
4696 files only if they match a dedicated @samp{<<target>>}.  Automatic links
4697 created by radio targets (@pxref{Radio targets}) will also work in the
4698 HTML file.  Links to external files will still work if the HTML file is
4699 in the same directory as the Org-mode file.  Links to other @file{.org}
4700 files will be translated into HTML links under the assumption that an
4701 HTML version also exists of the linked file.  For information related to
4702 linking files while publishing them to a publishing directory see
4703 @ref{Publishing links}.
4705 @node Images, CSS support, Links, HTML export
4706 @subsection Images
4708 @cindex images, inline in HTML
4709 @cindex inlining images in HTML
4710 HTML export can inline images given as links in the Org-mode file, and
4711 it can make an image the clickable part of a link.  By
4712 default@footnote{but see the variable
4713 @code{org-export-html-inline-images}}, images are inlined if a link does
4714 not have a description.  So @samp{[[file:myimg.jpg]]} will be inlined,
4715 while @samp{[[file:myimg.jpg][the image]]} will just produce a link
4716 @samp{the image} that points to the image.  If the description part
4717 itself is a @code{file:} link or a @code{http:} URL pointing to an
4718 image, this image will be inlined and activated so that clicking on the
4719 image will activate the link.  For example, to include a thumbnail that
4720 will link to a high resolution version of the image, you could use:
4722 @example
4723 [[file:highres.jpg][file:thumb.jpg]]
4724 @end example
4726 @noindent
4727 and you could use @code{http} addresses just as well.
4729 @node CSS support,  , Images, HTML export
4730 @subsection CSS support
4732 You can also give style information for the exported file.  The HTML
4733 exporter assigns the following CSS classes to appropriate parts of the
4734 document - your style specifications may change these:
4735 @example
4736 .todo           @r{TODO keywords}
4737 .done           @r{the DONE keyword}
4738 .timestamp      @r{time stamp}
4739 .timestamp-kwd  @r{keyword associated with a time stamp, like SCHEDULED}
4740 .tag            @r{tag in a headline}
4741 .target         @r{target for links}
4742 @end example
4744 The default style specification can be configured through the option
4745 @code{org-export-html-style}.  If you want to use a file-local style,
4746 you may use file variables, best wrapped into a COMMENT section at the
4747 end of the outline tree.  For example@footnote{Under Emacs 21, the
4748 continuation lines for a variable value should have no @samp{#} at the
4749 start of the line.}:
4751 @example
4752 * COMMENT html style specifications
4754 # Local Variables:
4755 # org-export-html-style: "   <style type=\"text/css\">
4756 #       p @{font-weight: normal; color: gray; @}
4757 #       h1 @{color: black; @}
4758 #   </style>"
4759 # End:
4760 @end example
4762 Remember to execute @kbd{M-x normal-mode} after changing this to make
4763 the new style visible to Emacs.  This command restarts org-mode for the
4764 current buffer and forces Emacs to re-evaluate the local variables
4765 section in the buffer.
4767 @c FIXME: More about header and footer styles
4768 @c FIXME: Talk about links and targets.
4770 @node XOXO export, iCalendar export, HTML export, Exporting
4771 @section XOXO export
4772 @cindex XOXO export
4774 Org-mode contains an exporter that produces XOXO-style output.
4775 Currently, this exporter only handles the general outline structure and
4776 does not interpret any additional Org-mode features.
4778 @table @kbd
4779 @kindex C-c C-e x
4780 @item C-c C-e x
4781 Export as XOXO file @file{myfile.html}.
4782 @kindex C-c C-e v
4783 @item C-c C-e v x
4784 Export only the visible part of the document.
4785 @end table
4787 @node iCalendar export, Text interpretation, XOXO export, Exporting
4788 @section iCalendar export
4789 @cindex iCalendar export
4791 Some people like to use Org-mode for keeping track of projects, but
4792 still prefer a standard calendar application for anniversaries and
4793 appointments.  In this case it can be useful to have deadlines and
4794 other time-stamped items in Org-mode files show up in the calendar
4795 application.  Org-mode can export calendar information in the standard
4796 iCalendar format.
4798 @table @kbd
4799 @kindex C-c C-e i
4800 @item C-c C-e i
4801 Create iCalendar entries for the current file and store them in the same
4802 directory, using a file extension @file{.ics}.
4803 @kindex C-c C-e I
4804 @item C-c C-e I
4805 Like @kbd{C-c C-e i}, but do this for all files in
4806 @code{org-agenda-files}.  For each of these files, a separate iCalendar
4807 file will be written.
4808 @kindex C-c C-e c
4809 @item C-c C-e c
4810 Create a single large iCalendar file from all files in
4811 @code{org-agenda-files} and write it to the file given by
4812 @code{org-combined-agenda-icalendar-file}.
4813 @end table
4815 How this calendar is best read and updated, depends on the application
4816 you are using.  For example, when using iCal under Apple MacOS X, you
4817 could create a new calendar @samp{OrgMode} (the default name for the
4818 calendar created by @kbd{C-c C-e c}, see the variables
4819 @code{org-icalendar-combined-name} and
4820 @code{org-combined-agenda-icalendar-file}).  Then set Org-mode to
4821 overwrite the corresponding file
4822 @file{~/Library/Calendars/OrgMode.ics}.  You may even use AppleScript
4823 to make iCal re-read the calendar files each time a new version of
4824 @file{OrgMode.ics} is produced.  Here is the setup needed for this:
4826 @cindex applescript, for calendar update
4827 @lisp
4828 (setq org-combined-agenda-icalendar-file
4829     "~/Library/Calendars/OrgMode.ics")
4830 (add-hook 'org-after-save-iCalendar-file-hook
4831  (lambda ()
4832   (shell-command
4833    "osascript -e 'tell application \"iCal\" to reload calendars'")))
4834 @end lisp
4836 @node Text interpretation,  , iCalendar export, Exporting
4837 @section Text interpretation by the exporter
4839 The exporter backends interpret additional structure in the Org-mode file
4840 in order to produce better output.
4842 @menu
4843 * Comment lines::               Some lines will not be exported
4844 * Enhancing text::              Subscripts, symbols and more
4845 * Export options::              How to influence the export settings
4846 @end menu
4848 @node Comment lines, Enhancing text, Text interpretation, Text interpretation
4849 @subsection Comment lines
4850 @cindex comment lines
4851 @cindex exporting, not
4853 Lines starting with @samp{#} in column zero are treated as comments
4854 and will never be exported.  Also entire subtrees starting with the
4855 word @samp{COMMENT} will never be exported.  Finally, any text before
4856 the first headline will not be exported either.
4858 @table @kbd
4859 @kindex C-c ;
4860 @item C-c ;
4861 Toggle the COMMENT keyword at the beginning of an entry.
4862 @end table
4864 @node Enhancing text, Export options, Comment lines, Text interpretation
4865 @subsection Enhancing text for export
4866 @cindex enhancing text
4867 @cindex richer text
4869 Some of the export backends of Org-mode allow for sophisticated text
4870 formatting, this is true in particular for the HTML backend.  Org-mode
4871 has a number of typing conventions that allow to produce a richly
4872 formatted output.
4874 @itemize @bullet
4876 @cindex hand-formatted lists
4877 @cindex lists, hand-formatted
4878 @item
4879 Plain lists @samp{-}, @samp{*} or @samp{+} as bullet, or with @samp{1.}
4880 or @samp{2)} as enumerator will be recognized and transformed if the
4881 backend supports lists.  See @xref{Plain lists}.
4883 @cindex underlined text
4884 @cindex bold text
4885 @cindex italic text
4886 @item
4887 You can make words @b{*bold*}, @i{/italic/}, _underlined_,
4888 @code{=code=}, and @samp{+strikethrough+}.
4890 @cindex LaTeX fragments, export
4891 @cindex TeX macros, export
4892 @item
4893 Many @TeX{} macros and entire La@TeX{} fragments are converted into HTML
4894 entities or images (@pxref{Embedded LaTeX}).
4896 @cindex tables, export
4897 @item
4898 Tables are transformed into native tables under the exporter, if the
4899 export backend supports this. Data fields before the first horizontal
4900 separator line will be formatted as table header fields.
4902 @cindex fixed width
4903 @item
4904 If a headline starts with the word @samp{QUOTE}, the text below the
4905 headline will be typeset as fixed-width, to allow quoting of computer
4906 codes etc.  Lines starting with @samp{:} are also typeset in
4907 fixed-width font.
4908 @table @kbd
4909 @kindex C-c :
4910 @item C-c :
4911 Toggle fixed-width for entry (QUOTE) or region, see below.
4912 @end table
4914 @cindex linebreak, forced
4915 @item 
4916 A double backslash @emph{at the end of a line} enforces a line break at
4917 this position.
4918 @end itemize
4920 If these conversions conflict with your habits of typing ASCII text,
4921 they can all be turned off with corresponding variables (see the
4922 customization group @code{org-export-general}, and the following section
4923 which explains how to set export options with special lines in a
4924 buffer.
4927 @node Export options,  , Enhancing text, Text interpretation
4928 @subsection Export options
4929 @cindex options, for export
4931 @cindex completion, of option keywords
4932 The exporter recognizes special lines in the buffer which provide
4933 additional information.  These lines may be put anywhere in the file.
4934 The whole set of lines can be inserted into the buffer with @kbd{C-c
4935 C-e t}.  For individual lines, a good way to make sure the keyword is
4936 correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion
4937 (@pxref{Completion}).
4939 @table @kbd
4940 @kindex C-c C-e t
4941 @item C-c C-e t
4942 Insert template with export options, see example below.
4943 @end table
4945 @example
4946 #+TITLE:     the title to be shown (default is the buffer name)
4947 #+AUTHOR:    the author (default taken from @code{user-full-name})
4948 #+EMAIL:     his/her email address (default from @code{user-mail-address})
4949 #+LANGUAGE:  language for HTML, e.g. @samp{en} (@code{org-export-default-language})
4950 #+TEXT:      Some descriptive text to be inserted at the beginning.
4951 #+TEXT:      Several lines may be given.
4952 #+OPTIONS:   H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t *:nil TeX:t LaTeX:t
4953 @end example
4955 @noindent
4956 The OPTIONS line is a compact form to specify export settings.  Here
4957 you can:
4958 @cindex headline levels
4959 @cindex section-numbers
4960 @cindex table of contents
4961 @cindex linebreak preservation
4962 @cindex quoted HTML tags
4963 @cindex fixed-width sections
4964 @cindex tables
4965 @cindex @TeX{}-like syntax for sub- and superscripts
4966 @cindex emphasized text
4967 @cindex @TeX{} macros
4968 @cindex La@TeX{} fragments
4969 @example
4970 H:      @r{set the number of headline levels for export}
4971 num:    @r{turn on/off section-numbers}
4972 toc:    @r{turn on/off table of contents}
4973 \n:     @r{turn on/off linebreak-preservation}
4974 @@:      @r{turn on/off quoted HTML tags}
4975 ::      @r{turn on/off fixed-width sections}
4976 |:      @r{turn on/off tables}
4977 ^:      @r{turn on/off @TeX{}-like syntax for sub- and superscripts.}
4978 *:      @r{turn on/off emphasized text (bold, italic, underlined)}
4979 TeX:    @r{turn on/off simple @TeX{} macros in plain text}
4980 LaTeX:  @r{turn on/off La@TeX{} fragments}
4981 @end example
4983 @node Publishing, Miscellaneous, Exporting, Top
4984 @chapter Publishing
4985 @cindex publishing
4987 Org-mode includes@footnote{@file{org-publish.el} is not yet part of
4988 Emacs, so if you are using @file{org.el} as it comes with Emacs, you
4989 need to download this file separately.  Also make sure org.el is at
4990 least version 4.27.} a publishing management system
4991 that allows you to configure automatic HTML conversion of
4992 @emph{projects} composed of interlinked org files.  This system is
4993 called @emph{org-publish}.  You can also configure org-publish to
4994 automatically upload your exported HTML pages and related attachments,
4995 such as images and source code files, to a web server.  Org-publish turns
4996 org-mode into a web-site authoring tool.
4998 Org-publish has been contributed to Org-mode by David O'Toole.
5000 @menu
5001 * Configuration::               Defining projects
5002 * Sample configuration::        Example projects
5003 * Triggering publication::      Publication commands
5004 @end menu
5006 @node Configuration, Sample configuration, Publishing, Publishing
5007 @section Configuration
5009 Publishing needs significant configuration to specify files, destination
5010 and many other properties of a project.
5012 @menu
5013 * Project alist::               The central configuration variable
5014 * Sources and destinations::    From here to there
5015 * Selecting files::             What files are part of the project?
5016 * Publishing action::           Setting the function doing the publishing
5017 * Publishing options::          Tweaking HTML export
5018 * Publishing links::            Which links keep working after publishing?
5019 * Project page index::          Publishing a list of project files
5020 @end menu
5022 @node Project alist, Sources and destinations, Configuration, Configuration
5023 @subsection The variable @code{org-publish-project-alist}
5024 @cindex org-publish-project-alist
5025 @cindex projects, for publishing
5027 Org-publish is configured almost entirely through setting the value of
5028 one variable, called @code{org-publish-project-alist}.
5029 Each element of the list configures one project, and may be in one of
5030 the two following forms:
5032 @lisp
5033 ("project-name"  :property value :property value ...)
5035 @r{or} 
5037 ("project-name"  :components ("project-name" "project-name" ...))
5039 @end lisp
5041 In both cases, projects are configured by specifying property values.
5042 A project defines the set of files that will be published, as well as
5043 the publishing configuration to use when publishing those files.  When
5044 a project takes the second form listed above, the individual members
5045 of the ``components'' property are taken to be components of the
5046 project, which group together files requiring different publishing
5047 options. When you publish such a ``meta-project'' all the components
5048 will also publish.
5050 @node Sources and destinations, Selecting files, Project alist, Configuration
5051 @subsection Sources and destinations for files
5052 @cindex directories, for publishing
5054 Most properties are optional, but some should always be set. In
5055 particular, org-publish needs to know where to look for source files,
5056 and where to put published files.
5058 @multitable @columnfractions 0.3 0.7
5059 @item @code{:base-directory}
5060 @tab Directory containing publishing source files
5061 @item @code{:publishing-directory}
5062 @tab Directory (possibly remote) where output files will be published.
5063 @item @code{:preparation-function}
5064 @tab Function called before starting publishing process, for example to
5065 run @code{make} for updating files to be published.
5066 @end multitable
5067 @noindent
5069 @node Selecting files, Publishing action, Sources and destinations, Configuration
5070 @subsection Selecting files
5071 @cindex files, selecting for publishing
5073 By default, all files with extension @file{.org} in the base directory
5074 are considered part of the project.  This can be modified by setting the
5075 properties 
5076 @multitable @columnfractions 0.25 0.75
5077 @item @code{:base-extension}
5078 @tab Extension (without the dot!) of source files.  This actually is a
5079 regular expression.
5081 @item @code{:exclude} 
5082 @tab Regular expression to match file names that should not be
5083 published, even though they have been selected on the basis of their
5084 extension.
5086 @item @code{:include}
5087 @tab List of files to be included regardless of @code{:base-extension}
5088 and @code{:exclude}.
5089 @end multitable
5091 @node Publishing action, Publishing options, Selecting files, Configuration
5092 @subsection Publishing Action
5093 @cindex action, for publishing
5095 Publishing means that a file is copied to the destination directory and
5096 possibly transformed in the process.  The default transformation is to
5097 export Org-mode files as HTML files, and this is done by the function
5098 @code{org-publish-org-to-html} which calls the HTML exporter
5099 (@pxref{HTML export}).  Other files like images only need to be copied
5100 to the publishing destination.  For non-Org-mode files, you need to
5101 specify the publishing function.
5103 @multitable @columnfractions 0.3 0.7
5104 @item @code{:publishing-function}
5105 @tab Function executing the publication of a file.  This may also be a
5106 list of functions, which will all be called in turn.
5107 @end multitable
5109 The function must accept two arguments: a property list containing at
5110 least a @code{:publishing-directory} property, and the name of the file
5111 to be published.  It should take the specified file, make the necessary
5112 transformation (if any) and place the result into the destination folder.
5113 You can write your own publishing function, but @code{org-publish}
5114 provides one for attachments (files that only need to be copied):
5115 @code{org-publish-attachment}.
5117 @node Publishing options, Publishing links, Publishing action, Configuration
5118 @subsection Options for the HTML exporter
5119 @cindex options, for publishing
5121 The property list can be used to set many export options for the HTML
5122 exporter.  In most cases, these properties correspond to user variables
5123 in Org-mode.  The table below lists these properties along with the
5124 variable they belong to.  See the documentation string for the
5125 respective variable for details.
5127 @multitable @columnfractions 0.3 0.7
5128 @item @code{:language}              @tab @code{org-export-default-language}
5129 @item @code{:headline-levels}       @tab @code{org-export-headline-levels}
5130 @item @code{:section-numbers}       @tab @code{org-export-with-section-numbers}
5131 @item @code{:table-of-contents}     @tab @code{org-export-with-toc}
5132 @item @code{:archived-trees}        @tab @code{org-export-with-archived-trees}
5133 @item @code{:emphasize}             @tab @code{org-export-with-emphasize}
5134 @item @code{:sub-superscript}       @tab @code{org-export-with-sub-superscripts}
5135 @item @code{:TeX-macros}            @tab @code{org-export-with-TeX-macros}
5136 @item @code{:LaTeX-fragments}       @tab @code{org-export-with-LaTeX-fragments}
5137 @item @code{:fixed-width}           @tab @code{org-export-with-fixed-width}
5138 @item @code{:timestamps}           .@tab @code{org-export-with-timestamps}
5139 @item @code{:tags}                 .@tab @code{org-export-with-tags}
5140 @item @code{:tables}                @tab @code{org-export-with-tables}
5141 @item @code{:table-auto-headline}   @tab @code{org-export-highlight-first-table-line}
5142 @item @code{:style}                 @tab @code{org-export-html-style}
5143 @item @code{:convert-org-links}     @tab @code{org-export-html-link-org-files-as-html}
5144 @item @code{:inline-images}         @tab @code{org-export-html-inline-images}
5145 @item @code{:expand-quoted-html}    @tab @code{org-export-html-expand}
5146 @item @code{:timestamp}             @tab @code{org-export-html-with-timestamp}
5147 @item @code{:publishing-directory}  @tab @code{org-export-publishing-directory}
5148 @item @code{:preamble}              @tab @code{org-export-html-preamble}
5149 @item @code{:postamble}             @tab @code{org-export-html-postamble}
5150 @item @code{:auto-preamble}         @tab @code{org-export-html-auto-preamble}
5151 @item @code{:auto-postamble}        @tab @code{org-export-html-auto-postamble}
5152 @item @code{:author}                @tab @code{user-full-name}
5153 @item @code{:email}                 @tab @code{user-mail-address}
5154 @end multitable
5156 When a property is given a value in org-publish-project-alist, its
5157 setting overrides the value of the corresponding user variable (if any)
5158 during publishing.  options set within a file (@pxref{Export
5159 options}), however, override everything.
5161 @node Publishing links, Project page index, Publishing options, Configuration
5162 @subsection Links between published files
5163 @cindex links, publishing
5165 To create a link from one Org-mode file to another, you would use
5166 something like @samp{[[file:foo.org][The foo]]} or simply
5167 @samp{file:foo.org.} (@pxref{Hyperlinks}).  Upon publishing this link
5168 becomes a link to @file{foo.html}.  In this way, you can interlink the
5169 pages of your "org web" project and the links will work as expected when
5170 you publish them to HTML.
5172 You may also link to related files, such as images. Provided you are
5173 careful with relative pathnames, and provided you have also configured
5174 org-publish to upload the related files, these links will work
5175 too. @ref{Complex example} for an example of this usage.
5177 Sometime an Org-mode file to be published may contain links that are
5178 only valid in your production environment, but not in the publishing
5179 location.  In this case, use the property 
5181 @multitable @columnfractions 0.4 0.6
5182 @item @code{:link-validation-function}
5183 @tab Function to validate links
5184 @end multitable
5186 @noindent
5187 to define a function for checking link validity.  This function must
5188 accept two arguments, the file name and a directory relative to which
5189 the file name is interpreted in the production environment.  If this
5190 function returns @code{nil}, then the HTML generator will only insert a
5191 description into the HTML file, but no link.  One option for this
5192 function is @code{org-publish-validate-link} which checks if the given
5193 file is part of any project in @code{org-publish-project-alist}.
5195 @node Project page index,  , Publishing links, Configuration
5196 @subsection Project page index
5197 @cindex index, of published pages
5199 The following properties may be used to control publishing of an
5200 index of files or summary page for a given project.
5202 @multitable @columnfractions 0.25 0.75
5203 @item @code{:auto-index}
5204 @tab When non-nil, publish an index during org-publish-current-project or
5205 org-publish-all.
5207 @item @code{:index-filename}
5208 @tab Filename for output of index. Defaults to @file{index.org} (which
5209 becomes @file{index.html}).
5211 @item @code{:index-title}
5212 @tab Title of index page. Defaults to name of file.
5214 @item @code{:index-function}
5215 @tab Plugin function to use for generation of index.
5216 Defaults to @code{org-publish-org-index}, which generates a plain list
5217 of links to all files in the project.
5218 @end multitable
5220 @node Sample configuration, Triggering publication, Configuration, Publishing
5221 @section Sample configuration
5223 Below we provide two example configurations.  The first one is a simple
5224 project publishing only a set of Org-mode files.  The second example is
5225 more complex, with a multi-component project.
5227 @menu
5228 * Simple example::              One-component publishing
5229 * Complex example::             A multi-component publishing example
5230 @end menu
5232 @node Simple example, Complex example, Sample configuration, Sample configuration
5233 @subsection Example: simple publishing configuration
5235 This example publishes a set of Org-mode files to the @file{public_html}
5236 directory on the local machine.
5238 @lisp
5239 (setq org-publish-project-alist
5240       '(("org" 
5241          :base-directory "~/org/"
5242          :publishing-directory "~/public_html"
5243          :section-numbers nil
5244          :table-of-contents nil
5245          :style "<link rel=stylesheet 
5246                 href=\"../other/mystyle.css\"
5247                 type=\"text/css\">")))
5248 @end lisp
5250 @node Complex example,  , Simple example, Sample configuration
5251 @subsection Example: complex publishing configuration
5253 This more complicated example publishes an entire website, including
5254 org files converted to HTML, image files, emacs lisp source code, and
5255 stylesheets. The publishing-directory is remote and private files are
5256 excluded.
5258 To ensure that links are preserved, care should be taken to replicate
5259 your directory structure on the web server, and to use relative file
5260 paths. For example, if your org files are kept in @file{~/org} and your
5261 publishable images in @file{~/images}, you'd link to an image with
5263 @example
5264 file:../images/myimage.png
5265 @end example
5267 On the web server, the relative path to the image should be the
5268 same. You can accomplish this by setting up an "images" folder in the
5269 right place on the webserver, and publishing images to it.
5271 @lisp
5272 (setq org-publish-project-alist
5273       '(("orgfiles"
5274           :base-directory "~/org/"
5275           :base-extension "org"
5276           :publishing-directory "/ssh:user@@host:~/html/notebook/"
5277           :publishing-function org-publish-org-to-html
5278           :exclude "PrivatePage.org"   ;; regexp
5279           :headline-levels 3
5280           :section-numbers nil
5281           :table-of-contents nil
5282           :style "<link rel=stylesheet 
5283                   href=\"../other/mystyle.css\" type=\"text/css\">"
5284           :auto-preamble t
5285           :auto-postamble nil)
5286          
5287          ("images"
5288           :base-directory "~/images/"
5289           :base-extension "jpg\\|gif\\|png"
5290           :publishing-directory "/ssh:user@@host:~/html/images/"
5291           :publishing-function org-publish-attachment)
5293          ("other"
5294           :base-directory "~/other/"
5295           :base-extension "css\\|el"
5296           :publishing-directory "/ssh:user@@host:~/html/other/"
5297           :publishing-function org-publish-attachment)
5298          ("website" :components ("orgfiles" "images" "other"))))
5299 @end lisp
5301 @node Triggering publication,  , Sample configuration, Publishing
5302 @section Triggering publication
5304 Once org-publish is properly configured, you can publish with the
5305 following functions: 
5307 @table @kbd
5308 @item C-c C-e c
5309 Prompt for a specific project and publish all files that belong to it.
5310 @item C-c C-e p
5311 Publish the project containing the current file.
5312 @item C-c C-e f
5313 Publish only the current file.
5314 @item C-c C-e a
5315 Publish all projects.
5316 @end table
5318 Org uses timestamps to track when a file has changed. The above
5319 functions normally only publish changed files. You can override this and
5320 force publishing of all files by giving a prefix argument.
5322 @node Miscellaneous, Extensions and Hacking, Publishing, Top
5323 @chapter Miscellaneous
5325 @menu
5326 * Completion::                  M-TAB knows what you need
5327 * Customization::               Adapting Org-mode to your taste
5328 * In-buffer settings::          Overview of the #+KEYWORDS
5329 * The very busy C-c C-c key::   When in doubt, press C-c C-c
5330 * Clean view::                  Getting rid of leading stars in the outline
5331 * TTY keys::                    Using Org-mode on a tty
5332 * Interaction::                 Other Emacs packages
5333 * Bugs::                        Things which do not work perfectly
5334 @end menu
5336 @node Completion, Customization, Miscellaneous, Miscellaneous
5337 @section Completion
5338 @cindex completion, of @TeX{} symbols
5339 @cindex completion, of TODO keywords
5340 @cindex completion, of dictionary words
5341 @cindex completion, of option keywords
5342 @cindex completion, of CamelCase links
5343 @cindex completion, of tags
5344 @cindex completion, of link abbreviations
5345 @cindex @TeX{} symbol completion
5346 @cindex TODO keywords completion
5347 @cindex dictionary word completion
5348 @cindex option keyword completion
5349 @cindex CamelCase link completion
5350 @cindex tag completion
5351 @cindex link abbreviations, completion of
5353 Org-mode supports in-buffer completion.  This type of completion does
5354 not make use of the minibuffer.  You simply type a few letters into
5355 the buffer and use the key to complete text right there.
5357 @table @kbd
5358 @kindex M-@key{TAB}
5359 @item M-@key{TAB}
5360 Complete word at point
5361 @itemize @bullet
5362 @item
5363 At the beginning of a headline, complete TODO keywords.
5364 @item
5365 After @samp{\}, complete @TeX{} symbols supported by the exporter.
5366 @item
5367 After @samp{*}, complete headlines in the current buffer so that they
5368 can be used in search links like @samp{[[*find this headline]]}.
5369 @item
5370 After @samp{:}, complete tags.  The list of tags is taken from the
5371 variable @code{org-tag-alist} (possibly set through the @samp{#+TAGS}
5372 in-buffer option, @pxref{Setting tags}), or it is created dynamically
5373 from all tags used in the current buffer.
5374 @item
5375 After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}).
5376 @item
5377 After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
5378 @samp{OPTIONS} which set file-specific options for Org-mode.  When the
5379 option keyword is already complete, pressing @kbd{M-@key{TAB}} again
5380 will insert example settings for this keyword.
5381 @item
5382 In the line after @samp{#+STARTUP: }, complete startup keywords,
5383 i.e. valid keys for this line.
5384 @item
5385 Elsewhere, complete dictionary words using ispell.
5386 @end itemize
5387 @end table
5389 @node Customization, In-buffer settings, Completion, Miscellaneous
5390 @section Customization
5391 @cindex customization
5392 @cindex options, for customization
5393 @cindex variables, for customization
5395 There are more than 170 variables that can be used to customize
5396 Org-mode.  For the sake of compactness of the manual, I am not
5397 describing the variables here.  A structured overview of customization
5398 variables is available with @kbd{M-x org-customize}.  Or select
5399 @code{Browse Org Group} from the @code{Org->Customization} menu.  Many
5400 settings can also be activated on a per-file basis, by putting special
5401 lines into the buffer (@pxref{In-buffer settings}).
5403 @node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous
5404 @section Summary of in-buffer settings
5405 @cindex in-buffer settings
5406 @cindex special keywords
5408 Org-mode uses special lines in the buffer to define settings on a
5409 per-file basis.  These lines start with a @samp{#+} followed by a
5410 keyword, a colon, and then individual words defining a setting.  Several
5411 setting words can be in the same line, but you can also have multiple
5412 lines for the keyword.  While these settings are described throughout
5413 the manual, here is a summary.  After changing any of those lines in the
5414 buffer, press @kbd{C-c C-c} with the cursor still in the line to
5415 activate the changes immediately.  Otherwise they become effective only
5416 when the file is visited again in a new Emacs session.
5418 @table @kbd
5419 @item #+STARTUP:
5420 This line sets options to be used at startup of org-mode, when an
5421 Org-mode file is being visited.  The first set of options deals with the
5422 initial visibility of the outline tree.  The corresponding variable for
5423 global default settings is @code{org-startup-folded}, with a default
5424 value @code{t}, which means @code{overview}.
5425 @cindex @code{overview}, STARTUP keyword
5426 @cindex @code{content}, STARTUP keyword
5427 @cindex @code{showall}, STARTUP keyword
5428 @example
5429 overview   @r{top-level headlines only}
5430 content    @r{all headlines}
5431 showall    @r{no folding at all, show everything}
5432 @end example
5433 Then there are options for aligning tables upon visiting a file.  This
5434 is useful in files containing narrowed table columns.  The corresponding
5435 variable is @code{org-startup-align-all-tables}, with a default value
5436 @code{nil}. 
5437 @cindex @code{align}, STARTUP keyword
5438 @cindex @code{noalign}, STARTUP keyword
5439 @example
5440 align      @r{align all tables}
5441 noalign    @r{don't align tables on startup}
5442 @end example
5443 Logging TODO state changes and clock intervals (variable
5444 @code{org-log-done}) can be configured using these options.
5445 @cindex @code{logdone}, STARTUP keyword
5446 @cindex @code{nologging}, STARTUP keyword
5447 @cindex @code{lognotedone}, STARTUP keyword
5448 @cindex @code{lognoteclock-out}, STARTUP keyword
5449 @cindex @code{lognotestate}, STARTUP keyword
5450 @example
5451 logging          @r{record a timestamp when an item is marked DONE}
5452 nologging        @r{don't record when items are marked DONE}
5453 lognotedone      @r{record timestamp and a note when DONE}
5454 lognotestate     @r{record timestamp, note when TODO state changes}
5455 lognoteclock-out @r{record timestamp and a note when clocking out}
5456 @end example
5457 Here are the options for hiding leading stars in outline headings.  The
5458 corresponding variables are @code{org-hide-leading-stars} and
5459 @code{org-odd-levels-only}, both with a default setting @code{nil}
5460 (meaning @code{showstars} and @code{oddeven}).
5461 @cindex @code{hidestars}, STARTUP keyword
5462 @cindex @code{showstars}, STARTUP keyword
5463 @cindex @code{odd}, STARTUP keyword
5464 @cindex @code{even}, STARTUP keyword
5465 @example
5466 hidestars  @r{make all but one of the stars starting a headline invisible.}
5467 showstars  @r{show all stars starting a headline}
5468 odd        @r{allow only odd outline levels (1,3,...)}
5469 oddeven    @r{allow all outline levels}
5470 @end example
5471 To turn on custom format overlays over time stamps (variables
5472 @code{org-put-time-stamp-overlays} and
5473 @code{org-time-stamp-overlay-formats}), use
5474 @cindex @code{customtime}, STARTUP keyword
5475 @example
5476 customtime @r{overlay custom time format}
5477 @end example
5478 @item #+SEQ_TODO:   #+TYP_TODO:
5479 These lines set the TODO keywords and their interpretation in the
5480 current file.  The corresponding variables are @code{org-todo-keywords}
5481 and @code{org-todo-interpretation}.
5482 @item #+TAGS:  TAG1(c1) TAG2(c2)
5483 These lines (several such lines are allowed) specify the legal tags in
5484 this file, and (potentially) the corresponding @emph{fast tag selection}
5485 keys.  The corresponding variable is @code{org-tag-alist}.
5486 @item #+LINK:  linkword replace
5487 These lines (several are allowed) specify link abbreviations.
5488 @xref{Link abbreviations}.  The corresponding variable is
5489 @code{org-link-abbrev-alist}.
5490 @item #+CATEGORY:
5491 This line sets the category for the agenda file.  The category applies
5492 for all subsequent lines until the next @samp{#+CATEGORY} line, or the
5493 end of the file.  The first such line also applies to any entries before it.
5494 @item #+ARCHIVE: %s_done::
5495 This line sets the archive location for the agenda file.  It applies for
5496 all subsequent lines until the next @samp{#+CATEGORY} line, or the end
5497 of the file.  The first such line also applies to any entries before it.
5498 The corresponding variable is @code{org-archive-location}.
5499 @item #+TBLFM:
5500 This line contains the formulas for the table directly above the line.
5501 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS:
5502 These lines provide settings for exporting files.  For more details see
5503 @ref{Export options}.
5504 @end table
5506 @node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous
5507 @section The very busy C-c C-c key
5508 @kindex C-c C-c
5509 @cindex C-c C-c, overview
5511 The key @kbd{C-c C-c} has many purposes in org-mode, which are all
5512 mentioned scattered throughout this manual.  One specific function of
5513 this key is to add @emph{tags} to a headline (@pxref{Tags}).  In many
5514 other circumstances it means something like @emph{Hey Org-mode, look
5515 here and update according to what you see here}.  Here is a summary of
5516 what this means in different contexts.
5518 @itemize @minus
5519 @item
5520 If there are highlights in the buffer from the creation of a sparse
5521 tree, or from clock display, remove these highlights.
5522 @item
5523 If the cursor is in one of the special @code{#+KEYWORD} lines, this
5524 triggers scanning the buffer for these lines and updating the
5525 information. 
5526 @item
5527 If the cursor is inside a table, realign the table.  This command
5528 works even if the automatic table editor has been turned off.
5529 @item
5530 If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
5531 the entire table.
5532 @item
5533 If the cursor is inside a table created by the @file{table.el} package,
5534 activate that table.
5535 @item
5536 If the current buffer is a remember buffer, close the note and file it.
5537 With a prefix argument, file it, without further interaction, to the
5538 default location.
5539 @item
5540 If the cursor is on a @code{<<<target>>>}, update radio targets and
5541 corresponding links in this buffer.
5542 @item
5543 If the cursor is in a plain list item with a checkbox, toggle the status
5544 of the checkbox.
5545 @item
5546 If the cursor is on a numbered item in a plain list, renumber the
5547 ordered list.
5548 @end itemize
5550 @node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
5551 @section A cleaner outline view
5552 @cindex hiding leading stars
5553 @cindex clean outline view
5555 Some people find it noisy and distracting that the Org-mode headlines
5556 are starting with a potentially large number of stars.  For example
5557 the tree from @ref{Headlines}:
5559 @example
5560 * Top level headline
5561 ** Second level
5562 *** 3rd level
5563     some text
5564 *** 3rd level
5565     more text
5566 * Another top level headline
5567 @end example
5569 @noindent
5570 Unfortunately this is deeply ingrained into the code of Org-mode and
5571 cannot be easily changed.  You can, however, modify the display in such
5572 a way that all leading stars become invisible and the outline more easy
5573 to read.  To do this, customize the variable
5574 @code{org-hide-leading-stars} like this:
5576 @lisp
5577 (setq org-hide-leading-stars t)
5578 @end lisp
5580 @noindent
5581 or change this on a per-file basis with one of the lines (anywhere in
5582 the buffer)
5584 @example
5585 #+STARTUP: showstars
5586 #+STARTUP: hidestars
5587 @end example
5589 @noindent
5590 Press @kbd{C-c C-c} with the cursor in a @samp{STARTUP} line to activate
5591 the modifications.
5593 With stars hidden, the tree becomes:
5595 @example
5596 * Top level headline
5597  * Second level
5598   * 3rd level
5599     some text
5600   * 3rd level
5601     more text
5602 * Another top level headline
5603 @end example
5605 @noindent
5606 Note that the leading stars are not truly replaced by whitespace, they
5607 are only fontified with the face @code{org-hide} that uses the
5608 background color as font color.  If you are not using either white or
5609 black background, you may have to customize this face to get the wanted
5610 effect.  Another possibility is to set this font such that the extra
5611 stars are @i{almost} invisible, for example using the color
5612 @code{grey90} on a white background.
5614 Things become cleaner still if you skip all the even levels and use only
5615 odd levels 1, 3, 5..., effectively adding two stars to go from one
5616 outline level to the next:
5618 @example
5619 * Top level headline
5620   * Second level
5621     * 3rd level
5622       some text
5623     * 3rd level
5624       more text
5625 * Another top level headline
5626 @end example
5628 @noindent
5629 In order to make the structure editing and export commands handle this
5630 convention correctly, use
5632 @lisp
5633 (setq org-odd-levels-only t)
5634 @end lisp
5636 @noindent
5637 or set this on a per-file basis with one of the following lines (don't
5638 forget to press @kbd{C-c C-c} with the cursor in the startup line to
5639 activate changes immediately).
5641 @example
5642 #+STARTUP: odd
5643 #+STARTUP: oddeven
5644 @end example
5646 You can convert an Org-mode file from single-star-per-level to the
5647 double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels
5648 RET} in that file.  The reverse operation is @kbd{M-x
5649 org-convert-to-oddeven-levels}.
5651 @node TTY keys, Interaction, Clean view, Miscellaneous
5652 @section Using org-mode on a tty
5653 @cindex tty keybindings
5655 Org-mode uses a number of keys that are not accessible on a tty.  This
5656 applies to most special keys like cursor keys, @key{TAB} and
5657 @key{RET}, when these are combined with modifier keys like @key{Meta}
5658 and/or @key{Shift}.  Org-mode uses these bindings because it needs to
5659 provide keys for a large number of commands, and because these keys
5660 appeared particularly easy to remember.  In order to still be able to
5661 access the core functionality of Org-mode on a tty, alternative
5662 bindings are provided.  Here is a complete list of these bindings,
5663 which are obviously more cumbersome to use.  Note that sometimes a
5664 work-around can be better.  For example changing a time stamp is
5665 really only fun with @kbd{S-@key{cursor}} keys.  On a tty you would
5666 rather use @kbd{C-c .}  to re-insert the timestamp.
5668 @multitable @columnfractions 0.15 0.2 0.2
5669 @item @b{Default} @tab @b{Alternative 1} @tab @b{Alternative 2}
5670 @item @kbd{S-@key{TAB}}     @tab @kbd{C-u @key{TAB}}       @tab
5671 @item @kbd{M-@key{left}}    @tab @kbd{C-c C-x l}           @tab @kbd{@key{Esc} @key{left}}
5672 @item @kbd{M-S-@key{left}}  @tab @kbd{C-c C-x L}           @tab
5673 @item @kbd{M-@key{right}}   @tab @kbd{C-c C-x r}           @tab @kbd{@key{Esc} @key{right}}
5674 @item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R}           @tab
5675 @item @kbd{M-@key{up}}      @tab @kbd{C-c C-x u}           @tab @kbd{@key{Esc} @key{up}}
5676 @item @kbd{M-S-@key{up}}    @tab @kbd{C-c C-x U}           @tab
5677 @item @kbd{M-@key{down}}    @tab @kbd{C-c C-x d}           @tab @kbd{@key{Esc} @key{down}}
5678 @item @kbd{M-S-@key{down}}  @tab @kbd{C-c C-x D}           @tab
5679 @item @kbd{S-@key{RET}}     @tab @kbd{C-c C-x c}           @tab
5680 @item @kbd{M-@key{RET}}     @tab @kbd{C-c C-x m}           @tab @kbd{@key{Esc} @key{RET}}
5681 @item @kbd{M-S-@key{RET}}   @tab @kbd{C-c C-x M}           @tab
5682 @item @kbd{S-@key{left}}    @tab @kbd{C-c C-x @key{left}}  @tab
5683 @item @kbd{S-@key{right}}   @tab @kbd{C-c C-x @key{right}} @tab
5684 @item @kbd{S-@key{up}}      @tab @kbd{C-c C-x @key{up}}    @tab
5685 @item @kbd{S-@key{down}}    @tab @kbd{C-c C-x @key{down}}  @tab
5686 @end multitable
5688 @node Interaction, Bugs, TTY keys, Miscellaneous
5689 @section Interaction with other packages
5690 @cindex packages, interaction with other
5691 Org-mode lives in the world of GNU Emacs and interacts in various ways
5692 with other code out there.
5694 @menu
5695 * Cooperation::                 Packages Org-mode cooperates with
5696 * Conflicts::                   Packages that lead to conflicts
5697 @end menu
5699 @node Cooperation, Conflicts, Interaction, Interaction
5700 @subsection Packages that Org-mode cooperates with
5702 @table @asis
5703 @cindex @file{calc.el}
5704 @item @file{calc.el} by Dave Gillespie
5705 Org-mode uses the calc package for implementing spreadsheet
5706 functionality in its tables (@pxref{The spreadsheet}).  Org-modes
5707 checks for the availability of calc by looking for the function
5708 @code{calc-eval} which should be autoloaded in your setup if calc has
5709 been installed properly.  As of Emacs 22, calc is part of the Emacs
5710 distribution.  Another possibility for interaction between the two
5711 packages is using calc for embedded calculations. @xref{Embedded Mode,
5712 , Embedded Mode, calc, GNU Emacs Calc Manual}.
5713 @cindex @file{constants.el}
5714 @item @file{constants.el} by Carsten Dominik
5715 In a table formula (@pxref{The spreadsheet}), it is possible to use
5716 names for natural constants or units.  Instead of defining your own
5717 constants in the variable @code{org-table-formula-constants}, install
5718 the @file{constants} package which defines a large number of constants
5719 and units, and lets you use unit prefixes like @samp{M} for
5720 @samp{Mega} etc.  You will need version 2.0 of this package, available
5721 at @url{http://www.astro.uva.nl/~dominik/Tools}. Org-mode checks for
5722 the function @code{constants-get}, which has to be autoloaded in your
5723 setup.  See the installation instructions in the file
5724 @file{constants.el}.
5725 @item @file{cdlatex.el} by Carsten Dominik
5726 @cindex @file{cdlatex.el}
5727 Org-mode can make use of the cdlatex package to efficiently enter
5728 La@TeX{} fragments into Org-mode files. See @ref{CDLaTeX mode}.
5729 @item @file{remember.el} by John Wiegley
5730 @cindex @file{remember.el}
5731 Org mode cooperates with remember, see @ref{Remember}.
5732 @file{Remember.el} is not part of Emacs, find it on the web.
5733 @cindex @file{table.el}
5734 @item @file{table.el} by Takaaki Ota
5735 @kindex C-c C-c
5736 @cindex table editor, @file{table.el}
5737 @cindex @file{table.el}
5739 Complex ASCII tables with automatic line wrapping, column- and
5740 row-spanning, and alignment can be created using the Emacs table
5741 package by Takaaki Ota (@uref{http://sourceforge.net/projects/table},
5742 and also part of Emacs 22).
5743 When @key{TAB} or @kbd{C-c C-c} is pressed in such a table, Org-mode
5744 will call @command{table-recognize-table} and move the cursor into the
5745 table.  Inside a table, the keymap of Org-mode is inactive.  In order
5746 to execute Org-mode-related commands, leave the table.
5748 @table @kbd
5749 @kindex C-c C-c
5750 @item C-c C-c
5751 Recognize @file{table.el} table.  Works when the cursor is in a
5752 table.el table.
5754 @kindex C-c ~
5755 @item C-c ~
5756 Insert a table.el table.  If there is already a table at point, this
5757 command converts it between the table.el format and the Org-mode
5758 format.  See the documentation string of the command
5759 @code{org-convert-table} for the restrictions under which this is
5760 possible.
5761 @end table
5762 @file{table.el} is part of Emacs 22.
5763 @end table
5765 @node Conflicts,  , Cooperation, Interaction
5766 @subsection Packages that lead to conflicts with Org-mode
5768 @table @asis
5770 @cindex @file{allout.el}
5771 @item @file{allout.el} by Ken Manheimer
5772 Startup of Org-mode may fail with the error message
5773 @code{(wrong-type-argument keymapp nil)} when there is an outdated
5774 version @file{allout.el} on the load path, for example the version
5775 distributed with Emacs 21.x.  Upgrade to Emacs 22 and this problem will
5776 disappear.  If for some reason you cannot do this, make sure that org.el
5777 is loaded @emph{before} @file{allout.el}, for example by putting
5778 @code{(require 'org)} early enough into your @file{.emacs} file.
5780 @cindex @file{CUA.el}
5781 @item @file{CUA.el} by Kim. F. Storm
5782 Keybindings in Org-mode conflict with the @kbd{S-<cursor>} keys
5783 used by CUA-mode (as well as pc-select-mode and s-region-mode) to
5784 select and extend the region.  If you want to use one of these
5785 packages along with Org-mode, configure the variable
5786 @code{org-CUA-compatible}.  When set, Org-mode will move the following
5787 keybindings in org-mode files, and in the agenda buffer (but not
5788 during date selection).
5790 @example
5791 S-UP    -> M-p             S-DOWN  -> M-n
5792 S-LEFT  -> M--             S-RIGHT -> M-+
5793 S-RET   -> C-S-RET
5794 @end example
5796 Yes, these are unfortunately more difficult to remember.  If you want
5797 to have other replacement keys, look at the variable
5798 @code{org-disputed-keys}.
5799 @item @file{windmove.el} by Hovav Shacham
5800 @cindex @file{windmove.el}
5801 Also this package uses the @kbd{S-<cursor>} keys, so everything written
5802 in the paragraph above about CUA mode also applies here.
5803 @end table
5806 @node Bugs,  , Interaction, Miscellaneous
5807 @section Bugs
5808 @cindex bugs
5810 Here is a list of things that should work differently, but which I
5811 have found too hard to fix.
5813 @itemize @bullet
5814 @item
5815 If a table field starts with a link, and if the corresponding table
5816 column is narrowed (@pxref{Narrow columns}) to a width too small to
5817 display the link, the field would look entirely empty even though it is
5818 not.  To prevent this, Org-mode throws an error.  The work-around is to
5819 make the column wide enough to fit the link, or to add some text (at
5820 least 2 characters) before the link in the same field.
5821 @item
5822 Narrowing table columns does not work on XEmacs, because the
5823 @code{format} function does not transport text properties.
5824 @item
5825 Text in an entry protected with the @samp{QUOTE} keyword should not
5826 autowrap.
5827 @item
5828 When the application called by @kbd{C-c C-o} to open a file link fails
5829 (for example because the application does not exist or refuses to open
5830 the file), it does so silently.  No error message is displayed.
5831 @item
5832 Recalculating a table line applies the formulas from left to right.
5833 If a formula uses @emph{calculated} fields further down the row,
5834 multiple recalculation may be needed to get all fields consistent.
5835 @item
5836 A single letter cannot be made bold, for example @samp{*a*}.
5837 @item
5838 The exporters work well, but could be made more efficient.
5839 @end itemize
5842 @node Extensions and Hacking, History and Acknowledgments, Miscellaneous, Top
5843 @appendix Extensions, Hooks and Hacking
5845 This appendix lists extensions for Org-mode written by other authors.
5846 It also covers some aspects where users can extend the functionality of
5847 Org-mode.
5849 @menu
5850 * Extensions::                  Existing 3rd-part extensions
5851 * Dynamic blocks::              Automatically filled blocks
5852 * Special agenda views::        
5853 @end menu
5855 @node Extensions, Dynamic blocks, Extensions and Hacking, Extensions and Hacking
5856 @section Third-party extensions for Org-mode
5858 The following extensions for Org-mode have been written by other people:
5860 @table @asis
5861 @cindex @file{org-publish.el}
5862 @item @file{org-publish.el} by David O'Toole
5863 This package provides facilities for publishing related sets of Org-mode
5864 files together with linked files like images as a webpages.  It is
5865 highly configurable and can be used for other publishing purposes as
5866 well.  As of Org-mode version 4.30, @file{org-publish.el} is part of the
5867 Org-mode distribution.  It is not yet part of Emacs, however, a delay
5868 caused by the preparations for the 22.1 release.  In the mean time,
5869 @file{org-publish.el} can be downloaded from David's site:
5870 @url{http://dto.freeshell.org/e/org-publish.el}.
5871 @cindex @file{org-mouse.el}
5872 @item @file{org-mouse.el} by Piotr Zielinski
5873 This package implements extended mouse functionality for Org-mode.  It
5874 allows you to cycle visibility and to edit the document structure with
5875 the mouse.  Best of all, it provides a context-sensitive menu on
5876 @key{mouse-3} that changes depending on the context of a mouse-click.
5877 As of Org-mode version 4.53, @file{org-mouse.el} is part of the
5878 Org-mode distribution.  It is not yet part of Emacs, however, a delay
5879 caused by the preparations for the 22.1 release.  In the mean time,
5880 @file{org-mouse.el} can be downloaded from Piotr's site:
5881 @url{http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el}.
5882 @cindex @file{org-blog.el}
5883 @item @file{org-blog.el} by David O'Toole
5884 A blogging plug-in for @file{org-publish.el}.@*
5885 @url{http://dto.freeshell.org/notebook/OrgMode.html}.
5886 @cindex @file{blorg.el}
5887 @item @file{blorg.el} by Bastien Guerry
5888 Publish Org-mode files as
5889 blogs. @url{http://www.cognition.ens.fr/~guerry/blorg.html}.
5890 @cindex @file{org2rem.el}
5891 @item @file{org2rem.el} by Bastien Guerry
5892 Translates Org-mode files into something readable by
5893 Remind. @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}.
5894 @end table
5896 @node Dynamic blocks, Special agenda views, Extensions, Extensions and Hacking
5897 @section Dynamic blocks
5899 Org-mode documents can contain @emph{dynamic blocks}.  These are
5900 specially marked regions that are updated by some user-written
5901 function.  A good example for such a block is the clock table inserted
5902 by the command @kbd{C-c C-x C-r} (@pxref{Clocking work time}).
5904 Dynamic block are enclosed by a BEGIN-END structure that assigns a name
5905 to the block and can also specify parameters for the function producing
5906 the content of the block.
5908 @example
5909 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
5911 #+END:
5912 @end example
5914 Dynamic blocks are updated with the following commands
5916 @table @kbd
5917 @kindex C-c C-x C-u
5918 @item C-c C-x C-u
5919 Update dynamic block at point.
5920 @kindex C-u C-c C-x C-u
5921 @item C-u C-c C-x C-u
5922 Update all dynamic blocks in the current file.
5923 @end table
5925 Updating a dynamic block means to remove all the text between BEGIN and
5926 END, parse the BEGIN line for parameters and then call the specific
5927 writer function for this block to insert the new content.  For a block
5928 with name @code{myblock}, the writer function is
5929 @code{org-dblock-write:myblock} with as only parameter a property list
5930 with the parameters given in the begin line.  Here is a trivial example
5931 of a block that keeps track of when the block update function was last
5932 run:
5934 @example
5935 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
5937 #+END:
5938 @end example
5940 @noindent
5941 The corresponding block writer function could look like this:
5943 @lisp
5944 (defun org-dblock-write:block-update-time (params)
5945    (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
5946      (insert "Last block update at: "
5947              (format-time-string fmt (current-time)))))
5948 @end lisp
5950 If you want to make sure that all dynamic blocks are always up-to-date,
5951 you could add the function @code{org-update-all-dblocks} to a hook, for
5952 example @code{before-save-hook}.  @code{org-update-all-dblocks} is
5953 written in a way that is does nothing in buffers that are not in Org-mode.
5955 @node Special agenda views,  , Dynamic blocks, Extensions and Hacking
5956 @section Special Agenda Views
5958 Org-mode provides a special hook that can be used to narrow down the
5959 selection made by any of the agenda views.  You may specify a function
5960 that is used at each match to verify if the match should indeed be part
5961 of the agenda view, and if not, how much should be skipped.
5963 Let's say you want to produce a list of projects that contain a WAITING
5964 tag anywhere in the project tree.  Let's further assume that you have
5965 marked all tree headings that define a project with the todo keyword
5966 PROJECT.  In this case you would run a todo search for the keyword
5967 PROJECT, but skip the match unless there is a WAITING tag anywhere in
5968 the subtree belonging to the project line.
5970 To achieve this, you must write a function that searches the subtree for
5971 the tag.  If the tag is found, the function must return @code{nil} to
5972 indicate that this match should not be skipped.  If there is no such
5973 tag, return the location of the end of the subtree, to indicate that
5974 search should continue from there.
5976 @lisp
5977 (defun my-skip-unless-waiting ()
5978   "Skip trees that are not waiting"
5979   (let ((subtree-end (save-excursion (org-end-of-subtree t))))
5980     (if (re-search-forward ":WAITING:" subtree-end t)
5981         nil          ; tag found, do not skip
5982       subtree-end))) ; tag not found, continue after end of subtree
5983 @end lisp
5985 Furthermore you must write a command that uses @code{let} to temporarily
5986 put this function into the variable @code{org-agenda-skip-function},
5987 sets the header string for the agenda buffer, and calls the todo-list
5988 generator while asking for the specific TODO keyword PROJECT.  The
5989 function must also accept one argument MATCH, but it can choose to
5990 ignore it@footnote{MATCH must be present in case you want to define a
5991 custom command for producing this special list.  Custom commands always
5992 supply the MATCH argument, but it can be empty if you do not specify it
5993 while defining the command(@pxref{Custom agenda
5994 views}).} (as we do in the example below).  Here is the example:
5996 @lisp
5997 (defun my-org-waiting-projects (&optional match)
5998   "Produce a list of projects that contain a WAITING tag.
5999 MATCH is being ignored."
6000   (interactive)
6001   (let ((org-agenda-skip-function 'my-skip-unless-waiting)
6002         (org-agenda-overriding-header "Projects waiting for something: "))
6003     ;; make the list
6004     (org-todo-list "PROJECT")))
6005 @end lisp
6008 @node History and Acknowledgments, Index, Extensions and Hacking, Top
6009 @appendix History and Acknowledgments
6010 @cindex acknowledgments
6011 @cindex history
6012 @cindex thanks
6014 Org-mode was borne in 2003, out of frustration over the user interface
6015 of the Emacs outline-mode.  All I wanted was to make working with an
6016 outline tree possible without having to remember more than 10 commands
6017 just for hiding and unhiding parts of the outline tree, and to allow to
6018 restructure a tree easily.  Visibility cycling and structure editing
6019 were originally implemented in the package @file{outline-magic.el}, but
6020 quickly moved to the more general @file{org.el}.  TODO entries, basic
6021 time stamps, and table support were added next, and highlight the two
6022 main goals that Org-mode still has today: To create a new,
6023 outline-based, plain text mode with innovative and intuitive editing
6024 features, and to incorporate project planning functionality directly
6025 into a notes file.
6027 Since the first release, hundreds of emails to me or on
6028 @code{emacs-orgmode@@gnu.org} have provided a constant stream of bug
6029 reports, feedback, new ideas, and sometimes patches and add-on code.
6030 Many thanks to everyone who has helped to improve this package.  I am
6031 trying to keep here a list of the people who had significant influence
6032 in shaping one or more aspects of Org-mode.  The list may not be
6033 complete, if I have forgotten someone, please accept my apologies and
6034 let me know.
6036 @itemize @bullet
6038 @item
6039 @i{Thomas Baumann} contributed the code for links to the MH-E email
6040 system.
6041 @item
6042 @i{Alex Bochannek} provided a patch for rounding time stamps.
6043 @item
6044 @i{Charles Cave}'s suggestion sparked the implementation of templates
6045 for Remember.
6046 @item
6047 @i{Pavel Chalmoviansky} influenced the agenda treatment of items with
6048 specified time.
6049 @item
6050 @i{Gregory Chernov} patched support for lisp forms into table
6051 calculations and improved XEmacs compatibility, in particular by porting
6052 @file{nouline.el} to XEmacs.
6053 @item
6054 @i{Sacha Chua} suggested to copy some linking code from Planner.
6055 @item
6056 @i{Eddward DeVilla} proposed and tested checkbox statistics.
6057 @item
6058 @i{Kees Dullemond} inspired the use of narrowed tabled columns.
6059 @item
6060 @i{Christian Egli} converted the documentation into TeXInfo format,
6061 patched CSS formatting into the HTML exporter, and inspired the agenda.
6062 @item
6063 @i{Nic Ferrier} contributed mailcap and XOXO support.
6064 @item
6065 @i{John Foerch} figured out how to make incremental search show context
6066 around a match in a hidden outline tree.
6067 @item
6068 @i{Niels Giessen} had the idea to automatically archive DONE trees.
6069 @item
6070 @i{Bastien Guerry} provided extensive feedback and some patches, and
6071 translated David O'Toole's tutorial into French.
6072 @item
6073 @i{Kai Grossjohann} pointed out key-binding conflicts with other packages.
6074 @item
6075 @i{Shidai Liu} (``Leo'') provided extensive feedback and some patches.
6076 @item
6077 @i{Leon Liu} asked for embedded LaTeX and tested it.
6078 @item
6079 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler
6080 happy.
6081 @item
6082 @i{Todd Neal} provided patches for links to Info files and elisp forms.
6083 @item
6084 @i{Tim O'Callaghan} suggested in-file links, search options for general
6085 file links, and TAGS.
6086 @item
6087 @i{Takeshi Okano} translated the manual and David O'Toole's tutorial
6088 into Japanese.
6089 @item
6090 @i{Oliver Oppitz} suggested multi-state TODO items.
6091 @item
6092 @i{Scott Otterson} sparked the introduction of descriptive text for
6093 links, among other things.
6094 @item
6095 @i{Pete Phillips} helped during the development of the TAGS feature, and
6096 provided frequent feedback.
6097 @item
6098 @i{T.V. Raman} reported bugs and suggested improvements.
6099 @item
6100 @i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
6101 control.
6102 @item
6103 @i{Kevin Rogers} contributed code to access VM files on remote hosts.
6104 @item
6105 @i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
6106 conflict with @file{allout.el}.
6107 @item
6108 @i{Jason Riedy} sent a patch to fix a bug with export of TODO keywords.
6109 @item
6110 @i{Philip Rooke} created the Org-mode reference card and provided lots
6111 of feedback.
6112 @item
6113 @i{Christian Schlauer} proposed angular brackets around links, among
6114 other things.
6115 @item
6116 Linking to VM/BBDB/GNUS was inspired by @i{Tom Shannon}'s
6117 @file{organizer-mode.el}.
6118 @item
6119 @i{Daniel Sinder} came up with the idea of internal archiving by locking
6120 subtrees.
6121 @item
6122 @i{Dale Smith} proposed link abbreviations.
6123 @item
6124 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
6125 chapter about publishing.
6126 @item
6127 @i{J@"urgen Vollmer} contributed code generating the table of contents
6128 in HTML output.
6129 @item
6130 @i{Chris Wallace} provided a patch implementing the @samp{QUOTE}
6131 keyword.
6132 @item
6133 @i{David Wainberg} suggested archiving, and improvements to the linking
6134 system.
6135 @item
6136 @i{John Wiegley} wrote @file{emacs-wiki.el} and @file{planner.el}.  The
6137 development of Org-mode was fully independent, and both systems are
6138 really different beasts in their basic ideas and implementation details.
6139 I later looked at John's code, however, and learned from his
6140 implementation of (i) links where the link itself is hidden and only a
6141 description is shown, and (ii) popping up a calendar to select a date.
6142 @item
6143 @i{Carsten Wimmer} suggested some changes and helped fix a bug in
6144 linking to GNUS.
6145 @item
6146 @i{Roland Winkler} requested additional keybindings to make Org-mode
6147 work on a tty.
6148 @item
6149 @i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks
6150 and contributed various ideas and code snippets.
6151 @end itemize
6154 @node Index, Key Index, History and Acknowledgments, Top
6155 @unnumbered Index
6157 @printindex cp
6159 @node Key Index,  , Index, Top
6160 @unnumbered Key Index
6162 @printindex ky
6164 @bye
6166 @ignore
6167    arch-tag: 7893d1fe-cc57-4d13-b5e5-f494a1bcc7ac
6168 @end ignore